NAME

nibackgen3C50 - Generate 3C50 estimate of NICER background spectrum

USAGE

nibackgen3C50 rootdir obsid bkgidxdir bkglibdir gainepoch ...

DESCRIPTION

The nibackgen3C50 task uses a set of three background proxies embedded in NICER event lists to estimate the background spectrum for a single NICER observation. It does so by (1) dividing the exposure into intervals, (2) calculating the value of the proxies in each interval, (3) finding the best match to a pre-computed library of background spectra for each interval, and (4) combining these - appropriately weighted and scaled - to construct a composite background spectrum. Note that the library spectra are extracted from observations of source-free areas of the sky, and include the astrophysical background associated with those fields as well as the NICER instrumental Non-X-ray-Background. As part of the calculation, the input cleaned event file GTI are subdivided into intervals no larger than that specified by the 'dtmax' parameter, discarding residual intervals smaller than that specified by the 'dtmin' parameter. One may set 'dtmin' to 0 and 'dtmax' to some value greater than the exposure time to use the original GTI. If all GTI in the original file are less than 'dtmin', an error will result and no output files produced.

The location of the required background library files, where subdirectories bg_model_3C50_RGv5, bg_model_3C50_g2019d, and bg_model_3C50_g2020a are located, is specified by the 'bkglibdir' parameter. The 'bkgidxdir' parameter specifies the location of the required background index file, nibackgen3C50_info.fits, that lists the current 3C50 background library versions indexed by gain epoch (see below) -- and contains information such as the definitions of the background proxies; and the names, energy boundaries, and average count rates for the library spectra.

Multiple library versions correspond to distinct gain calibrations, identified by their gain epoch: the 2018 library ("3C50_RGv5") was constructed using the nixtiflightpi20170601v002.fits CALDB file, the 2019 library ("3C50_g2019d") using the nixtiflightpi20170601v004.fits CALDB file, and the 2020 library ("3C50_g2020a") using the nixtiflightpi20170601v005.fits CALDB file (nixtiflightpi20170601v006.fits and nixtiflightpi20170601v007.fits represent relatively modest updates to nixtiflightpi20170601v005.fits, and data processed with one of those gain files also should use the 2020 library). The library version to be applied is specified by the 'gainepoch' parameter. A warning is issued if the GCALFILE keyword in the input cleaned event file does not exactly match the name of the CALDB version gain file corresponding to the setting of 'gainepoch'. This warning may be ignored if applying the 'gainepoch=2020' library to data calibrated using nixtiflightpi20170601v006.fits or nixtiflightpi20170601v007.fits. An error will result if the setting of 'gainepoch' has no corresponding entry in the index file.

The task also creates a total spectrum extracted from the input event list based on these (possibly revised) GTI, with the additional excision of data in time intervals with background proxies that lie outside of the background library bounds. The source (background subtraced) spectrum may then be determined by the difference between the total spectrum and the background spectrum. Both the total and background spectra are extracted based on the unfiltered event list with the option of excluding a list of FPMs using the 'fpmofflist' parameter that, by default, is set to FPMs (DET_ID) 14 and 34. The task performs no other checks or corrections for inactive or noisy detectors.

GTI where the absolute value of the estimated net "HBG" (13-15 keV) count rate exceeds the value set by the 'hbgcut' parameter, are considered as suspect and also excluded; its default value is set at a conservative value of 0.5 counts per second. Finally, GTI where the absolute value of the estimated net "S0" (0.2-0.3 keV) count rate exceeds the value set by the 's0cut' parameter, are similarly excluded; its default value is set at a conservative value of 30 counts per second. If the absolute value of the estimated net HBG or S0 count rate exceeds the values of these parameters in all refactored GTI, no background spectrum is produced.

As with the nicerl2 task, by default, the task expects the input to adhere to the standard NICER directory layout with calibrated merged unfiltered and filtered event files in $ROOTDIR/$OBSID/xti/event_cl, and auxiliary files in $ROOTDIR/$OBSID/auxil/. An advanced programmer can adjust these locations with the hidden parameters ufadir, cldir, ufafile, and clfile. When using these parameters, note that certain patterns can be used as shortcuts: "$CALEVTDIR" for the location of the input calibrated and filter event files, "$OBSID" for the observation ID number, and "$INDIR" for the input directory $ROOTDIR/$OBSID. Note, also, that these patterns should appear explicitly with the dollar sign included; typically the command shell will interpret '$name' as a shell variable so appropriate quoting will be required. The 'rootdir' parameter may be maintained at its default value of "NONE" in some such cases.

The user may also directly input the combined, calibrated unfiltered "ufa" and filtered "cl" event files using the 'ufafile' and 'clfile' parameters. In this case, the 'rootdir', 'obsid', and 'calevtdir' parameters may all be set to "NONE".

The names of the output PI files are determined by the 'totspec' (for the total), and 'bkgspec' (for the background) parameters. These are treated as roots, and the suffix ".pi" is added to these strings in constructing the output file names. The background spectrum consists of primary ISS night and supplemental soft excess ISS day components, and the task also produces the spectra corresponding to these individual components. Their file names are constructed by adding the suffixes "_ngt.pi" and "_day.pi" to string value of 'bkgspec'. There may be instances where the supplemental ISS day spectrum is not needed, in which case the total background spectrum is equivalent to the night-only component.

PARAMETERS

