The niscorpspectmod task estimates a background model for a NICER spectrum that is usable within XSPEC. 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 many background estimation tools (including niscorpspect) which estimate a background file which is simply subtracted by XSPEC from the source+background spectrum, this task generates a model that can be used for spectral analysis. The model has parameters that can be adjusted and fit to the data along with the model of X-ray emission from the source. One of the outputs of this task is an XSPEC command file (myfile-bkg.xcm) which is used to construct and initialize the SCORPEON model for spectral analyais.
If you are uncertain which SCORPEON background estimator task to use, niscorpspectmod (this task) or niscorpspect, here is a summary of which to use.
The required inputs to the task are
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.
The outputs of the task are:
niscorpspectmod is compatible with both standard XSPEC as well as pyXSPEC. The user specifies the outlang parameter, either outlang=XCM (XSPEC commands) or outlang=PYTHON (pyXSPEC commands) and the resulting output command file is in the appropriate language. The examples below are for XSPEC, but similar examples apply for Python / pyXspec.
By default the outrespfile will have a name like $OUTFILE-nxb.rmf where $OUTFILE is the name of the output command file (minus the suffix). Thus, the outputs will be placed in the input spectrum's directory and be named similarly to the output script, with different suffixes.
You can override this behavior and choose different output file names by specifying the outfile and/or outrespfile explicitly. Anywhere where the string "$INFILE" / "$OUTFILE" appears will be replaced by the infile / outfile root file name, respectively. Of course, you can always specify the file names explicitly, without $INFILE or $OUTFILE, and that is recommended if you are designing your own pipeline. The $INFILE and $OUTFILE syntax is useful for standard processing so that output files have standard naming.
Once you have run niscorpspectmod to completion, you should have an XSPEC command file and NXB response. You can load this model into XSPEC.
First, you should load your data. In this example, we will load spectrum number 1 into datagroup 1.
data 1:1 myfile.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. 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.
If you want to load your data as a different spectrum number, that is acceptable. Instead of the "1:1" above you can specify "2:2" for the second file / datagroup, "3:3" for the third file / datagroup, and so on. However the spectrum number is important for the next step when you load the background model.
To load the background model generated by niscorpspectmod, you can use the following two statements,
set nicer_bkgspect 1 @myfile-bkg.xcmHere, we use TCL to set a variable "nicer_bkgspect" to a value of 1. If you loaded a different spectrum number, say 2, then the command would be "set nicer_bkgspect 2" instead.
The "@myfile-bkg.xcm" statement will execute the XSPEC command file this task generated, and we use myfile-bkg.xcm as an example here.
As an alternate example, if you wanted to load two spectra (myfile1.pha and myfile2.pha, with associated auxiliary files) into data groups 1 and 2, you would do the following,
data 1:1 myfile1.pha
resp 1:1 myfile1.rmf
arf 1:1 myfile1.arf
set nicer_bkgspect 1
@myfile1-bkg.xcm
data 2:2 myfile2.pha
resp 1:2 myfile2.rmf
arf 1:2 myfile2.arf
set nicer_bkgspect 2
@myfile2-bkg.xcm
This works the same as any XSPEC analysis of multiple spectra, except that here we must specify "set nicer_bkgspect 2" for the second spectrum so that the loader knows to apply background to the second spectrum. Note that this requires that niscorpspectmod has been run twice: once for each spectrum.
Internally to the XSPEC command file, the following things happen.
If this is the first time loading this file, it will define multiple XSPEC "mdefine" functions which characterize the various NICER SCORPEON background model shapes. There are ~50 of these mdefine statements corresponding to the various contributions to the backgrounds. The user is not intended to alter these model statements.
The XSPEC commands will define responses and models for each of the model sources (typically "sky" for sky backgrounds with model number 98 and "nxb" for non X-ray backgrounds with model number 99).
Finally, XSPEC commands set the background parameters for all of the relevant model parameters.
Scientists may be familiar with using the XSPEC "save" command to save model and parameter definitions and the end of a work session. "save" is a common and useful mechanism to keep the products from one session so that they can be used in a future work session.
With a modern version of XSPEC, the "save all" command will save most of the required elements of the SCORPEON model. Here, "modern version" means a version of XSPEC released with the SCORPEON model or later, so in principle "save" should always work, except in cases where users share SCORPEON-generated save files with colleagues that have older versions of XSPEC.
That being said, the output of the "save" command will be somewhat jumbled. If possible, the user should save the parameters to a temporary file and then transfer them to a clean master save file.
By default, niscorpspectmod will provide background estimates for all available background components and for the newest released version. The scientist can alter this behavior if desired. This may not necessarily be recommended, but could be useful if a knowledgable scientist needs to alter the behavior.
To control which background components are created, the scientist can specify this list using the "bkgcomponents" parameter. This is a comma-separated list of components. See the help "niscorpeon" for the components defined for each released SCORPEON model (for example, nxb, sky, swcx, etc). When specifying the bkgcomponents explicitly, only those components are written to the output XSPEC command file. Please beware that doing this may lead to an incomplete background model.
To control which backgrond model version is used, specify the "bkgver" parameter. Each of the released background models, with version numbers, is described in the help for "niscorpeon." The only real reason to specify an alternate version number might be to replicate an analysis that was done with an older version of the SCORPEON model.
By default, the background models are set in XSPEC with specific source numbers, which are typically 98 and 99. If this conflicts with your work, you can change them by using the "bkgsources" parameter. For example if you wanted sky-related model components with source 42 and NXB-related model components with source 50, then set bkgsources=sky:42,nxb:50. Please note that this setting just changes which number is used for each model source, not whether the component is present (use bkgcomponents for that).
By default, many of the background model parameters have a priori estimates which are computed from by various means. Some of the NXB parameter values are estimated from NICER telemetry (filter file), and some of the sky-related background terms are computed from published literature (see below). In addition, most of the background model parameters a designed to be adjustable (i.e. fittable), so they have programmed minimum/maximum ranges as well.
The scientist can override all of these if they wish. This is governed by the "bkgconfigs" parameter, which is a comma-separated list of settings of the form "component.parameter[.sub]=value" to change to a specified value. Here component is the background component, as described in the help for "niscorpeon" (for example "nxb" or "swcx"). "paremeter" is the background parameter name as it shows up in XSPEC (for example "prel_norm" or "gal_nh"). The "sub" indicates that you can change the "min", "max", "step" or "fixed" nature of parameter as well as its value.
Examples of single config settings are
nxb.prel_norm=10 # set prel_norm to 10.0 nxb.prel_norm.fixed=1 # set prel_norm to be fixed sky.cxb_norm=15.0 # set cxb_norm to be 15 sky.cxb_norm.min=13 # set cxb_norm minimum value to 13and put altogether they would be specified on the command line as
niscorpspectmod ... bkgconfigs=nxb.prel_norm=10,nxb.prel_norm.fixed=1,sky.cxb_norm=15.0,sky.cxb_norm.min=13
The use of bkgconfigs may seem daunting at first. For the most part, its use will be unnecessary. However, the scientist may discover that a certain parameter, say the local hot bubble temperature, is not being estimated properly by default, and they wish to override the default. Usually, the scientist will start with the defaults, and then iteratively decide if any of the background parameters need to be overridden.
Cases where this may be especially useful are if the user is running a pipeline on many short observations over a long observing campaign, and wants to apply some campaign-level average parameter values to every short observation.
Another case where bkgconfigs may be useful is when using the sister tool niscorpspect to generate a background file (not model), and so the parameters must be predetermined. If the scientist has additional information about background, they cannot fit background parameters with the output of niscorpspect since it is a constant, so the only place to apply this a priori information is with the bkgconfigs parameter. An example of this might be if the scientist fit the campaign average spectrum with a SCORPEN background model to determine the best-fit halo and LHB normalizations. Then they could run niscorpspect to generate a background file for each snapshot and use bkgconfigs=sky.lhb_em=XXXX,sky.halo_em=YYYY to apply these averages. Thus one gains the advantage of the simplicity of a background file instead of a model, but still have higher fidelity regarding the halo and LHB components.
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.
The "detailed" variant provides addiitional detailed parameters for some model components. The actual spectral shape and normalization of the defailed variant is the same as the default variant, but the detailed variant provides additional parameters that are adjustable in the case of special circumstances. Currently, only the NXB model component has a detailed variant, which provides additional normalization adjustment factors for sub-components such as COR and SAA, as well as normalization adjustment factors for the strong background lines.
The "sf" variant provides background models tailored to NICER's SLOW+FAST data mode. This mode consists of only events that have both slow and fast pulse heights, which automatically implies energies above about 0.6 keV. A threshold at 0.572 keV is applied to the background model. The total background for SLOW+FAST events may be lower than the default mode.
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.
Run niscorpspectmod 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.
niscorpspectmod myspectrum.pha myspectrum-bkg.xcm \
ni1234567890.mkf ni1234567890_0mpu7_cl.evt myspectrum_sky.arf myspectrm.rmf
Note that the output is stored in myspectrum-bkg.xcm and myspectrum-nxb.rmf.
As above, but for pyXspec outputs.
niscorpspectmod myspectrum.pha myspectrum-bkg.py outlang=PYTHON \
ni1234567890.mkf ni1234567890_0mpu7_cl.evt myspectrum_sky.arf myspectrm.rmf