niscorpspect HEADAS help file

NAME

niscorpspect - estimate NICER SCORPEON background file for spectra

USAGE

niscorpspect infile outfile mkfile selfile skyarffile specrespfile

DESCRIPTION

The niscorpspect task estimates a background file for a NICER spectrum that is usable within XSPEC. This background file 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.

This task estimates a constant background file which is subtracted from the scientist's source+background spectrum within XSPEC. This is unlike the niscorpspectmod task, which estimates a background model that can be evaluated and fitted within XSPEC. Internally, niscorpspect calls niscorpspectmod and evaluates the resulting generated model using XSPEC's "fakeit" command to generate a background spectrum file.

If you are uncertain which SCORPEON background estimator task to use, niscorpspect (this task) or niscorpspectmod, here is a summary of which to use.

niscorpspectmod generates a model that has adjustable parameters. It is the more sophisticated of the two tasks, and requires more understanding of the background parameters, but is also likely to produce a more accurate result. Use this task when you are analyzing single spectra of faint sources or where the highest precision is required.
niscorpspect generates a constant background file that has no adjustable parameters. It is less sophisticated and likely to produce less accurate results, but is simpler to use. Use this task when you are analyzing many spectra, within automated pipelines, where lower precision is acceptable, or when the source spectrum is unknown a priori.

Inputs

The required inputs to the task are

Spectrum file (infile). This is the spectrum for which you require a background estimate. It should have an accurate GTI extension.
Filter file (mkfile). This is the filter file which should cover the time range of the accumulated spectrum. I.e. the spectrum GTIs and filter file times should overlap.
File with FPM Selection information (selfile). This can be either a cleaned event file with an FPMSEL extension, or the filter file.
A "Sky" ARF (skyarffile). This is different from the ARF for your target. Please see below for more information how to generate this.
A response file (specrespfile). This is the RMF generated using nicerrmf for your target.

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 outputs of the task is an output background file that can be loaded within XSPEC. This is a standard OGIP "type I" spectrum file.

Using SCORPEON Background File in XSPEC

Once you have run niscorpspect to completion, you should have an background file. You can load this model into XSPEC with your data.

Loading Data and SCORPEON Background File

First, you should load your data. In this example, we will load spectrum number 1 into datagroup 1.

    data 1:1 myfile.pha
    back 1 myfile-bkg.pha
    resp 1:1 myfile.rmf
    arf 1:1  myfile.arf

Please note that this is the standard way to load data into XPEC, and nothing special regarding the background is contained in these XSPEC command statements.

In this example, we assume that your spectrum, RMF and ARF are named myfile.pha, myfile.rmf and myfile.arf respectively, and that you have already created these files. These should be the target-specific RMF and ARF that you generated for this spectrum, and not the sky ARF and not the NXB response.

The file "myfile-bkg.pha" in this example is the background file generated by this task.

Please note that if you have used the "updatepha=YES" option when running this task, the task will populate the BACKFILE keyword of the input spectrum, and the background file will be loaded automatically.

Details: Controlling How The Task Works

The SCORPEON model is a sophisticated model with many components. The operation of the model is described in more detail in the documentation for niscorpspectmod.html, and the user is recommended to read the help for that task as well.

The background-related parameters of niscorpspectmod are available to niscorpspect as well. These parameters include,

bkgcomponents - which background components to include in the calculation
bkgver - which background model version to use
bkgconfigs - a way to override the defaults of individual background parameters
datamodes - which event selection datamode to use

For more information on these, see the documentation for niscorpspectmod.

As noted in the documentation for niscorpspectmod, one can use the bkgconfigs parameter to set individual background parameters where additional external information about the background is available. Some examples are discussed in that file in more detail.

The task niscorpspectmod takes many parameters, not all of which are passed directly by this task. If any of these parameters need to be accessed, the niscorpspecmod_args parameter can be used to specify them in bulk.

When generating a background file, this task applies a statistical uncertainty to each sample. By default, this is set as 50% x RATE or 1.0e-5 ct/s, whichever is bigger, where RATE is the estimated background rate. The percentage error can be specified by the scientist using the syserrpct parameter (which defaults to 50%). The lower bound on the error is specified by the minerr parameter.

Details: Model Variants

Some of the SCORPEON models come in different flavors or variants. The variants provide additional or different functionality for the same basic component. You may select such variants using the bkgvariant=NAME parameter, for example bkgvariant=detailed. Please see the help file for niscorpspectmod for more details.

Details: Soft Landing Procedure

After making an a priori estimate of the background parameters, the SCORPEON model can tailor or adjust the model to more closely match the spectral data it is intended for. This is known as the "soft landing" process, and is enabled when bkgsoftlanding=YES (the default). The background trel_norm (and possibly prel_norm) are adjusted to match the 12-15 keV data, and the noise peak sigma and norm are adjusted to match the 0.22-0.26 keV data. For more information, please see the SCORPEON help page.

PARAMETERS

infile [filename]: Input spectrum file name for which the background model is to be estimated. If updatepha=YES, this file must be writable.
outfile [filename]: Name of output estimated background file.
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 above.
(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.
(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.
(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 patterns $INFILE and $OUTFILE are replaced by the infile and outfile parameters. 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.
(niscorpspectmod_args=NONE) [string]: Any additional arguments to pass to niscorpspectmod. For example to set non-default latitude and longitude columns, set niscorpspectmod_args="latcol=MYLATCOL loncol=MYLONCOL".
(updatepha="YES") [boolean]: If yes, then modify the input file's BACKFILE keyword to be background file output by this task.
(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 niscorpspect task parameters that were used to produce the output file.

EXAMPLES

Run niscorpspect for myspectrum.pha, using the spectrum'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.


   niscorpspect myspectrum.pha myspectrum-bkg.pha \
     ni1234567890.mkf ni1234567890_0mpu7_cl.evt \
     myspectrum_sky.arf myspectrm.rmf

Note that the output is stored in myspectrum-bkg.pha.

LAST MODIFIED

Jul 2022