NAME

nicerl3-lc - NICER full standard light curve analysis chain

USAGE

nicerl3-lc indir

DESCRIPTION

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.

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

Outputs

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.

Normalization

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.

Task Operation

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 (Space Weather only). See the Background Modeling section below for more detail.

Background Modeling

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, no background is computed. To have a background estimate computed, set bkgmodeltype to one of the allowed background models, which is currently just 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 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.

Special Conditions

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.

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.
pirange=30:800 [string]
Pulse height range to extract light curve from, in the form start-end (inclusive). See above for a discussion regarding meaning of the PI value. Either the low-high or low:high notation is permitted.
timebin=30.0 [real]
Time bin size in seconds.
(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.
(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.
(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.
(lcfile="$INROOTmpu7_sr$SUFFIX.lc") [string]
Name of output light curve file.
(bkgfile="$INROOTmpu7_bg$SUFFIX.lc") [string]
Name of output background light curve file.
(skyarffile="$INROOTmpu7_sk$SUFFIX.arf") [string]
Name of input Sky ARF file, used by the SCORPEON model. This should be the same file generated by nicerl3-spect.
(rmffile="$INROOTmpu7$SUFFIX.rmf") [string]
Name of input X-ray RMF file, used by the SCORPEON model. This should be the same file generated by nicerl3-spect.
(bkgrmffile="$INROOTmpu7_bk$SUFFIX.rmf") [string]
Name of input background RMF file, used by the SCORPEON model. This should be the same file generated by nicerl3-spect.
(detnormtype="arr52") [string]
Determines how the light curve samples are normalized by number of selected detectors. A value of "arr52" will normalize to an equivalent array with all 52 detectors enabled. A value of "fpm" will normalize to per FPM. A value of "NONE" will not normalize the output, meaning the values will be the total array count, which may be higher or lower depending on the number of FPM detectors selected.
(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="none") [string]
Name of background model type, either "scorpeon" (SCORPEON model) or "sw" (Space Weather model). Note that only the Space Weather model is supported at this time. A value of "none" indicates to not estimate background but perform all other tasks.
(bkgmodelformat="bkgmodelformat") [string]
Output background model format, either "file" or "xcm" (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.
(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-lc 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-lc. 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.
(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-lc task parameters that were used to produce the output file.

EXAMPLES

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.0

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-lc outmerged 30-200 120.0 obsid=merged clobber=YES

SEE ALSO

nicerl3-spect

nicerl2

niextlc.html

niobsmerge

LAST MODIFIED

May 2023