NAME

USAGE

DESCRIPTION

The xtdnxbgen task generates a PI spectrum of the Non-X-ray Background (NXB) for an Xtend observation. The NXB spectrum is calculated from 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 model effects of the particle background with the science data.

The xtdnxbgen task uses the following required inputs: (a) the science Xtend event file ('infile') for which the NXB spectrum is to be calculated (xtdnxbgen reads and uses instrument configuration header keywords and the GTI); (b) the extended housekeeping (EHK) file ('ehkfile') containing information on the spacecraft orbit during the observation; (c) a DS9-format region file ('regfile') describing the NXB spectral extraction region; and (d) the output NXB spectrum file ('outpifile').

In the default usage, xtdnxbgen will use a remote database of NXB event data to construct the spectrum. The header keywords from 'infile' are compared with a look-up table in the database to determine appropriate NXB data to use based on the instrument configuration, along with the requested time window of night Earth observations specified by 'timefirst' and 'timelast'. Based on experience with previous missions, a window of 300 days centered on the science observation provides a balance between achieving sufficient statistics in the NXB spectrum and sampling a short enough time that Solar cycle variations are minimized. This may depend on the goals of the science observation, however. The 'exclude_keys' parameter can be used to specify header keywords to ignore when compiling NXB data to retrieve from the database.

Selected event lists and supporting files are downloaded locally, and if 'apply_xtdtools=yes', the event lists are reprocessed to apply the most recent calibration available in the user's CalDB. This processing first runs xtdpi to reassign PI and grade to each event; and then runs xtdflagpix to reapply any event flagging that may have changed due to the xtdpi run. In addition, the user can specify a custom 'bad_status' for xtdflagpix to match any non-standard processing of the science data. See the help files for xtdpi and xtdflagpix for more information on these tools. At the end of reprocessing, the event lists are screened to produce cleaned event lists. If 'outnxbfile' specifies a filename, then a single processed, cleaned NXB event file will be output, useful to avoid long reprocessing on further runs of xtdnxbgen. Likewise if 'outnxbehk' is specified, the combined NXB EHK file from the database will be saved locally.

The remote database is used if 'database=REMOTE', accessing the URL provided in 'db_location'. Instead, a local on-disk mirror of the database can be used if 'database=LOCAL', with the full pathname provided in 'db_location'. This database must follow the same directory structure as the remote one, including the look-up table, and is intended for work off-line or with poor connectivity. As a third option, a single input NXB event list can be specified with 'innxbfile', requiring an EHK file specified with 'innxbehk'. These files can be saved from previous runs of xtdnxbgen with 'outnxbfile' and 'outnxbehk', but reprocessing with 'apply_xtdtools' cannot be performed in this usage, only on the NXB database input. Note that 'innxbfile' and 'innxbehk' must both be 'NONE' to use either a remote or local database. This is the default usage.

The task then filters the NXB event data based on the region file 'regfile', and performs any screening specified by 'expr'. This screening is optional and should match any additional filtering that was performed on the science event data. 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. CORTIME is the recommended table to use for Xtend. The 'sortbin' parameter specifies the COR value bin boundaries that are used in the NXB selection.

The xtdnxbgen task outputs the weighted NXB PI spectrum ('outpifile'), (optionally) the calibrated, screened, and time-filtered NXB event list ('outnxbfile'), and (optionally) the NXB EHK file corresponding to the NXB event file ('outnxbehk').

If the background region file is different from the source region, xtdnxbgen applies a correction due to dependence on the background on CCD row number. In this case, the background region file must be provided by the parameter 'regfile' and the source region file by the parameter 'regfile2'. Both region files must be in the the same coordinate system, specified by 'regmode'. The NXB row-dependence can be adjusted with 'slope' and 'constant', although it is recommended to use the default values. If the region file for source and background are the same, this correction is not needed.

PARAMETERS

infile [filename]

Input Xtend 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 background region file in DS9 format. The region should be in coordinates specified by 'regmode'. If source and background regions differ, the source region should be specified by 'regfile2' to correct for spatial differences. Note, the user is responsible for ensuring this input region file indeed matches the value input for 'regmode'.

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

Input NXB event file used to construct the NXB spectrum. If 'innxbfile=NONE', the task will use the NXB database specified by 'database'.

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

