NAME

USAGE

DESCRIPTION

The nicercal task applies standard NICER-recommended calibration processes to an entire NICER observation. NICER data comes from seven independent MPUs (Measurement Power Unit slices). This task uses nimpucal to apply calibration to each slice, one at a time.

This is a high level task that calls nimpucal multiple times, for each MPU slice in turn. Please see the documentation help file for nimpucal for which calibrations are applied and any caveats. In general, nimpucal applies calibration adjustments for gain (PI and PI_FAST) and clock (TIME) correction.

For clock correction, the user may specify a timebiascalfile. It should be a file name, giving the name of a clock calibration file; or CALDB for standard Calibration Database; or NONE to disable clock calibration. The NICER team recommends "CALDB" for most operation.

When clock correction is enabled, then the .mkf filter file is also adjusted to be on the same time base as event files (see mkftimezero). The file is modified in-place. If the .mkf file is gzipped, it will be unzipped before proceeding.

Unlike most HEASoft tasks, this task is designed to work on an entire observation directory. It is expected that the input adheres to the standard NICER directory layout: uncalibrated event files in $INDIR/xti/event_uf; and MPU housekeeping data in $INDIR/xti/hk. However, an advanced programmer can adjust these locations with the hidden parameters.

Upon completion, the calibrated event files are placed in the directory specified by 'outdir'. With default usage, this will be in the observation directory, under xti/event_cl. Input files in the input directory matching *_uf.evt are calibrated and placed in the output directory with name *_ufa.evt. Please note that these defaults can be changed if desired, but changes are not recommended for the beginning user.

If the ra or dec parameters are non-zero, the RA_OBJ and DEC_OBJ keywords of the output files will be written with these values.

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

(outdir = "$INDIR/xti/event_cl") [filename]

Output directory name. Output files will be placed in this directory. Users can use the string $INPUT to duplicate the input directory name. The recommended outdir (="$INDIR/xti/event_cl") will place the output files in the observation directory under the xti/event_cl subdirectory. Note that to use the $INDIR notation from a Unix-like command line shell, users will probably have to use single-quote quoting to avoid variable expansion by the shell itself.

ra [real]

Right ascension of target in J2000 degrees. This parameter is also allowed to be "OBJ", which will use the RA_OBJ keyword from the input file.

dec [real]

Declination ascension of target in J2000 degrees. This parameter is also allowed to be "OBJ", which will use the DEC_OBJ keyword from the input file.

(mpulist = "0-6") [string]

List of MPUs to process, either as a comma-seprated list, or as a hypenated range. For example, "0,1,2,3,4,5,6" is the same as "0-6".

(picalfile="CALDB") [filename]

Name of PI gain calibration data file for slow chain pulse heights, or "CALDB". For standard operation, the NICER team recommends to use "CALDB".

(pifastcalfile="CALDB") [filename]

Name of PI_FAST gain calibration data file for fast chain pulse heights, or "CALDB". For standard operation, the NICER team recommends to use "CALDB".

(timebiascalfile="CALDB") [filename]

Name of clock calibration file, or "CALDB". For standard operation, the NICER team recommends to use "CALDB". A value of "NONE" disables clock calibration.

(leapinit="AUTO") [string]

Initialize LEAPINIT keyword of event extensions? An integer value indicates to use that many leap seconds. A value of "AUTO" indicates use the appropriate number of leap seconds for the given observation TSTART. A value of "NONE" indicates to not change LEAPINIT.

(outfilefile="NONE") [filename]

nicercal can report the output files that it creates. If outfilefile lists a file name, then this file will be created as an ASCII file which lists one output file per line. If outfilefile=NONE, then no output file list is created.

(mkftimezero=-1.0) [real]

When clock correction is enabled, the .mkf filter file TIMEZERO keyword is adjusted to this value. The NICER team does not recommend changing this value. If clock correction is disabled via timebiascalfile=NONE, the .mkf file is not changed.

(filtexpr="EVENT_FLAGS=bxxxx00") [string]

