NAME

USAGE

DESCRIPTION

This task applies gain calibration to NICER event files pulse heights, to put all event data onto a common energy scale. The end result is a new column in the output event file, called "PI", which standard for Pulse Invariant. The PI column places all NICER event data onto the same energy scale, which is useful for event screening and energy selection.

The NICER PI column value represents the nominal photon energy in units of (10 eV). For example, a PI value of 675 represents a nominal photon energy of 675*10 = 6750 eV = 6.750 keV. Users should be aware that while this number is useful for basic data screening, the PI value should only be interpreted as an approximate photon energy because of detector response effects.

NICER has two pulse-height related data values for each event, the "slow" pulse height -- PHA -- which is derived from slow-chain electronics, and the "fast" pulse height -- PHA_FAST -- which is derived from the fast-chain electronics. Each of these is calibrated separately, and the resulting columns are named PI and PI_FAST, respectively. Which column is operated upon is specified with the 'column' parameter, which defaults to PI. Thus, to apply gain calibration for both, nicerpi must be run twice, once with column=PI and once with column=PI_FAST.

By default, nicerpi applies sub-bin randomization to the pulse height data. The purpose of randomization is to remove discrete integer rounding effects when translating the pulse height to pulse invariant. Although randomization does introduce a slight energy smearing, the effect is only a few eV, and is required to inter-compare multiple detectors and compute accurate response matrices.

In certain circumstances the NICER team may recommend to re-apply calibration to an event file which has already been calibrated, rather than re-applying to Level1 files from scratch. In that case, set hkfile=NONE and recal=YES. Please be aware that other calibration-related processing related to the task nicerclean would be skipped in this case and care must be taken.

PARAMETERS

infile [filename]

Input file name. Name of a NICER event file to have gain 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.

calfile [filename]

Name of FPM/MPU gain calibration data file, or "CALDB". For standard operation, the NICER team recommends to use "CALDB".

outfile [filename]

Name of output event file, or "INFILE". A new file named outfile will be created with modified PI and/or PI_FAST columns. If outfile=INFILE, then the input file will be modified in place without creating a new file.

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

(recal="NO") [boolean]

Apply revised calibration to event file which already has been calibrated? The default is NO and the user should only set to yes when recommended by the NICER team.

(fastfix="YES") [boolean]

If yes, then fix event files for known fast channel (PHA_FAST and PI_FAST) invalid events.

(cleanup="YES") [boolean]

If yes, then clean up temporary files. If no, temporary files remain. This is typically for debugging.

(timeoffset=0.0) [real]

Constant time offset to add to housekeeping timestamps to bring them into alignment with event timestamps.

(clobber = NO) [boolean]

If the output file already exists, then setting "clobber = yes" will cause it to be overwritten.

(chatter = 1) [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 nicerpi task parameters that were used to produce the output file.

EXAMPLES

This is a typical invocation:

nicerpi crab_pulsar.evt mpu_hk.fits CALDB outfile=INFILE

SEE ALSO

nicercal

LAST MODIFIED