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.

A given light curve may be observed by different configurations of NICER detectors, and hence the number of enabled detectors changes over time. During the transition, the actual number of detectors may not be known because, for example, there is an unaccounted for fractional second of exposure, or that enable/disable commands take a finite time to execute. For that reason, nicerl3-lc blanks out or censors a short period of time around detector transitions. This censor time range is specified by detnormbuff, the default value of which is 1.6 seconds, which will typically cover about two filter file samples. In order to prevent small variations in numbers of detectors from censoring large parts of the light curve, nicerl3-lc will only censor if the number of detectors changes by more than detnormchg percent, which is 10% by default.

Additional Screening by Time

nicerl3-lc requires certain information to normalize light curves. This information is available in NICER housekeeping at 1 second intervals.

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 (SCORPEON and Space Weather). 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 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.

SCORPEON Background Light Curve Estimation

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.

Background Light Curve Estimation

The task supports the SCORPEN model for background estimation of light curves. It will use the niscorplc tool to provide an estimate of the background in each light curve sample. In addition to creating the background file named by the bkgfile parameter, the background estimates are attached to the main output file (the "lcfile") with the column name BACK_V. In addition, there are columns named like BACK_str where str is the name of each SCORPEON background component. Please note that the SCORPEON background estimate may not be sufficient for direct background subtraction, but mauy be useful to attribute measured light curve background variations to background variations. For more information, please see the niscorplc help file.

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.
(lcthresh=0.1) [real]
Fractional exposure to consider for each light curve bin. A value of 1.0 indicates to require every output bin have full exposure, where the default of 0.1 indicates that every output bin have at least 10% of full exposure. Rate values are computed using the correct exposure regardless of the value of lcthresh. This setting merely decides which potential time bins are excluded due to fractional exposure less than the lcthresh threshold.
(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.
(detnormchg=10) [real]
Percentage change in the number of enabled/selected detectors considered significant enough to consider that the normalization has changed.
(detnormbuff=1.6) [real]
When a change in number of detectors has been detected, detnormbuff is the number of seconds of data to censor around the transition point.
(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 both model types are supported, although the Space Weather model maybe run extremely slowly. 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.
(bkgconfigs="NONE") [string]
A comma-separated list of parameter settings, as described in the help file for the niscorpspectmod task.
(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.

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=SCORPEON
The 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

SEE ALSO

nicerl3-spect

nicerl2

niextlc.html

niobsmerge

niscorplc

niscorpspectmod.html

LAST MODIFIED

May 2023