NAME

rslnxbgen - Create a non-X-ray background (NXB) spectrum for the XRISM Resolve instrument.

USAGE

rslnxbgen infile ehkfile regfile innxbfile innxbehk innxbhk outpifile

DESCRIPTION

The rslnxbgen task generates a PI spectrum of the non-X-ray background (NXB) for a XRISM Resolve observation. The NXB spectrum is calculated from a calibration event file containing night Earth data accumulated over an extended period of time. This spectrum may be used in spectral fitting (e.g., with XSPEC) to account for the effects of the NXB.

The rslnxbgen task requires the following input file parameters: (a) a Resolve science event file ('infile') that provides header keywords and GTI needed by rslnxbgen, (b) the corresponding extended housekeeping (EHK) file ('ehkfile') containing information on the spacecraft orbit during the observation, (c) the NXB event file ('innxbfile'), (d) the NXB EHK file ('innxbehk'), and (e) a DS9-format region file ('regfile'). The region may be specified in RAW, DET, FOC, or SKY coordinates as specifed by the 'regmode' parameter. It is possible to select the region using a list of Resolve pixels by settting the 'regfile' paramter to NONE, and setting the 'pixels' parameter. The files described in (c) and (d) can be obtained by anonymous FTP. The task xrismversion can be run to display the FTP location and names of the required files.

The science event file GTI is applied to the science EHK file to derive an exposure time histogram of the geomagnetic cutoff rigidity (COR) during these intervals. The rslnxbgen task filters the NXB event data on the region file, with this selection performed using DET coordinates. The task internally transforms the coordinates if the region file is not provided in DET coordinates, using the pointing information in the science event file if the region file is in SKY coordinates. The task uses the 'timefirst' and 'timelast' parameters to extend the GTI to apply to the NXB event and NXB EHK data well beyond the science data exposure to ensure sufficient statistical quality in the output NXB spectrum. The default value, based on experience with previous missions, is to have a window of 300 days centered on the observation. The rslnxbgen task then screens the NXB events using the expression specified in the 'expr' parameter that should apply the same criteria that were used for selection of the events in the science data. The NXB spectrum is extracted from the NXB event file, filtered with the extended GTI and region, for each COR bin specifed by the 'sortbin' parameter, and a weighted sum of these is calculated using the science event COR histogram described above.

Note: if the NXB spectrum is calculated using a pixel list rather than a region file, the BACKSCAL keyword is set to -1, and must be adjusted such that the ratio of this keyword value to that in the source spectrum to which it is to be applied is equal to the ratio of the extraction region areas (or numbers of pixels).

The EHK files store several types of COR 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 default for 'sortcol' and is recommended for Resolve.

The rslnxbgen task outputs the weighted NXB PI spectrum ('outpifile'); and, optionally, the GTI-filtered science EHK file, the NXB event list used to derive the NXB spectrum ('outnxbfile'), and the corresponding NXB EHK ('outnxbehk').

PARAMETERS

infile = in.fits [filename]
Input event file name.

ehkfile = ehk.fits [filename]
Input EHK file name. This file must contain the column specified in 'sortcol' used in caclulating the weighted output NXB spectrum.

regfile = NONE [filename NONE|file name]
Input region file in DS9 format. The region should be in the coordinate systme specified by 'regmode'. If 'regfile' is set to NONE, the task uses the 'pixels' parameter to specify the extraction region.

innxbfile = nxb.fits [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 xrismversion.

innxbehk = nxb.ehk [filename]
Input NXB EHK file name. This file must contain the column specified in 'sortcol' used in caclulating the weighted output NXB spectrum. The name of the file and its location (accessible by anonymous FTP) can displayed by running the task xrismversion.

outpifile pi.out [filename]
Output PI spectrum file name.

(outehkfile = NONE) [filename NONE|file name]
Output EHK file name. Contains the EHK data filtered for times in the 'infile' GTI. If this parameter is set to NONE, this file is not created.

(outnxbfile = NONE) [filename NONE|file name]
Output NXB file name. Contains the filtered NXB events used to extract 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 name. Contains the EHK data for the times covered by the filtered NXB events. If the parameter is set to NONE, this file is not created.

(regmode = NONE) [string NONE|SKY|DEF|FOC|RAW]
Region mode. Specifies the coordinate system used by 'regfile'. If 'regfile' is set to NONE, then 'regmode' is ignored and 'pixels' is used to define the region.

(timefirst = 150) [integer]
Number of days before the science observation used to extract NXB event data.

(timelast = 150) [integer]
Number of days after the science observation used to extract NXB event data.

(sortcol = COR3) [string COR|COR2|COR3|CORTIME]
Column for sorting NXB data. This column must exist in the science and NXB EHK files.

(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; and, the list must be comma-separated in increasing numerical order.

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

(expr = NONE) [string]
Additional expression applied to the NXB event list to select good events. This should match the screening of the science data. If the parameter is set to NONE, no expression is used.

(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 (yes/[no]).

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

EXAMPLES

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

SEE ALSO

xtdnxbgen

LAST MODIFIED

November 28, 2018