NAME

USAGE

DESCRIPTION

The task 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 can be used in spectral fitting (e.g. with XSPEC) to subtract or model effects of the particle background from the science data.

The sxinxbgen task uses the following inputs: (a) the science SXI event file for which the NXB spectrum is to be calculated (sxinxbgen 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) the NXB HK file ('innxbhk'), and (f) 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). The task 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). The files described in (c) to (e) can be obtained by anonymous FTP. The task hitomiversion can be run to display the FTP location and names of the required files. The file 'innxbhk' is also in the calibation database and is retrieved by sxinxbgen if the parameter 'innxbhk' is set to CALDB.

If 'apply_sxipi=yes', sxinxbgen first runs the task sxipi to apply the latest calibration to the NXB events before filtering and extracting the spectrum. The task sxipi requires an SXI housekeeping (HK) file ('innxbhk') suitable for the NXB event list. The sxipi parameters 'hkext', 'hkcolstem', 'hkvideoid', 'vtevnoddfile', 'chtrailfile', 'ctifile', 'spthfile', 'gainfile', 'patternfile', 'startcol', 'evnoddcor', 'badpixopt', 'evtthre', 'deltatime', 'randomize', and 'seed' may be set within sxinxbgen. The task sxipi is actually run twice as it is in the pipeline: first, it applies the charge trail and CTI corrections to determine a preliminary event GRADE; and second, it calculates a GRADE-dependent CTI correction and applies that along with the other corrections to finally recalculate PI. See the sxipi help file for full details of this process and the sxipi parameters (listed above) that can be set with sxinxbgen.

Next, sxinxbgen filters the NXB event data on the region file. This selection is done using DET coordinates; the task internally transforms the coordinates if the region file is not already provided in DET coordinates. 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 task 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 (defined in the code by a rate greater than 1.5 cts/s). 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. NXB spectra are extracted based on the distribution of COR 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 cutoff rigidity arrays. Empirically derived values are stored in the columns COR, COR2, COR3, and calculated values are stored 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.

The task sxinxbgen outputs the weighted NXB PI spectrum ('outpifile'), (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 by the parameter 'regfile' and the source region file by the parameter 'regfile2'. 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. The name of the file and its location (accessible by anonymous FTP) can displayed by running the task hitomiversion.

innxbehk [filename]

Input NXB EHK file. This file must contain the column specified in 'sortcol' used to weight the output NXB spectrum. The name of the file and its location (accessible by anonymous FTP) can displayed by running the task hitomiversion.

innxbhk [filename CALDB|file name]

Input NXB HK file. Contains HK data needed to reprocess the NXB data with sxipi, as specified by the 'hkext', 'hkcolstem', and 'hkvideoid' parameters. If 'innxbhk=CALDB', the file is retrieved from the calibration database.

outpifile [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 input GTI file. 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' and 'regfile2'.

(timefirst = 150) [integer]

Number of days before the science observation to use for extracting NXB events.

(timelast = 150) [integer]

Number of days after the science observation to use for extracting NXB events.

(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 NONE|expression]

Additional expression to select good events, to be 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 yes|no]

If 'runlcurve' is set to yes, a light curve is extracted in the 12-24 keV range from the NXB data and is used to exclude times of high background; if set to no, lightcurve filtering is not performed.

(apply_sxipi = yes) [boolean yes|no]

If 'apply_sxipi' is set to yes, recalculate PI using sxipi. If 'apply_sxipi' is set to no, do not run sxipi.

(hkext = HK_SXI_USR_USER_HK1) [string]

Name of the HK extension in the HK file 'innxbhk' from which the video temperature is read. This parameter is ignored if 'apply_sxipi' is set to no.

(hkcolstem = SXI_USR_HKTBL_) [string]

Column name stem where the video temperature is recorded in the HK file. This parameter is ignored if 'apply_sxipi' is set to no.

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

Video card IDs used for the even-odd correction for CCD1, CCD2, CCD3, and CCD4. This parameter must consist of a comma-separated list of 4 characters A or B. This parameter is ignored if 'apply_sxipi' is set to no.

(vtevnoddfile = CALDB) [filename CALDB|file name]

Name of even-odd video temperature correction file. If set to CALDB, the file is read from the calibration database. This parameter is ignored if 'apply_sxipi' is set to no.

(chtrailfile = CALDB) [filename CALDB|file name]

Name of charge trail correction file. If set to CALDB, the file is read from the calibration database. This parameter is ignored if 'apply_sxipi' is set to no.

(ctifile = CALDB) [filename CALDB|file name]

Name of CTI correction file. If set to CALDB, the file is read from the calibration database. This parameter is ignored if 'apply_sxipi' is set to no.

(spthfile = CALDB) [filename CALDB|file name]

Name of split threshold values file. If set to CALDB, the file is read from the calibration database. This parameter is ignored if 'apply_sxipi' is set to no.

(gainfile = CALDB) [filename CALDB|file name]

Name of gain file for PHA to PI conversion. If 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 CALDB|file name]

Name of file for grade hit pattern. If set to CALDB, the file is read from the calibration database.

(startcol = PHAS) [string PHAS|PHAS_EVENODD|PHAS_TRAILCORR|PHAS_CTICORR|PHA]

The column name with which to start the corrections. Note that PHAS_EVENODD, PHAS_TRAILCORR, and PHAS_CTICORR are only present if the event file has already been processed with sxipi with 'debugcol=yes'. The 'startcol' parameter is ignored if 'apply_sxipi' is set to no.

(evnoddcor = yes) [boolean yes|no]

If set to yes, the even-odd correction is enabled. This parameter is ignored if 'apply_sxipi' is set to no.

(badpixopt = 2) [integer 1|2|3]

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 not flagged in the 3x3 event island and all PHAS values are used to grade and calculate the summed PHA; this method is 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 calculated 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. Then, 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. The 'badpixopt' 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 [s] 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 to the STATUS column. This parameter is ignored if 'apply_sxipi' is set to no.

(randomize = yes) [boolean yes|no]

If set to yes, randomization is used to convert the input integer PHAS or PHA column to floating point. If 'startcol' is PHAS_EVENODD, PHAS_TRAILCORR, or PHAS_CTICORR, this parameter is ignored, since those columns are floating point values. This parameter is also ignored, regardless of the value of 'startcol', if 'apply_sxipi' is set to 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 NONE|file name]

Input region file for the source in DS9 format, if the source and background regions are different. This second region allows for the correction for the ACT coordinates. By default this parameter is set to NONE, e.g. background and source region are the same. If 'regfile2' is the same as the file provided in 'regfile', there is no ACT correction. The region should be specified in coordinates specified by 'regmode'.

(slope = 0.2121 [double])

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

(constant = 297.7 [double])

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

(cleanup = yes) [boolean yes|no]

Delete temporary files.

(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 task parameters in HISTORY.

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 25, 2024