nicerclean - Apply standard NICER screening


nicerclean infile outfile ...


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.

In older versions of nicerclean, it was recommended to use the filtexpr keyword to specify a filtering expression for the EVENT_FLAGS column of the event file. As of version 1.12, nicerclean now recommends to use the supplied keyword parameters to filter events by type. These keywords are:

By default, events from the slow chain are included (and optionally fast chain), which is equivalent to datamode=so+s+f. This is the setting recommended by the NICER team for almost all circumstances.

The older, non-recommended method to specify event types was to use an EVENT_FLAG filter. Users can change this setting by changing the filtexpr parameter as follows.

For backwards compatibility reasons, it is still permitted to use such a filtexpr. If the expression is simple, consisting of just an EVENT_FLAGS filter, the task will automatically translate the flags to the equivalent parameter settings.

However, if the filtexpr expression is complex, involving more than just an EVENT_FLAGS filtering expression, then nicerclean will be unable to parse the expression reliably. In this case, nicerclean uses the filtexpr as-is without changes.

Note that if you use a "complex" filtering expression, the settings for keep_undershoots, keep_overshoots, keep_forced and keep_noisering will be ignored. If you plan on using these parameters, you should remove the EVENT_FLAGS portion of the expression and replace it with the proper keep_* parameter values.

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.

By default, nicerclean assumes the input file has FPM Selection information included, and will update it upon output. Set fpmsel=NO to disable this action.

As of 2023, the NICER team is aware of a new phenomenon which is designated "noise ringers." These are events that arrive very shortly after an undershoot in the same FPM, almost always within 110 usec, and only at undershoot rates that exceed about 80 undershoots per second, per FPM. The NICER software flags these events with EVENT_FLAGS=bx1xxxxxx (i.e. bit 6).

To screen out such events above an undershoot rate of 80 ct/s/FPM, set keep_noisering=NO and noisering_under=80. This screening is applied on an FPM-by-FPM basis, and doesn't change the good-time of an FPM (although it adds roughly 110 usec of deadtime in the same FPM after an undershoot).


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. Either low:high or low-high notation is allowed.
(filtexpr="NONE") [string]
Extractor filtering expression to be used for screening of events. See above for common screening expressions. Note that by default filtexpr=NONE, because event-type filtering is expected to be done by setting the keep_* keywords. However, one can still use EVENT_FLAG filting.
(datamode="so+s+f") [string]
X-ray event type screening, as described above.
(keep_overshoots=NO) [boolean]
Set to NO to screen out overshoots, or to YES to permit them.
(keep_undershoots=NO) [boolean]
Set to NO to screen out undershoots, or to YES to permit them.
(keep_forced=NO) [boolean]
Set to NO to screen out forced triggers, or to YES to permit them.
(keep_noisering=NO) [boolean]
Set to NO to screen out noise ringers, or to YES to permit them. Note that if noisering_under is set, then the per-FPM undershoot rate is also required to exceed that value before a noise ringer is excluded.
(noisering_under=80) [real]
The per-FPM undershoot rate, above which events with the noise ringer bit flag set are screened out. If noisering_under=0, then keep_noisering is followed always, regardless of undershoot rate.
(cleanup="YES") [boolean]
If yes, then clean up temporary files. If no, temporary files remain. This is typically for debugging.
(fpmsel="YES") [boolean]
If yes, then modify FPM Selection information.
(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.


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 \

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.


nicercal, nimpucal, nimaketime, nicermergeclean


Jun 2023