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).
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.
nicercal, nimpucal, nimaketime, nicermergeclean