NAME

hxinxbgen -- Create a Non-X-ray Background (NXB) spectrum for HXI

USAGE

hxinxbgen infile ehkfile regfile innxbfile innxbehk innxbhk outpifile

DESCRIPTION

'hxinxbgen' 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.

'hxinxbgen' 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, and the pointing, as well as 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'); the NXB EHK file ('innxbehk'); (d) 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).

'hxinxbgen' 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. 'hxinxbgen' 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 Cut-Off 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 Cut-Off Rigidity values. 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.

'hxinxbgen' outputs the weighted NXB PI spectrum ('outpifile'); and optionally, 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 [filename]
Input event file. Header keywords are read from the EVENTS extension, and the GTI extension is used to construct the weighting histogram.

ehkfile [filename]
Input EHK file. This file must contain the column specified in sortcol used to weight the output NXB spectrum.

regfile [filename]
Input region file in DS9 format. The region should be in coordinates specified by regmode.

innxbfile [filename]
Input NXB event file used to construct the NXB spectrum.

inpsefile [filename]
Input NXB pseudo event file used to correct the NXB spectrum calculated using the NXB event file.

innxbehk [filename]
Input NXB EHK file. This file must contain the column specified in sortcol used to weight the output NXB spectrum.

outpifile [filename]
Output PI spectrum file name.

(outehkfile = NONE) [filename]
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]
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]
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]
Region mode. Specifies the coordinate system used by regfile. Allowed systems are SKY, DET, FOC, and RAW. If this is SKY, then 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]
Column for sorting NXB data by COR. This column must exist in the EHK files, and must be either COR, COR2, COR3, or CORTIME.

(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 is excluded. This range should match any COR filtering performed on the science data. List must be comma-separated 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 since SAA [s]. Times where tsaabin is below the minimum or above the maximum value is excluded. This range should match any COR filtering performed on the science data. List must be comma-separated in increasing numerical order.

(expr = NONE) [string]
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]
Delete intermediate files ([yes]/no).

(buffer = -1) [integer]
Rows to buffer (-1=auto, 0=none, >0=numrows).

(clobber = no) [boolean]
Overwrites the existing output file if set to yes (yes/[no]).

(chatter = 1) [integer]
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]
Log filename. If set to DEFAULT uses the name of the task and, if preceded by '!', overwrite the file if it exists. If set to NONE no log file is created.

(debug = no) [boolean]
Diagnostic output is printed out on the screen if set to yes (yes/[no]).

(history = yes) [boolean]
Records tool parameters in HISTORY ([yes]/no).

(mode = ql) [string ql|hl|q]
Mode to query the parameter file. Acceptable values include: "ql" (query and learn/remember), "hl" (hidden and learn/remember), "q" (query but don't remember), "h" (hidden).

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

sxinxbgen, sxsnxbgen

LAST MODIFIED

February 3, 2016