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