The nicerl3-lc task is a full NICER light curve analysis chain. It starts with a Level2 cleaned event file and produces a light curve file and background estimates.
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-lc 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 background model.
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.
The task produces a full set of light curve analysis outputs for the user.
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.
The output light curve is binned according to the user's requested time binning (timebin parameter), in the requested energy channel range (pirange parameter). As a reminder to the NICER user, one PI bin is equivalent to 0.01 keV, so setting pirange=30:500 means 0.3-5.0 keV.
In addition to making data file products, nicerl3-lc 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.
The graphical output can display the X-axis as "time" in two different ways. When plottime=time (the default), then the X-axis is displayed as calendar time, which is the usual definition for a light curve plot. However, this form of display is often difficult to visualize for a typical NICER observation, which has more time gaps than it has valid data. The light curve shows up as clusters of points for each GTI that are difficult to distinguish.
Therefore, there is an additional setting, plottime=sandwich. In this plotting mode, the X-axis is essentially bin number, multiplied by the bin size. This form is useful to distguish variations from point to point. However, any absolute time information is not visible on this form of plot.
nicerl3-lc can normalize by the number of selected FPM detectors. This allows long-term light curves to reflect better the flux of an astrophysical source, even if the number of selected detectors may change over time (due to disabling or due to autoscreening). The normalization uses the "FPM Selection" information data, which is stored in the clfile's FPM_SEL extension. Users should take care to maintain FPM Selection information in an accurate state by using only NICER tools to manipulate event files. In other words, do not use "extractor" or "xselect" to filter events.
The normalization is governed by the "detnormtype" parameter.
The default value of "arr52" will scale the resulting count rate to a fictitious array consisting of 52 detectors (i.e. a state where all detectors would be enabled).
A value of "fpm" will normalize so that the count rate is per selected FPM.
A value of "NONE" will not normalize the count rate, so it will be subject to variations if the number of selected detectors increases or decreases during an observation.
Please note that for NICERDAS 10 and earlier (HEASoft 6.31.1 and earlier), the tool did not normalize by number of detectors, which means the previous default was effectively detnormtype=NONE.
The task performs standard and recommended processing steps upon calibrated and screened "Level2" event files, in order to produce high quality light curve.
Now we will discuss what tasks nicerl3-lc performs.
Extract Light Curve. The NICER task niextlc is used to extract a source+background light curve file (lcfile) from the cleaned event file.
Generate Background Estimate. The task supports several NICER background estimators (SCORPEON and Space Weather). See the Background Modeling section below for more detail.
nicerl3-lc supports several background modeling techniques. It is designed to be flexible enough for most use cases.
Note that by default bkgmodeltype=none, which means that no background model is computed. To have a background estimate computed, set bkgmodeltype to one of the allowed background models, which is currently either SCORPEON (bkgmodeltype=scorpeon) or Space Weather (bkgmodeltype=sw).
In addition to generating a background file, the background estimtes are inserted into the light curve file (lcfile) in the BACKV (background rate) and BACKE (background rate error) columns. The channel selections match those of the source light curve.
The task supports the SCORPEON background model. In this usage, the task uses fixed a priori estimates of the background by SCORPEON, and the background parameters are not fittable as they are for spectral analysis. However, the background components do vary with time and this variation is captured in the background estimate.
To use the SCORPEON model, you will need to set bkgmodeltype=scorpeon, and provide the "Sky ARF" and "RMF" responses. These responses are produced as output by nicerl3-spect and you can use those products directly as input for nicerl3-lc. nicerl3-lc will automatically choose these files, if they have the default names. To specify them explicitly use the following command line options:
nicerl3-lc ... bkgmodeltype=scorpeon \
skyarffile=/path/to/file.arf rmffile=/path/to/file.rmf
where file.arf and file.rmf are the "Sky" ARF and detector response
matrix for this observation. Note that the RMF file is not
the "background" RMF produced by nicerl3-spect.
In addition to the BACKV and BACKE columns, which report the total estimated background, the SCORPEON model also produces estimates for each component that it tracks, and reports them as separate columns. These columns are named BACK_name where name is the name of the component. The possible names are: BASELINE, COR, TREL, PREL, SAA.
The task supports the Space Weather background model due to Gendreau & Corcoran. It will use the nibkgestimator_lc task to generate an estimated background light curve 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 bkgmodelformat="file". In addition the user must have available the Space Weather auxiliary event file, which is available for download separately.
If the task discovers that there is no good exposure in the event file, then the light curve file will have EXPOSURE=0. It does not make sense to use such a light curve.
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 file 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-lc for input directory 1234567890, for pulse heights 30-200 (0.3-2.0 keV) and 120 second time bins.
nicerl3-lc 1234567890 30-200 120.0The output products will be placed in 1234567890/xti/event_cl.
Run nicerl3-lc for input directory 1234567890, for pulse heights 30-200 (0.3-2.0 keV) and 120 second time bins, and select the SCORPEON background model.
nicerl3-lc 1234567890 30-200 120.0 bkgmodeltype=SCORPEONThe output products will be placed in 1234567890/xti/event_cl. If you use non-default names for the response files, then please see above for more information.
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-lc outmerged 30-200 120.0 obsid=merged clobber=YES