NAME

USAGE

DESCRIPTION

The niscorplc task estimates a SCORPEON background for a NICER light curve. This background model represents by default both the sky-related backgrounds such as the cosmic X-ray background (CXB), as well as the non-X-ray backgrounds (NXB) that are encountered by NICER throughout its orbital environment.

Unlike other SCORPEON background estimation tools, this tool is designed to function on light curves rather than spectra. It is designed to estimate the time variations of each background component as a function of time. However, it does not have the same flexibility to "fit" the background to your data, which is only possible for spectroscopy analysis within XSPEC. Although the estimates of the normalizations of each component can vary with time, they are not adjustable by the user.

Because two of the inputs are products of the nicerl3-spect tool, it is required to run nicerl3-spect before running nicerl3-lc.

Inputs

The required inputs to the task are

• a light curve extracted from NICER data using niextlc or nicerl3-lc
• the pulse height range of interest
• a NICER filter file covering the same time as the light curve
• an FPM selection file, typically your cleaned event file
• the "sky arf" calculated by nicerl3-spect
• the response matrix calculated by nicerl3-spect (not the "background response")

The time binning of the file is determined by the task automatically using the OGIP-standard time-related keywords and columns, including the TIME column, and the TIMEDEL, TIMEPIXR, TIMEZERO keywords.

Please note that this task requires a filter file which has been generated by niprefilter2 version 2.0 or higher. It is possible to run nicerl2 to generate a revised filter file without disturbing your event file by running nicerl2 with the option tasks=MKF.

If you use a filter file as your FPM Selection information, please be aware that there are some limitations. Using the filter file in this way will not reflect if you have de-selected some detectors using nifpmsel. For this reason, it's recommended to always use the cleaned event file produced by nicerl2 (version 1.17 or higher) as your selfile. It is possible to run nicerl2 to generate a revised cleaned event file without disturbing your spectrum if necessary.

In addition, the task needs access to NICER's Calibration Database (CALDB) in order to access various background calibration files.

Outputs

The output of the task is a new FITS file containing background estimates. The output file contains the same number of rows as the light curve files, and the rows should be a one-to-one match with the light curve time bins. The columns of the output file are:

• TIME - the time stamp for the light curve bin
• BACKV - estimated total background in the requested PI band
• BACKE - estimated systematic error of BACKV, set to 50% by default (this can be adjusted with the syserrpct parameter)
• BACK_X - estimate of background due to each SCORPEON background component, including COR, TREL, PREL, SAA and NOISE). An additional column, BACK_BASELINE, contains the non-time variable components including CON and the sky backgrounds.

It should be noted that the background estimates produced by this tool is probably not accurate enough for a simple subtraction from the light curve samples. Rather, they will be useful for human manual screening of light curves, to exclude data with background flares.

PARAMETERS

infile [filename]

Input light curve file name for which the background model is to be estimated.

pirange=30:800 [string]

Pulse height range to extract light curve from, in the form start-end (inclusive). See above for a discussion regarding meaning of the PI value. Either the low-high or low:high notation is permitted.

outfile [string]

Name of the output background estimate. If $INFILE or $OUTFILE are present in the string, they are replaced as described above.

mkfile [filename]

Name of the filter file (.mkf file).

selfile [filename]

Name of the file containing FPM Selection information. This should either be the cleaned event list (recommended), although the filter file can also be specified if necessary, with the limitations described above.

skyarffile [filename]

Name of "sky ARF" for this pointing position. This should be an ARF generated by nicerarf with a "flat" surface brightness profile and is different from the ARF used for the target.

specrespfile [filename]

Name of RMF for the target, as generated by nicerarf.

(bkgcomponents="INDEF") [string]

A comma-separated list of background components from the model to include. A value of INDEF means to use the model-specific default.

(bkgver="v23") [string]

The background model version to use, as described above.

(bkgconfigs="NONE") [string]

A comma-separated list of parameter settings, as described in the help file for the niscorpspectmod task.

(bkgvariant="INDEF") [string]

Use this parameter to select a background variant other than the default. A value of INDEF or NONE will select the default. Currently, the allowed variants are "detailed" and "sf".

