NAME

USAGE

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. For these purposes, 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. The location of the required "3C50_RGv5" background library file is specified by the 'bkgdir' parameter. One may set 'dtmin' to 0 and 'dtmax' to some value greater than the exposure time to use the original GTI.

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. Finally, 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.

Note that "3C50_RGv5" background library files were extracted using CalDB gain file nixtiflightpi20170601v002.fits; and, strictly speaking are applicable to input event files with the same gain correction (see GCALFILE header keyword to check).

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, clfile, and mkfile. When using these parameters, note that the 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 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 GTI extension of the cleaned event file must be named GTI (and not, e.g., STDGTI).

The 'mkfile' parameter is not currently used, but reserved for future task revision, and may be generally set to 'NONE' at this time.

PARAMETERS

(rootdir = NONE) [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 defined by the 'calevtdir' parameter.

obsid [string]

Name of input observation indentifier. 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.

bkgdir_root [string]

Name of "3C50_RGv5" background library directory.

(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.pi") [string]

Name of output total spectrum file. GTI with background proxies out-of-bounds of the background library are excluded.

(bkgspec = "backgen3C50_bkg.pi") [string]

Name of output background spectrum file.

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

(mkfile = "$INDIR/auxil/ni$OBSID.mkf") [string]

Name of the MKF filter file, to be used as input. This parameter is subject to pattern substitution $INDIR ($ROOTDIR/$OBSID) and $OBSID as described above. Currently not used, but reserved for future task revision; and, so may be set to 'NONE'.

(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=20.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=60.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 HBG rate exceed this are discarded from the output total spectrum, and from consideration in constructing the output background 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 1200190101.

  nibackgen3C50 rootdir='datadir' obsid='1200190101'  bkgdir='bgklibdir' 

The input directory is a NICER observation number 1200190101. The input event files are in the observation directory under datadir/1200190101/xti/event_cl/, and the background library files under bgklibdir.

2. Extract estimated NICER background and accompanying total spectrum for observation 1200190101, using intervals between 10 and 120 s to characterize the variation of the background.

  nibackgen3C50 rootdir='datadir' obsid='1200190101'  bkgdir='bgklibdir' \
dtmin=10.0 dtmax=120.0 

3. Extract estimated NICER background and accompanying total spectrum, for observation 1200190101, 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='1200190101'  bkgdir='bgklibdir' \ 
fpmofflist=0-5,25-27 

  nibackgen3C50 rootdir='NONE' obsid='NONE'  bkgdir='bgklibdir' \
calevtdir='NONE' ufafile='combined_ufa.evt' clfile='combined_cl.evt' \
mkfile='NONE' dtmin=10.0 dtmax=120.0 

SEE ALSO

nicerl2

LAST MODIFIED