NAME

nicerclean - Apply standard NICER screening

USAGE

nicerclean infile outfile ...

DESCRIPTION

The nicerclean task is a high-level task that applies standard screening.

The input to the task is a single merged event file, as produced by nimpumerge. This would typically be named niNNNNNNNNNN_0mpu7_ufa.evt, where the "ufa" indicates unscreened but calibrated data. Here "mpu7" means all MPUs, numbered 0-6, have been merged into one file designated as "mpu7." The output of the task is a single merged and screened event file, which is typically named niNNNNNNNNNN_0mpu7_cl.evt, where the "cl" indicates a cleaned event file.

Another input to the task is a GTI (good time interval) file which contains the desired screening good time intervals. Note that nicerclean does not by itself create a GTI file, but rather uses one created externally by the user. The NICER team recommends to use nimaketime first to accomplish this, before running nicerclean.

In addition to applying good time screening, the task also applies per-event screening based on event type and pulse height range. By default, events from the slow chain are included (and maybe fast chain). Users can change this setting by changing the filtexpr parameter as follows.

The NICER team recommends to keep the default event type screening.

By default, events with pulse invariant (PI) pulse heights above 20 (i.e. 200 eV and above). This can be changed using the pirange parameter. For example, use pirange=35:1000 to select events with nominal pulse heights in the range 0.35 - 10.00 keV.

When trumpetfilt=YES, nicerclean performs standard filtering to exclude background events using the event PI_RATIO column. This is known as "trumpet" filtering since the PI vs PI_RATIO cloud looks like a trumpet. This filtering expression is equivalent to the expression,

    PI_RATIO < fastconst + (fastsig/10 eV)/PI + fastquart*PI**3
where fastconst=1.1 is the overall ratio threshold (nominal ratio is 1.0 with a tolerance of 0.1 = 10%); fastsig=1200 eV is the noise level threshold for the fast chain, and fastquart=0 is the fast chain quartic error (0 in most cases). Both default values are determined experimentally based on the fast chain threshold performance. When PI_RATIO is undefined (especialy below approximately 600 eV, where the fast chain becomes insensitive), this selection defaults to accepting events.

PARAMETERS

infile [string]
The name of the input calibrated MPU-merged event file.
outfile [filename]
The name of the output merged, calibrated and screened file (cleaned file).
(gtifile="NONE") [string]
Name of the good time interval (GTI) screening file, or NONE if no good time screening is to be performed.
(trumpetfilt=YES) [boolean]
Apply standard background PI_RATIO filtering.
(fastconst=1.1) [real]
Trumpet ratio constant cut.
(fastsig=1200.0) [real]
Fast chain noise level in eV. The "trumpet" flare becomes dominant below E=fastsig.
(fastquart=0.0) [real]
Fast chain quartic gain error as shown above. No longer used with improved fast chain calibration.
(pirange="20:1500") [string]
Pulse height screening criteria to apply. See above for examples.
(filtexpr="EVENT_FLAGS=bx1x000") [string]
Extractor filtering expression to be used for screening of events. See above for common screening expressions.
(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

Merge and clean an event file.

  nicerclean infile=1706221428/xti/event_cl/ni1706221428_0mpu7_ufa.evt \
    outfile=1706221428/xti/event_cl/ni1706221428_0mpu7_cl.evt \
    gtifile=standard.gti

The command takes as input one "ufa" file and applies standard screening to produce one output "cl" file. The good time interval file standard.gti is used for time screening. Default event filtering is applied.

SEE ALSO

nicercal, nimpucal, nimaketime, nicermergeclean

LAST MODIFIED

Mar 2018