NAME

USAGE

DESCRIPTION

The hxinxbgen task generates a PI spectrum of the non-X-ray background (NXB) for an HXI observation. The NXB spectrum is calculated from a calibration file containing night Earth data, when X-rays are blocked from the detector's view, accumulated over a period of time. This spectrum is used in spectral fitting (e.g., with xspec) to subtract the effects of the particle background from the science data.

The hxinxbgen task uses the following inputs: (a) the science HXI event file for which the NXB spectrum is calculated (hxinxbgen reads and uses information in the header keywords related to the time of the observation, the pointing, and the GTI); (b) the extended housekeeping (EHK) file ('ehkfile') containing information on the spacecraft orbit during the observation; (c) the NXB event file (parameter 'innxbfile'); (d) the NXB EHK file ('innxbehk'); (e) an NXB pseudo event file; and (f) a DS9-format region file ('regfile') describing the spectral extraction HXI source region. The region may be specified in RAW, DET, FOC, or SKY coordinates (see 'regmode' parameter). The files described in (c), (d), and (e) can be obtained by anonymous FTP. The task hitomiversion can be run to display the FTP location of the required files.

The hxinxbgen task first filters the NXB event data on the region file. This selection is done using DET coordinates and the task internally transforms the coordinates if the region file is not provided in DET. The task then creates a GTI to apply to the NXB event and NXB EHK data using the 'timefirst' and 'timelast' parameters. These extend the NXB GTI beyond that of the science data to ensure sufficient statistics in the output NXB spectrum. A baseline default value, based on experience with previous missions, is to have a window of 300 days centered on the observation. The hxinxbgen task then screens the NXB events using the same criteria used for selection of events in the science data (see 'expr' parameter). Finally, the NXB spectrum is produced from NXB events within this GTI that are selected and weighted based on the geomagnetic cutoff rigidity (COR), an estimate of the shielding provided by the Earth's magnetic field against impinging charged particles, and on the time since the last passage through the South Atlantic Anomaly (SAA), an area of enhanced background. NXB spectra are extracted based on the distributions of COR and T_SAA that are present in the science event data. For each science event data T_SAA bin, hxinxbgen extracts spectra from each COR bin in the science data filtered on that combination of T_SAA and COR. The spectrum is weighted by the ratio of the science exposure time in that combination of T_SAA and COR bin to the total science exposure time. The NXB output spectrum is then the sum of these weighted spectra.

The EHK file contains several cutoff rigidity functions. Empirically derived values are stored in the columns COR, COR2, or COR3; and a calculated value in the CORTIME column. The choice of COR to use is specified by the 'sortcol' parameter. COR3 is the recommended table to use for HXI. The 'sortbin' parameter specifies the COR value bin boundaries that are used in the NXB selection. The EHK file also contains several values of the time since SAA passage based on the longitude and latitude of the vertices of polygons that define the SAA for various instruments. The choice of T_SAA to use is specified by the 'tsaacol' parameter. The 'tsaabin' parameter specifies the T_SAA value bin boundaries that are used in the NXB selection. Times with COR below the minimum or above the maximum value in 'sortbin', or T_SAA below the minimum or above the maximum in 'tsaabin', are excluded from the NXB data. Therefore, these ranges should match any COR and T_SAA filtering performed on the science data.

The hxinxbgen task outputs the weighted NXB PI spectrum ('outpifile'). Optional outputs include the EHK file corresponding to the science GTI ('outehkfile'); the calibrated, screened, and time-filtered NXB event list ('outnxbfile'); and the NXB EHK file corresponding to that NXB file ('outnxbehk').

PARAMETERS

infile = in.fits [filename]

Input event file. Header keywords are read from the EVENTS extension, and the GTI extension is used to construct the weighting histogram.

ehkfile = ehk.fits [filename]

Input EHK file. This file must contain the column specified in 'sortcol' used to weight the output NXB spectrum.

regfile = ds9.reg [filename]

Input region file in DS9 format. The region should be in coordinates specified by' regmode'.

innxbfile = nxb.fits [filename]

Input NXB event file used to construct the NXB spectrum.

inpsefile = nxb.pse [filename]

Input NXB pseudo event file used to correct the NXB spectrum calculated using the NXB event file.

innxbehk = nxb.ehk [filename]

Input NXB EHK file. This file must contain the column specified in 'sortcol' used to weight the output NXB spectrum.

outpifile = pi.out [filename]

Output PI spectrum file name.

(outehkfile = NONE) [filename NONE|file name]

Output EHK file. Contains the EHK data for only the times in the 'infile' GTI. If the parameter is set to NONE, this file is not created.

(outnxbfile = NONE) [filename NONE|file name]

Output NXB file. Contains the filtered NXB events used in the output spectrum. If the parameter is set to NONE, this file is not created.

(outnxbehk = NONE) [filename NONE|file name]

Output NXB EHK file. Contains the EHK data for only the times covered by the filtered NXB events. If the parameter is set to NONE, this file is not created.

(regmode = SKY) [string SKY|DET|FOC|RAW]

Region mode. Specifies the coordinate system used by 'regfile'. If this is SKY, 'regfile' should be in X, Y coordinates.

(timefirst = 150) [integer]

Days before the science observation used to extract NXB.

(timelast = 150) [integer]

Days after the science observation used to extract NXB.

(sortcol = COR3) [string COR|COR2|COR3|CORTIME]

Column for sorting NXB data by COR. This column must exist in the EHK files.

(sortbin = 0,4,5,6,7,8,9,10,11,12,13,99) [string]

Bin boundaries for sorting NXB data by COR. Times where 'sortcol' is below the minimum, or above the maximum value, are excluded. This range should match any COR filtering performed on the science data. List must be comma-separated and in increasing numerical order.

(tsaacol = T_SAA_HXI1) [string]

Column for sorting NXB data by time since SAA. This column must exist in the EHK files.

(tsaabin = 500,1000,2000,5000) [string]

Bin boundaries for sorting NXB data time [s] since SAA. Times where 'tsaabin' is below the minimum, or above the maximum value, are excluded. This range should match any COR filtering performed on the science data. List must be comma-separated and in increasing numerical order.

(expr = NONE) [string NONE|expression]

Additional expression to select good events applied to the NXB event list. This should match the screening of the science data. If the parameter is set to NONE, no expression is used.

(cleanup = yes) [boolean yes|no]

Delete temporary files if 'cleanup=yes'.

(clobber = no) [boolean yes|no]

Overwrites the existing output file if set to yes.

(chatter = 2) [integer 0|1|2|3]

Chatter level for output. Set to 0 to suppress output, or to 1, 2, or 3 for increasing the chatter of the output.

(logfile = !DEFAULT) [string DEFAULT|NONE|file name]

Log file name. If set to DEFAULT, uses the name of the task and, if preceded by "!", overwrites the file if it exists. If set to NONE, no log file is created.

(debug = no) [boolean yes|no]

Diagnostic output is printed to the screen if set to yes.

(history = yes) [boolean yes|no]

Records tool parameters in HISTORY.

EXAMPLES

1. Run hxinxbgen with a restrictive COR range to reduce the background for a low surface-brightness target.

      hxinxbgen infile=target.evt ehkfile=ehk.fits regfile=target_sky.reg innxbfile=nxb.fits innxbehk=nxb.ehk \
         outpifile=target_hxinxb.pi sortbin="6,7,8,9,10,11,12,13,99"
   

SEE ALSO

LAST MODIFIED