NAME

USAGE

DESCRIPTION

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

'sxinxbgen' uses the following inputs: (a) the science SXI event file for which the NXB spectrum is calculated ('sxinxbgen' 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 SXI source region. The region may be specified in RAW, DET, FOC, or SKY coordinates (see 'regmode' parameter). 'sxinxbgen' includes options for recalculating the PI values in the input NXB event file (see 'apply_sxipi' parameter), and for excluding times of high background by extracting a light curve from the NXB data (see 'runlcurve' parameter).

If 'apply_sxipi=yes', 'sxinxbgen' first runs the tool 'sxipi' to apply the latest calibration to the NXB events before filtering and extracting the spectrum. 'sxipi' requires an SXI housekeeping (hk) file for the observation (see 'innxbhk' parameter). The 'sxipi' parameters 'hkfile', 'hkext', 'hkcolstem', 'hkvideoid', 'vtevnoddfile', 'chtrailfile', 'ctifile ', 'spthfile', 'gainfile', 'patternfile', 'startcol', 'evnoddcor', 'badpixopt', 'evtthre', 'deltatime', 'randomize', and 'seed' may be set within 'sxigainfit' (see 'sxipi' for details).

'sxinxbgen' next 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. 'sxinxbgen' then screens the NXB events using the same criteria used for selection of events in the science data (see 'expr' parameter). If 'runlcurve=yes', a light curve is extracted in the 12-24 keV range from the NXB data and used at this point to remove times of high background. 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.

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

'sxinxbgen' 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').

If the background region file is different from the source region, 'sxinxbgen' applies a correction due to the ACTY background dependence. In this case the background region file must be provided in the paramater 'region' and the source region in the parameter 'region2'. If the region file for source and background are the same this correction is not needed.

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.

innxbehk [filename]

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

innxbhk [filename]

Input NXB HK file. Contains HK data needed to reprocess the NXB data with sxipi, as specified by the hkext, hkcolstem, and hkvideoid parameters.

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. 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. List must be comma-separated in increasing numerical order. The range should match any COR filtering performed on the science data.

(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.

(runlcurve = no) [boolean]

If runlcurve is set to yes a light curve is extracted in the 12-24 keV range from the NXB data and used to exclude times of high background; if set to no lightcurve filtering is not conducted (yes/[no]).

(apply_sxipi = yes) [boolean]

If apply_sxipi is set to yes recalculate PI using sxipi. If apply_sxsipi is set to no, do not run sxipi ([yes]/no).

(hkext = HK_SXI_USR_USER_HK1) [string]

HK extension with video temperatures. This parameter is ignored if apply_sxipi is set to no.

(hkcolstem = SXI_USR_HKTBL_) [string]

Column template for video temperatures. This parameter is ignored if apply_sxipi is set to no.

(hkvideoid = A,B,B,B) [string]

Video card ID for gain correction of CCD1-4. This parameter is ignored if apply_sxipi is set to no.

(vtevnoddfile = CALDB) [filename]

Input video evenodd file. If the parameter is set to CALDB, the file is read from the calibration database. If the parameter is set to NONE this file is not used. This parameter is ignored if apply_sxipi is set to no.

(chtrailfile = CALDB) [filename]

Input charge trail correction file. If the parameter is set to CALDB, the file is read from the calibration database. If the parameter is set to NONE this file is not used. This parameter is ignored if apply_sxipi is set to no.

(ctifile = CALDB) [filename]

Input CTI correction file. If the parameter is set to CALDB, the file is read from the calibration database. If the parameter is set to NONE this file is not used. This parameter is ignored if apply_sxipi is set to no.

(spthfile = CALDB) [filename]

Input split threshold file. If the parameter is set to CALDB, the file is read from the calibration database. If the parameter is set to NONE this file is not used. This parameter is ignored if apply_sxipi is set to no.

(gainfile = CALDB) [filename]

Input gain correction file. If the parameter is set to CALDB, the file is read from the calibration database. This parameter is ignored if apply_sxipi is set to no.

(patternfile = CALDB) [filename]

Input grade hit pattern file. If the parameter is set to CALDB, the file is read from the calibration database. If the parameter is set to NONE this file is not used. This parameter is ignored if apply_sxipi is set to no.

(startcol = PHAS) [string]

The column name with which to start the corrections. The allowed values are PHAS, PHAS_EVENODD, PHAS_TRAILCORR, PHAS_CTICORR, or PHA. All but PHAS and PHA are only present if the event file has already been processed with sxipi with debugcol=yes. This parameter is ignored if apply_sxipi is set to no.

(evnoddcor = yes) [boolean]

If set to yes, the even-odd correction is enabled. This parameter is ignored if apply_sxipi is set to no ([yes]/no).

(badpixopt = 2) [integer]

Option specifying how to process events that contain bad pixels. Must be an integer in the range 1-3. If set to 1, bad pixels are ignored in the 3x3 and all PHAS values are used to grade and calculate the summed PHA. This is the method used by the Suzaku XIS. If set to 2, the task applies PHAS_MASK to mask out bad pixels in the 3x3 and set them to NULL. Grading and PHA summation are then done normally, effectively ignoring these pixels. If set to 3, the task applies PHAS_MASK to mask out bad pixels in the 3x3 and set them to NULL. The GRADE, PHA, and PI values are also set to NULL and these are considered bad events. This is the most conservative option, ensuring better fidelity at the expense of fewer counts. This parameter is ignored if apply_sxipi is set to no.

(evtthre = DEFAULT) [string]

Event threshold value. If set to DEFAULT, the task uses the values in the infile header keyword EVENTTHR, which contains one value for each CCD_ID and SEGMENT combination. Otherwise, a single numerical floating-point value can be specified, and is used for all CCD_IDs and SEGMENTs. This parameter is ignored if apply_sxipi is set to no.

(deltatime = 8) [integer]

Acceptable time gap to search for video temperature in HK file. If a time entry is not found within this deltatime of the event, then an error flag is assigned in the STATUS. This parameter is ignored if apply_sxipi is set to no.

(randomize = yes) [boolean]

If set to yes, PHA is calculated from PHAS using decimal randomization. If startcol is PHAS_EVENODD, PHAS_TRAILCORR, or PHAS_CTICORR, this parameter is ignored, since those columns are floating point values. This parameter is ignored if apply_sxipi is set to no (yes/[no]).

(seed = -1457) [integer]

Random number generator seed; uses system time for seed=0. This parameter is ignored if apply_sxipi is set to no.

regfile2 [filename]

Input region file for the source in DS9 format. This second region allows to make the correction for the ACT coordinates. By default is NONE, e.g. bakground and source region are the same. If the 'regfile2' file is the same of the file provided in 'regfile' the ACT correction has not effect. The region should be in coordinates specified by regmode.

(slope [filename])

Input slope for the backgroud dependence on ACTY. This value is calculated from calibration and it is recommended not to change.

(constant [filename])

Input constant for the backgroud dependence on ACTY. This value is calculated from calibration and it is recommended not to change.

(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 sxinxbgen with a restrictive COR range, to reduce the background for a low-surface-brightness target.

   sxinxbgen infile=target.evt ehkfile=ehk.fits regfile=target_sky.reg innxbfile=nxb.fits innxnehk=nxb.ehk innxbhk=nxb.hk outpifile=target_sxinxb.pi \
   sortbin="6,7,8,9,10,11,12,13,99"
   

2. Run sxinxbgen using a region in DET coordinates, and excluding the calibration source regions.

   sxinxbgen infile=target.evt ehkfile=ehk.fits regfile=target_det.reg innxbfile=nxb.fits innxbehk=nxb.ehk innxbhk=nxb.hk outpifile-target_sxinxb.pi regmode=DET \
   expr="STATUS[2]==b0"
   

3. Run sxinxbgen without applying the most recent SXI calibration.

   sxinxbgen infile=target.evt ehkfile=ehk.fits regfile=target_sky.reg innxbfile=nxb.fits innxbehk=nxb.ehk innxbhk=nxb.hk outpifile-target_sxinxb.pi apply_sxipi=no
   

SEE ALSO

sxsnxbgen, hxinxbgen, sxipi, ftselect

LAST MODIFIED

February 3, 2016