The nicerl3-spect task is a full NICER spectral analysis chain. It starts with a Level2 cleaned event file and produces spectra, responses, background files and XSPEC command files.
This task is meant as a "getting started" analysis script that does most of the desirable and recommended NICER analysis steps. It is understood that advanced analysts may want to go beyond what is possible with this task.
By default, the task takes as input a NICER observation directory. This should be a full NICER directory with files that have been processed by nicerl2. Upon completion of nicerl2, calibrated and screened event files (the so-called "ufa" and "cl" files) are placed in the observation directory under the subdirectory xti/event_cl.
It is possible to change this default. The task supports three possible scenarios which address the needs of all NICER analysts.
In scenario 1, the observation directory has the typical archive directory structure and nicerl2 has placed its results in the xti/event_cl directory as planned. This is the default.
In scenario 2, the user has followed the instructions of the nicerl2 task under the section titled "WORKING WITH READ-ONLY INPUT DATA" and placed their results into an alternate output directory. The user may specify this directory as the "indir" and nicerl3-spect will search it automatically for nicerl2 products if it does not find an xti/event_cl subdirectory.
In scenario 3, the user has done their own analysis, and the individual input files must be specified manually.
The input files are
The "ufa" file may be considered optional because it is required for the 3c50 background model but not the SCORPEON or space weather background models.
In addition, the target coordinates are required (R.A. and Decl.), either manually entered on the command line or the task can use the RA_OBJ and DEC_OBJ keywords found in the event file (the default).
The task can use some shorthand templates which allow the task to avoid many hardcoded path names. These templates of the form $NAME and can be used in most input or output file names to indicate certain patterns are present without specifying them explicitly. For example, by having a default mkfile=$INDIR/ni$OBSID.mkf, the task will look in the input directory "$INDIR" for a file of the form ni$OBSID.mkf where $OBSID is the 10-digit observation ID code.
The available patterns are:
This system works well with the default directory layouts. If it appears too complicated to the user, they may easily specify the names of input and output files explicitly and they will be used without issue.
This task assumes that NICER calibration files are available via CALDB.
Please note that this task will not operate upon barycentered event files.
As described in more detail below, nicerl3-spect applies several corrections or adjustments to the spectra it produces, as recommended by the NICER team. All of these actions are adjustable by the user. This section describes briefly the parameters you can use to adjust these settings.
nicerl3-spect can choose amongst several NICER background models which are included with NICERDAS. These are the SCORPEON, 3C50 and Space Weather Models. You can read more about background modeling in the "Background Modeling" section below.
SCORPEON. To use the SCORPEON background model, set bkgmodeltype=scorpeon. To produce a background model to be used within XSPEC, use bkgformat=script, while a static background file can be produced. Examples:
nicerl3-spect ... bkgmodeltype=scorpeon bkgformat=script # Background model nicerl3-spect ... bkgmodeltype=scorpeon bkgformat=file # Background file
A background model is saved in the parameter designated by bkgscript (defaults to the {file}mpu7_bg.xcm), while a background file is saved in the file designated by bkgfile (defaults to {file}mpu7_bg.pha).
Instead of an XSPEC XCM script file, nicerl3-spect also supports PyXSPEC, by setting outlang=python. Example: Examples:
nicerl3-spect ... bkgmodeltype=scorpeon bkgformat=script outlang=pythonand the default script name will be {file}mpu7_bg.py. Please note that you can always specify non-default background files (bkgfile parameter) or script names (bkgscript parameter).
The SCORPEON model supports other options such as bkgcomponents, bkgver, bkgvariant, and bkgsoftlanding, and these are passed directly from nicerl3-spect to the SCORPEON modeling tools. Please see the help file for niscorpspectmod for more details.
3C50. For the 3C50 model, specify bkgmodeltype=3c50. Example:
nicerl3-spect ... bkgmodeltype=3c50Only bkgformat=file is supported, and the output is saved in the file name designated by the bkgfile parameter (defaults to {file}mpu7_bg.pha). The 3C50 parameters hbgcut and s0cut are passed directly to the nibackgen3c50 task. The bkgscript, bkgcomponents, bkgvariant, bkgver parameters are ignored when using the 3C50 model.
Space Weather. For the Space Weather model, specify bkgmodeltype=sw. Example:
nicerl3-spect ... bkgmodeltype=swOnly bkgformat=file is supported, and the output is saved in the file name designated by the bkgfile parameter (defaults to {file}mpu7_bg.pha). The bkgscript, bkgcomponents, bkgvariant, bkgver parameters are ignored when using the Space Weather model.
No Background Model. To disable background estimation, use bkgmodeltype=none.
The default energy range for spectra is channels 22-1501 (0.22 - 15.01 keV). To change this, use the noticerange parameter. Example,
niprefilter ... noticerange=100:800which will notice channels 100-800 (1.0-8.0 keV). This range is used when generating XSPEC scripts, as well as for optimal binning. In addition, the spectrum's QUALITY flags will be set to ignore the un-noticed channels. By default bad channels are set to QUALITY=1, but this can be changed with the badquality parameter.
nicerl3-spect will automatically apply the NICER-recommended systematic error vector to the data. This file is most commonly available in CALDB. To disable this action, set syserrfile=NONE.
nicerl3-spect will automatically call ftgrouppha to optimally rebin the output spectrum, via the GROUPING method. This method appends an additional column to the output spectrum called GROUPING, which designates which channels should be grouped during spectral fitting, while preserving internally all of the channel information.
It uses the ftgrouppha task to perform many possible kinds of grouping. Please see that task's help page for more information.
The default grouping is grouptype=optmin groupscale=10, which is optimal Kaastra & Bleeker binning, with the additional requirement of 10 counts per grouped bin. You can specify a different minimum counts with the groupscale parameter.
Set grouptype=NONE to disable grouping, which leaves the native bin size of 10 eV across the entire spectral range.
nicerl3-spect currently does not adjust or correct spectra for NICER spectra, this is an anticipated future development.
nicerl3-spect is compatible with results of merging multiple product directories into a single one, as done by the niobsmerge task. Simply use the same "obsid" parameter to both niobsmerge and nicerl3-spect. See below for an example.
The task produces a full set of spectral analysis outputs for the user to apply within a spectral analysis environment such as XSPEC.
The outputs are
By default, all outputs are placed in the same directory as the cleaned events. As noted above, by default the names of the output files are governed by a set of shorthand templates. Each of the files will have the same name prefix as the cleaned event file. If the user wishes to choose the output product file names manually by setting the parameter names listed above to explicit file names, that is permitted.
In addition to making data file products, nicerl3-spect is also capable of making graphical outputs. This can be useful for basical diagnostic reporting or for standard pipeline analysis. To enable graphical output, set doplot=YES.
Graphical output requires the presence of XSPEC. The spectral products will be loaded into XSPEC and displayed using the "plot ldata" command. The format of the output is determined by the plotfiles parameter. This should be a wildcard pattern list of XSPEC "hardcopy" output filenames of the form FILENAME/DEVICE. For example, plotfiles="myfile.png/png" will make a PNG graphical file with name myfile. You can make multiple graphical outputs at once with either a space-separated list such as plotfiles="myfile.png/png myfile.ps/cps" (PNG and postscript output), or using the "glob" notation with wildcard braces such as, plotfiles="myfile.{png/png,ps/cps}".
The output products of this task can be used within the XSPEC analysis environment.
To use the products within XSPEC, run the task with outlang=xcm, which is the default. Then start XSPEC and type
@loadfile.xcm
where "loadfile.xcm" is the name of the loadfile generated by the
task. This operation will load the data, responses and background
files/models. At this point the user can start performing spectral
analysis.
To use the products within pyXspec, run the task with outlang=python. The output scripts are in python format and can be used with a Python installation that is compatible and has had the XSPEC python libraries installed.
Start python and execute the following commands.
from xspec import *
exec(open('loadfile.py').read())
The first command initializes the pyXspec module. Any errors
resulting from the first line indicate that pyXspec was not installed
properly. Here, "loadfile.py" is the name of the loadfile generated
by the task. This operation will load the data, responses and
background files/models. At this point the user can start performing
spectral analysis.
The task performs standard and recommended processing steps upon calibrated and screened "Level2" event files, in order to produce high quality spectral products.
Now we will discuss what tasks nicerl3-spect performs.
Extract Spectrum. The NICER task niextspect is used to extract a source+background spectrum file (phafile) from the cleaned event file.
Apply Systematic Error. The NICER task niphasyserr is used to apply a systematic error in the SYS_ERR column. Disable this by setting syserrfile=NONE.
Set QUALITY Column. The NICER task niphaquality is used to apply a QUALITY flag based upon the noticerange setting.
Perform grouping (rebinning). The task ftgrouppha is used to rebin the spectrum.
Create Target ARF Response. The NICER task nicerarf is used to generate an ARF response for the target. The target coordinates from ra and dec task parameters are used to generate the response. The user can specify a source brightness profile, which defaults to a point source.
Create Sky ARF Response. The NICER task nicerarf is used to generate an ARF response a flat-sky surface brightness profile. This ARF may be used for background modeling. In addition to being required by the SCORPEON model, the Sky ARF can be used to model diffuse galactic or extragalactic backgrounds that may be in the NICER field of view.
Create Target X-ray RMF Response. The NICER task nicerrmf is used to generate an RMF response. This RMF may be used for modeling the emission spectrum of the target (as well as for any diffuse X-ray backgrounds).
Generate Background Estimate. The task supports several NICER background estimators (SCORPEON,3c50,Space Weather). See the Background Modeling section below for more detail.
Generate "Load File". A load file is an XSPEC command script ("xcm" file) which contains XSPEC commands to load the products into XSPEC. This file is meant as a starting point for the user to ease them into NICER analysis. Of course the user will likely add more commands to condition the data and establish a spectral model, which can be placed in the load file as well. It is recommended that users save these in a file with a different name, so that it is less likely to overwrite it when running nicerl3-spect at a later date.
nicerl3-spect supports several background modeling techniques. It is designed to be flexible enough for most use cases.
The task supports the SCORPEON model by default. This model attempts to understand the physical basis of the various background components and generate a spectral model that represents their contribution to the background. The model is an actual XSPEC model and not background file, which allows the user to fit the background parameters alongside the target spectral parameters. This gives a better fit as well as a more realistic estimate of uncertainties due to correlations between background and target.
To use the SCORPEON background model, this task uses the niscorpspectmod tool to generate an XSPEC model file. Enable this by setting bkgmodeltype="scorpeon" and bkgformat="xcm". The output is placed in the file name specified by the bkgscript parameter.
SCORPEON. SCORPEON can also generate a static background file, which is more commonly used in X-ray analysis. Generating a background file will be more familiar to users, but also may be less accurate when it comes to spectral fitting. Enable this by setting bkgmodeltype="scorpeon" and bkgformat="file". The output is placed in the file name specified by the bkgfile parameter. In addition to the default SCORPEON model, SCORPEON supports several variants. Please see the help for niscorpeon for more details.
3C50. The task also supports the 3c50 background model due to Remillard et al. 2021. It uses the "nibackgen3c50" task to generate an estimated background file that can be used for spectral analysis. This operation only produces a file and not a fittable model. Enable this by setting bkgmodeltype="3c50" and bkgformat="file". The output is placed in the file name specified by the bkgfile parameter.
The 3C50 model does support the enabling and disabling of individual detectors for an entire observation. Support for partial on-time of some detectors is present but not high fidelity.
Please be aware that by its nature, the 3C50 model does additional quality filtering on the data, and may excluded additional data beyond that done by the user with nimaketime and the standard quality settings. This may leave the user will little or no remaining data. The hbgcut and s0cut parameters can be adjusted to allow more data, at the cost of reducing the quality of the background model.
Space Weather. The task also supports the Space Weather background model due to Gendreau & Corcoran. It will use the nibkgestimator task to generate an estimated background spectrum file that can be used for spectral analysis. This operation produces a file and not a fittable model. Enable this by setting bkgmodeltype="sw" and bkgformat="file". In addition the user must have available the Space Weather auxiliary event file, which is available for download separately.
The Space Weather model does support the enabling and disabling of individual detectors for an entire observation. Support for partial on-time of some detectors is present but not high fidelity.
If the task discovers that there is no good exposure in the event file, then the spectrum file will have EXPOSURE=0. It does not make sense to load such a spectrum within XSPEC, and downstream tools like response generation will not work properly in any case.
The user can detect zero exposure by looking at the error status code from the task. In Bash and Perl, this status is available in the "$?" variable, and in C-shell it's available in the $status variable. A value of 218 would indicate that the output spectrum is unusable, but that no actual error condition occurred. The user should not rely upon any of the outputs being valid when this condition occurs.
Run nicerl3-spect for input directory 1234567890.
nicerl3-spect 1234567890The output products will be placed in 1234567890/xti/event_cl.
Merge product directories from data/[0-9]* and then extract a spectrum. The merged results are placed in a directory named outmerged, with "obsid" set to merged.
ls -d data/[0-9]* > indirs.lis niobsmerge @indirs.lis outdir=outmerged obsid=merged clobber=YES nicerl3-spect outmerged obsid=merged clobber=YES
NICER 3C50 (nibackgen3C50) background model