Extractor filtering expression to be used for initial screening of events. Typically this screening expression will remove over-shoot and under-shoot events, which cannot be calibrated, but keep X-ray events and forced triggers (EVENT_FLAGS=bxxxx00).

(ufpat = "$INDIR/xti/event_uf/ni??????????_?mpu?_uf.evt{,.gz}") [string]

Unix wildcard matching expression to locate uncalibrated (unfiltered) events within the input directory. The default expression will locate standard NICER unfiltered ("uf") files within the xti/event_uf subdirectory. If the user has modified the directory layout this pattern can be used to point nicercal to the relevant files. The pattern "$INDIR" is replaced by the 'indir' parameter value (note that proper quoting is required by most command shells to avoid variable expansion).

(hkpat = "$INDIR/xti/hk/ni??????????_?mpu?.hk{,.gz}") [string]

Unix wildcard matching expression to locate MPU housekeeping files within the input directory. The default expression will locate standard NICER housekeeping files within the xti/hk subdirectory. If the user has modified the directory layout this pattern can be used to point nicercal to the relevant files. The pattern "$INDIR" is replaced by the 'indir' parameter value (note that proper quoting is required by most command shells to avoid variable expansion).

(mkfpat = "$INDIR/auxil/ni??????????.mkf{,.gz}") [string]

Unix wildcard matching expression to locate the .mkf filter file. This pattern is used when applying time calibration. The pattern "$INDIR" is replaced by the 'indir' parameter value (note that proper quoting is required by most command shells to avoid variable expansion).

(mpupat = "mpu(\d+)") [string]

Perl-style regular expression to capture the MPU slice number from the file name. The default value captures the number N from the mpuN in NICER standard event files. There must be exactly one capture phrase in the expression which identifies the MPU slice number.

(uftagpat = "_uf\.evt") [string]

Perl-style regular expression to match the unfiltered event file tag, typically, "_uf.evt". The backslash is required to make it a proper regular expression. This tag is replaced by the cltagpat to construct the output file name.

(cltagpat = "_ufa.evt") [string]

String used to replace the uftagpat pattern when creating the output file. This is a normal string, not a regular expression, and no variables are possible. The default transforms "uf" into "ufa" files.

(initialize="YES") [boolean]

If YES, then initialize all values to NULL before calibration. If NO, then start with previous values before recomputing calibration.

(randomize="YES") [boolean]

Apply sub-bin randomization to pulse-height values? See above.

(randomseed=0) [integer]

The initial random seed integer value for randomization. This is primarly for testing purposes so that repeatable results can be obtained. If randomseed=0, the default, then the random seed is computed based on date, so that it should normally be different for each invocation.

(calstation="FLIGHT") [string]

Station where data was collected. For in-flight operations use calstation=FLIGHT. For ground-based testing, other values can be used. This parameter selects the NICSTATN keyword value in CALDB.

(caldbver="INDEF") [string]

String to use for CALDBVER keyword in output files. Note that this keyword is documentary only, it does not change the operation of the task or how the calibration is applied. A value of INDEF indicates to not update CALDBVER.

(softver="INDEF") [string]

String to use for SOFTVER keyword in output files. Note that this keyword is documentary only, it does not change the operation of the task or how the calibration is applied. A value of INDEF indicates to not update SOFTVER.

(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]

Amount of verbosity of the task. For chatter=0, no output is printed. For chatter=5, debugging output is printed.

(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 task parameters that were used to produce the output file.

EXAMPLES

1. Apply NICER calibration to data from observation 1706221428.

  nicercal indir=1706221428 outdir='$INDIR/xti/event_cl' clobber=YES 

The input directory is a NICER observation number 1706221428. The output files are placed in the observation directory under 1706221428/xti/event_cl/ni1706221428_0mpu*_ufa.evt. Note that single quotes are used to prevent $INDIR from being expanded by the Unix shell. The default calibrations files are taken from CALDB.

SEE ALSO

nicerpi,

nimpucal

LAST MODIFIED