rootdir [string]
Name of input observation root directory. This is the directory one level up from that set by the 'obsid' parameter. May be set to 'NONE' if explicitly specifying the files defined by the 'ufafile' and 'clfile' parameters, or the directory containing these files explictly defined by the 'calevtdir' parameter.
obsid [string]
Name of input observation identifier. When 'rootdir' is specified, this is the directory for a single NICER observation that contains xti/{events_uf,events_cl,hk,auxil} subdirectories, and is relative to 'rootdir'. May be set to 'NONE' if explicitly specifying the files defined by the 'ufafile' and 'clfile' parameters.
bkgidxdir [string]
Name of the directory where the 3C50 background library index file, nibackgen3C50_info.fits is located.
bkglibdir [string]
Name of the directory where the 3C50 background library spectra are located.
gainepoch = AUTO [string]
Name of the library version used to create the estimated background spectrum. An error results if there is no corresponding entry in the library index file, and a warning is issued if the library version does not match the GCALFILE keyword in the input cleaned event file. This warning may be disregarded in cases where this parameter is set to 2020 and the data is processed using CALDB gain file nixtiflightpi20170601v006.fits or later. If this parameter is set to AUTO (the default) then the task will attempt to determine the gain epoch automatically.
(calevtdir = "$INDIR/xti/event_cl") [string]
Subdirectory containing MPU-merged "ufa" and cleaned "cl" event files, which are inputs to the task. This parameter is subject to pattern substitution $INDIR ($ROOTDIR/$OBSID) as described above. May be set to 'NONE' if explicitly specifying the files defined by the 'ufafile' and 'clfile' parameters.
(totspec = "backgen3C50_tot") [string]
Name of output total spectrum file root. GTI with background proxies out-of-bounds of the background library are excluded.
(bkgspec = "backgen3C50_bkg") [string]
Name of output background spectrum file root.
(ufafile = "$CALEVTDIR/ni$OBSID_0mpu7_ufa.evt") [string]
Name of the input master "ufa" event file. This parameter is subject to pattern substitutions $CALEVTDIR and $OBSID as described above.
(clfile = "$CALEVTDIR/ni$OBSID_0mpu7_cl.evt") [string]
Name of the input "cl" event file. This parameter is subject to pattern substitutions $CALEVTDIR and $OBSID as described above.
(fpmofflist=14,34) [string]
List of FPMs to exclude from consideration in constructing the output total and background spectra, either as a comma-separated list, or as a hyphenated range.
(dtmin=10.0) [real]
Minimum time interval (s). Residual intervals shorter than this are discarded from the output total spectrum, and from consideration in constructing the output background spectrum.
(dtmax=120.0) [real]
Maximum time interval (s). GTI are subdivided into intervals that are no longer than this for consideration in constructing the output background spectrum.
(hbgcut=0.5) [real]
Maximum net HBG (13-15 keV) rate (c/s). GTI where the absolute value of the net HBG rate exceed this are discarded from the output total spectrum, and from consideration in constructing the output background spectrum.
(s0cut=30.0) [real]
Maximum net S0 (0.2-0.3 keV) rate (c/s). GTI where the absolute value of the net S0 rate exceed this are discarded from the output total spectrum, and from consideration in constructing the output background spectrum.
(minweight=1.0e-9) [real]
Minimum weight considered in calls to mathpha. Background library spectra with weights below this value are not included in the final weighted spectrum.
(cleanup="YES") [boolean]
If yes, then clean up temporary files. If no, temporary files remain. This is typically used for debugging.
(clobber = NO) [boolean]
If the output files already exist, then setting "clobber = yes" will cause them to be overwritten.
(chatter = 2) [integer, 0 - 5]
Amount of verbosity of the task. For chatter=0, no output is printed. For chatter=5, debugging output is printed.
(history = YES) [boolean]
If history = YES, then a set of HISTORY keywords will be written to the header of the specified HDU in the output file to record the value of all the task parameters that were used to produce the output file.

EXAMPLES

1. Extract estimated NICER background, and accompanying total spectrum, for observation 2010100101.

 nibackgen3C50 rootdir='datadir' obsid='2010100101'  bkgidxdir='mybgkdir' \
  bkglibdir='mybgkdir' gainepoch='2020'

The input directory is a NICER observation number 2010100101. The input event files are in the observation directory under datadir/2010100101/xti/event_cl/, and the background library files and index file under mybgkdir. The 2020 version of the background spectral library, corresponding to the nixtiflightpi20170601v005.fits gain CALDB file, is used.

2. Extract estimated NICER background and accompanying total spectrum for observation 2010100101. Do not consider GTI where the absolute value of the net HBG rate exceeds 0.1 c/s or the net s0 rate exceeds 10 c/s.

 nibackgen3C50 rootdir='datadir' obsid='2010100101' \
  bkgidxdir='mybgkdir'  bkglibdir='mybgkdir' gainepoch='2020' \
  hbgcut=0.1 s0cut=10.0

3. Extract estimated NICER background and accompanying total spectrum, for observation 2010100101, excluding events detected in FPMs (DET_ID) 0, 1, 2, 3, 4, 5, 25, 26, and 27 from the output total and background spectrum.

 nibackgen3C50 rootdir='datadir' obsid='2010100101'  bkgidxdir='mybgkdir' \
  bkglibdir='mybgkdir' gainepoch='2020' fpmofflist=0-5,25-27 
4. Extract estimated NICER background and accompanying total spectrum from ufiltered event file combined_ufa.evt based on the GTI in combined_cl.evt, and using intervals between 30 and 240 s to characterize the variation of the background.

 nibackgen3C50 rootdir='NONE' obsid='NONE'  bkgidxdir='mybgkdir' \
  bkglibdir='mybgkdir' gainepoch='2020' calevtdir='NONE' \
  ufafile='combined_ufa.evt' clfile='combined_cl.evt' \
  dtmin=30.0 dtmax=240.0 

SEE ALSO

nicerl2

LAST MODIFIED

August 10 2021