Input NXB EHK file. This file must contain the column specified in 'sortcol' used to weight the output NXB spectrum. If 'innxbehk=NONE', the task will use the NXB database specified by 'database'.

outpifile [filename]

Output PI spectrum file name.

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

Output NXB event 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.

(database = REMOTE) [string REMOTE|LOCAL]

Type of NXB database to be used. The remote database will be accessed automatically from the FTP site, or a local database can be supplied in the 'db_locattion' parameter.

(db_location = https://heasarc.gsfc.nasa.gov/FTP/xrism/prelaunch/.dev/) [string]

Location of the NXB database to be used. The remote database is located at the FTP site. If a local database is being used, this parameter must be the full path to the local database.

(exclude_keys) = NONE [string NONE|list of keywords]

Comma-separated list of keywords to exclude from determining the applicable database datasets, or NONE, if no keywords are to be excluded.

(apply_xtdtools = yes) [boolean yes|no]

If 'apply_xtdtools' is set to yes, recalculate PI using xtdpi and flag events using xtdflaggpix. If 'apply_xtdtools' is set to no, do not run xtdpi or xtdflagpix. If 'innxbfile' and 'innxbehk' are specified as file names, reprocessing is not allowed, therefore 'apply_xtdtools' must be set to no.

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

Region mode. Specifies the coordinate system used by 'regfile' and 'regfile2'. Note that it is the user's responsibility to ensure 'regmode' matches the coordinate system used in 'regfile' and 'regfile2'.

(timefirst = -150) [string]

Start of the time window within which to extract NXB events. This can be specified as a number of days before TSTART of the input science events file ('infile') by using an integer preceded by '-'. It can also be specified as a date in the form YYYY-MM-DDThh:mm:ss, which need not be before the start of the science data. The same format must be used for 'timefirst' and 'timelast'.

(timelast = +150) [string]

End of the time window within which to extract NXB events. This can be specified as a number of days after TSTOP of the input science events file ('infile') by using an integer preceded by '+'. It can also be specified as a date in the form YYYY-MM-DDThh:mm:ss, which need not be after the end of the science data, but must be later than 'timefirst'. The same format must be used for 'timefirst' and 'timelast'.

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

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 any additional non-standard 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, light curve filtering is not performed.

(regfile2 = NONE) [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 row-dependent correction of the background. 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 spatially dependent correction. The region should be specified in coordinates specified by 'regmode'. Note, the user is responsible for ensuring this input region file indeed matches the value input for 'regmode'.

(slope = 0.2121 [double])

Input slope for the backgroud dependence on CCD row. This value is calculated from calibration and it is recommended not to change it. The accepted range is -1 to 1.

(constant = 297.7 [double])

Input constant for the backgroud dependence on CCD row. This value is calculated from calibration and it is recommended not to change it. The accepted range is 0 to 3000.

(bad_status = DEFAULT) [string]

Bad status list, colons can be used to specify a range (eg. 1:3,5 = 1,2,3,5). This is an xtdflagpix parameter, and it should match the value of 'bad_status' used for processing of the science data with xtdflagpix. Use DEFAULT for this parameter to use the default parameter value from xtdflagpix, which are correct if the science data has not been reprocessed.

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

EXAMPLES

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

   xtdnxbgen infile=xa100050020xtd_p0100004b0_uf.evt ehkfile=xa100050020.ehk regfile=target_sky.reg innxbfile=nxb.fits \
     innxnehk=nxb.ehk outpifile=target_xtdnxb.pi sortbin="0,6,7,8,9,10,11,12,13,99"
   

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

   xtdnxbgen infile=xa100050020xtd_p0100004b0_uf.evt ehkfile=xa100050020.ehk regfile=target_det.reg innxbfile=nxb.fits \
     innxbehk=nxb.ehk outpifile=target_xtdnxb.pi regmode=DET expr="STATUS[2]==b0"
   

3. Run xtdnxbgen without applying the most recent Xtend calibration.

   xtdnxbgen infile=xa100050020xtd_p0100004b0_uf.evt ehkfile=xa100050020.ehk regfile=target_sky.reg \
     outpifile=target_xtdnxb.pi apply_xtdtools=no
   

SEE ALSO

rslnxbgen, xtdpi, xtdflagpix, ftselect

LAST MODIFIED

Novvember 1, 2023