NAME

USAGE

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 known time biases.
4. PI_RATIO. The PI_RATIO column represents the ratio (PI/PI_FAST).

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.

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

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.

(ra=0.0) [real]

Value to assign to RA_OBJ in the input file, or 0 to leave RA_OBJ unchanged.

(dec=0.0) [real]

Value to assign to DEC_OBJ in the input file, or 0 to leave DEC_OBJ unchanged.

(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