NAME

sxsnxbgen -- Create a Non-X-ray Background (NXB) spectrum for SXS

USAGE

sxsnxbgen infile ehkfile regfile innxbfile innxbehk innxbhk outpifile

DESCRIPTION

'sxsnxbgen' generates a PI spectrum of the non-X-ray background (NXB) for an SXS 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.

'sxsnxbgen' uses the following inputs: (a) the science SXS event file for which the NXB spectrum is calculated ('sxsnxbgen' 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 SXS source region. The region may be specified in RAW, DET, FOC, or SKY coordinates (see 'regmode' parameter). For the SXS it is possible to select the region using a list of SXS pixels (see 'pixels' parameters); in this case the user must set 'regfile=NONE'.

'sxsnxbgen' 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. 'sxsnxbgen' 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. NXB spectra are extracted based on the distribution of COR that are present in the science event data and weighted by the ratio of the science exposure time in that bin to the total science exposure time. The NXB output spectrum is then the sum of these weighted spectra. Note that if the NXB spectrum is calculated using a pixel list rather than a regionfile, the BACKSCAL keyword is set to -1 and would need to be adjusted according to the pixel list of the source spectral file if used as background file.

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 SXS. The 'sortbin' parameter specifies the COR value bin boundaries that are used in the NXB selection.

'sxsnxbgen' 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. If regfile is set to NONE, the tool uses the pixels parameter to specify the extraction region.

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

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. If regfile is set to NONE, then this parameter is ignored and pixels is used to define the region.

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

(pixels = 1,2,3,12) [string]
Pixels for sorting NXB data. This is a list of SXS pixels used to filter the NXB data instead of a region. The list of pixels can be comma-separated, or a range can be specified using "-" or ":". The following are equivalent: "1,2,3,12", "1-3,12", and "1:3,12". If pixels="-", then all pixels are used. This parameter is ignored unless regfile is set to NONE.

(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 sxsnxbgen with a restrictive COR range, to reduce the background for a low-surface-brightness target.
    sxsnxbgen infile=in.evt ehkfile=ehk.fits regfile=target_sky.reg innxbfile=nxb.fits innxbehk=nxb.ehk outpifile=target_sxsnxb.pi sortbin="6,7,8,9,10,11,12,13,99"
    
  2. Run sxsnxbgen using a pixel list instead of a region file.
    sxsnxbgen infile=target.evt ehkfile=ehk.fits regfile=NONE innxbfile=nxb.fits innnxbehk=nxb.ehk outpifile=target_sxsnxb.pi pixels="1:3,12"
    

SEE ALSO

sxinxbgen, hxinxbgen

LAST MODIFIED

February 3, 2016