NAME

nimpucal - Apply standard NICER calibration to MPU data

USAGE

nimpucal infile hkfile outfile ...

DESCRIPTION

The nimpucal task applies standard NICER-recommended calibration processes to NICER data. NICER data comes from seven independent MPUs (Measurement Power Unit slices) and this task applies to data from a single MPU slice. To apply calibration to all slices, use the high level task nicercal.

After calibration, a new event file is produced. The new events are on a common gain scale, and have the columns PI, PI_FAST and PI_RATIO, as described below. Data from all detectors can be merged. (see nimpumerge)

The standard calibrations applied are:

  1. PI calibration. The nicerpi task applies gain calibration to calculate the PI (pulse invariant) column for the slow channel.
  2. PI_FAST calibration. The nicerpi task applies gain calibration to calculate the PI_FAST column for the fast channel, where available.
  3. TIME calibration. The nicertimecal task applies clock correction to adjust for know time biases.
  4. PI_RATIO. The PI_RATIO column represents the ratio (PI/PI_FAST).

Some calibrations are not applied. At present, no attempt is made to apply absolute timing calibration. Without timing calibration, it is anticipated that event timestamps 400-600 nsec absolute timing error, and approximately 100 nsec timing offset error between slow-only and slow+fast channel timestamps.

As documented on the nicerpi help page, the gain scale for pulse invariant is set so that:
PI = (ENERGY / 10 eV)
where ENERGY is the nominal photon energy. The same applies for PI_FAST.

The PI_RATIO column represents the ratio of PI / PI_FAST, i.e. the ratio of slow to fast corrected pulse heights. In principle these quantities are approximately equal, but in practice, they are slightly different for particle background events, diffuse X-ray background events, and concentrated X-rays from the target. This ratio can be used for background screening when both pulse heights are available.

PARAMETERS

infile [filename]
Input file name. Name of a NICER event file to have calibration performed upon it. If outfile=INFILE then the input file will be modified in place, otherwise it will be untouched.
hkfile [filename]
Name of MPU housekeeping file, available in each observation.
outfile [filename]
Name of output event file, or "INFILE". A new file named outfile will be created with this name. If outfile=INFILE, then the input file will be modified in place without creating a new file.
(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 data file for correcting TIME column, or "CALDB". For standard operation, the NICER team recommends to use "CALDB".
(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.
(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).
(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.
(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 MPU1.

  nimpucal infile=ni1706221428_0mpu1_uf.evt outfile=ni1706221428_0mpu1_ufa.evt \
    hkfile=ni1706221428_0mpu1.hk

The input file is the "uf" (unfiltered) events. Calibrations are applied to this file and the result is placed in the "ufa" (unfiltered but calibrated) event file. The housekeeping file must match the same MPU. Calibration data is taken from CALDB default.

SEE ALSO

nicerpi,

nicercal

LAST MODIFIED

Apr 2018