NAME

nicerl3-spect - NICER full standard spectral analysis chain

USAGE

nicerl3-spect indir

DESCRIPTION

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.

Inputs

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.

Controlling How nicerl3-spect Functions

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.

Background Estimation

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=python
and 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=3c50
Only 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=sw
Only 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.

Valid Energy Range

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:800
which 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.

Systematic Error

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.

Optimal Binning (Grouping)

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.

Deadtime

nicerl3-spect currently does not adjust or correct spectra for NICER spectra, this is an anticipated future development.

Using Merged Data

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.

Outputs

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}".

Using Within XSPEC

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.

Python Usage

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.

Task Operation

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.

Background Modeling

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.

Special Conditions

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.

PARAMETERS

indir [filename]
Input directory name. The directory should be a single NICER observation directory, which in turn contains xti/{events_uf,events_cl,hk,auxil} subdirectories. Note that if you specify all file names explicitly, indir can be a dummy directory name.
(ra="OBJ") [string]
Right ascension of target in J2000 degrees. This parameter is also allowed to be "OBJ" or "NOM", which will use the RA_OBJ or RA_NOM keywords from the input file, respectively.
(dec="OBJ") [string]
Declination of target in J2000 degrees. This parameter is also allowed to be "OBJ" or "NOM", which will use the DEC_OBJ or DEC_NOM keywords from the input file, respectively.
(cldir = "$INDIR/xti/event_cl") [string]
Subdirectory where the output files as listed above are placed. This parameter is subject to pattern substitution $INDIR as described above. Note that if you specify all file names explicitly, indir can be a dummy directory name.
(clfile = "$CLDIR/ni$OBSID_0mpu7_cl.evt") [string]
Name of the master "cl" event file to be created. This parameter is subject to pattern substitutions $INDIR, $CLDIR and $OBSID as described above.
(ufafile = "$CLDIR/ni$OBSID_0mpu7_ufa.evt") [string]
Name of the master "ufa" event file to be created. This parameter is subject to pattern substitutions $INDIR, $CLDIR and $OBSID as described above. You may set ufafile=NONE if you are not using the 3C50 background model.
(mkfile="$CLDIR/ni$OBSID.mkf,$INDIR/auxil/ni$OBSID.mkf") [string]
Name of the filter file (.mkf file). This is a series of comma-separated paths to check, in order.
(phafile="$INROOTmpu7_sr$SUFFIX.pha") [string]
Name of output spectrum file.
(bkgfile="$INROOTmpu7_bg$SUFFIX.pha") [string]
Name of output background spectrum file, if bkgformat=file.
(bkgscript="$INROOTmpu7_bg$SUFFIX.$LANG") [string]
Name of output background spectrum model script file, if bkgformat=script. Here $LANG is ".py" for outlang=python and ".xcm" otherwise.
(bkgformat="model") [string]
Format of output, either "model" (XSPEC model, only applicable to the SCORPEON model) or "file", which is a standard background file.
(outlang="xcm") [string]
Language of load script and (optionally) the background model script, either "python" or "xcm" (XSPEC command script). Note that the format of the background, controlled by bkgformat determines whether the background is a fittable model or a static file, whereas the output language is the language that scripts are written in.
(loadfile="$INROOTmpu7_load$SUFFIX.$LANG") [string]
Name of output (py)XSPEC command file to load the products. Here $LANG is ".py" for outlang=python and ".xcm" otherwise.
(arffile="$INROOTmpu7$SUFFIX.arf") [string]
Name of output Target ARF file.
(skyarffile="$INROOTmpu7_sk$SUFFIX.arf") [string]
Name of output Sky ARF file.
(rmffile="$INROOTmpu7$SUFFIX.rmf") [string]
Name of output X-ray RMF file.
(bkgrmffile="$INROOTmpu7_bk$SUFFIX.rmf") [string]
Name of output background RMF file.
(plotfiles="$INROOTmpu7_sr$SUFFIX.png/png") [string]
A "glob" pattern of graphical output hardcopy output specifications of the form FILENAME/DEVICE, where FILENAME is the graphical file name and DEVICE is the PGPLOT output device. This can either be a space-separated list of FILENAME/DEVICE pairs, such as plotfiles="myfile.png/png myfile.ps/ps" or it can use wildcard brace matching like plotfiles="myfile.{png/png,ps/ps,svg/svg}" to avoid typing the output file name more than once.
(bkgmodeltype="scorpeon") [string]
Name of background model type, either "3c50" (3C50 model), "scorpeon" (SCORPEON model) or "sw" (Space Weather model). A value of "none" means to disable background modeling.
(bkgformat="INDEF") [string]
Output background model format, either "file" or "model" format. A value of INDEF indicates a model-specific default should be chosen.
(bkgcomponents="INDEF") [string]
For the SCORPEON model, which SCORPEON background components to include. A value of INDEF indicates to use the model-specific default.
(bkgver="INDEF") [string]
For the SCORPEON model, which SCORPEON background model version to use. A value of INDEF indicates to use the most recent version.
(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.
(profile="point") [string]
X-ray surface brightness profile name. Must be one of "point" (point-like), "flat" (flat sky background), "gaussian" (Gaussian). See the help for nicerarf for more details.
(profpar="NONE") [string]
Special parameters for given X-ray surface brightness profile. See the help for nicerarf for more details.
(angunit="arcsec") [string]
Specifies the units of angular quantities. In particular, when profile="flat", angunit specifies the units of solid angle. Allowed values are "arcsec", "arcmin", "deg", "rad", "sr". For example, when angunit="arcsec" the output units will be arcsec^2. See the help for nicerarf for more details.
(detlist="launch") [string]
A comma-separated list of detectors to include or exclude. This list is evaluated from left to right, in that order. Each list item can be: If the first list item is an exclusion, then it is assumed that "launch" detectors are enabled to begin with.
(suffix="") [string]
An optional suffix string, which will be placed in every output file name by default. By default this is the empty string, which indicates no special suffix. The suffix can be used for version control or testing purposes, to allow different runs of nicerl3-spect to have different output names.
(gtifile="NONE") [string]
Name of a time filter file, as a single GTI file. Although this is allowed, it is recommended to do time filtering using niextract-events before running nicerl3-spect. Note that using a gtifile is not possible if you use the 3C50 background model.
(obsid="AUTO") [string]
The observation ID to use for documentation purposes and for scanning directories for required files. A value of AUTO means to scan for the first available file and use the observation ID of that file for subsequent documentation.
(noticerange="22:1501") [string]
NICER PI bin range to notice within XSPEC. These PI bins will be noticed, inclusive. Only a single range can be specified.
(badquality = 1) [integer]
The QUALITY value to use. See above for defined values
(syserrfile="CALDB") [string]
NICER systematic error vector to apply to spectrum. Use "CALDB" to consult NICER CALDB, or "NONE" to not apply the systematic error vector.
(syserrfactor=1.0) [real]
Scale factor for systematic error values.

(updatepha="NO") [boolean]
If set, then the output spectrum will have updated BACKFILE, ANCRFILE and RESPFILE keywords, which allows XSPEC to load the spectrum files with greater user ease. The default is set to "NO," because these keywords can often cause confusion and difficulty within XSPEC if the files are accessed from a working directory different from the directory where they were created.
(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 nicerl3-spect task parameters that were used to produce the output file.

EXAMPLES

Run nicerl3-spect for input directory 1234567890.


   nicerl3-spect 1234567890

The 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

SEE ALSO

nicerl3-lc

nicerl2

nicerarf

nicerrmf

niextspect.html

niphasyserr

niphaquality

NICER SCORPEON model

niscorpspectmod.html

niscorpspect.html

NICER Space Weather model

NICER 3C50 (nibackgen3C50) background model

ftgrouppha

niobsmerge

LAST MODIFIED

May 2023