(bkgsoftlanding=YES) [boolean]

Set to YES to enable the "soft landing" process as described above, or NO to disable soft landing and rely upon a priori estimates only.

(bkgsources="INDEF") [string]

A comma-separated list of background model source numbers, as described above.

(datamodes="so+sf") [string]

Which NICER datamode selection to use. At present this is restricted to "so+sf".

(gtifile="$INFILE[GTI]") [string]

File name[extension] containing the Good Time Interval used to create the input spectrum file. The pattern $INFILE is replaced by the infile parameter. Therefore, the default setting of "$INFILE[GTI]" will look for the GTI extension of the input file.

(detlist=launch) [string]

List of detectors to process, as a comma-separated list. This can be a list of detector numbers or ranges of detectors. A value of "launch" means the 52 detectors operable at launch. A minus sign in front a of a detector number means to exclude that detector. Please note that FPM Selection information will be used to further refine the number of enabled detectors, so it is safe to specify "launch" here even if detectors have been deselected using nifpmsel.

(noiseparfile="CALDB") [string]

NICER noise peak parameter calibration file, or CALDB.

(bkgparfile="CALDB") [string]

NICER background parameter calibration file, or CALDB.

(diagrespfile="CALDB") [string]

NICER NXB diagonal response file, or CALDB.

(selcol="INDEF") [string]

Which column to use from selfile. A value of INDEF indicates to determine the column name automatically from the file type (either FPM_ON or FPM_SEL).

(corcol="COR_SAX") [string]

Name of filter file column for cutoff rigidity.

(solarphicol="SOLARPHI") [string]

Name of filter file column for solar wind modulation potential.

(overcol="MPU_OVERONLY_COUNT") [string]

Name of filter file column for per-FPM overshoot values.

(undercol="MPU_UNDERONLY_COUNT") [string]

Name of filter file column for per-FPM undershoot values.

(fpmoncol="FPM_ON") [string]

Name of filter file column for per-FPM on/off information

(latcol="SAT_LAT") [string]

Name of filter file column for NICER observatory earth latitude.

(loncol="SAT_LON") [string]

Name of filter file column for NICER observatory earth longitude.

(maxunder=600) [real]

Maximum value of per-FPM undershoot to consider. Values above this number are truncated. This serves as outlier protection when computing norms of the noise peak.

(bat2dets="BKGPAR") [string]

List of detectors which are considered "Batch 2" in terms of background performance. Set to BKGPAR to read this list from the background calibration file.

(noise_enom=0.0) [real]

Nominal energy to compute noise norm in keV, or 0.0 to use the noise peak centroid.

(minmkfver=2.0) [real]

Minimum version of niprefilter2 used to compute filter file.

(bkgexpo=1.0e9) [real]

Exposure to use with XSPEC fakeit command, in seconds.

(syserrpct=50) [real]

Systematic error to apply to each background estimate sample, in percent.

(minerr=1.0e-5) [real]

Minimum error to apply to each background estimate sample, in ct/s.

(cleanup="YES") [boolean]

If yes, then clean up temporary files. If no, temporary files remain. This is typically for debugging.

(clobber = NO) [boolean]

If the output file already exists, then setting "clobber = yes" will cause it to be overwritten.

(chatter = 2) [integer, 0 - 5]

Controls the amount of informative text written to standard output. Setting chatter = 4 or higher will produce detailed diagnostic output; chatter = 1 prints out a basic diagnostic message. The default is to produce a brief summary on output.

(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 niscorplc task parameters that were used to produce the output file.

EXAMPLES

Run niscorplc for mycurve.lc, using the light curve's GTI, for all pre-launch operating detectors. The filter file is ni1234567890.mkf and the cleaned event file with FPM Selection information is in ni1234567890_0mpu7_cl.evt. The PI range is 25-500 (0.25-5.0 keV).

   niscorplc mycurve.pha 25-500 mycurve_bkg.lc \
     ni1234567890.mkf ni1234567890_0mpu7_cl.evt myspectrum_sky.arf myspectrm.rmf 

SEE ALSO

niscorpeon

niscorpspect

nicerarf

nicerrmf

nicerl2

nicerl3-lc

LAST MODIFIED