NAME
nicerpi - apply gain calibration to NICER event file (calculate Energy/PI)
USAGE
nicerpi infile hkfile calfile [outfile]
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
The event file to be calibrated is crab_pulsar.evt. Since outfile=INFILE, the input file
is modified in place. The task queries CALDB for the gain calibration file.
SEE ALSO
nicercal
LAST MODIFIED
Sep 2022