nicermergeclean HEADAS help file

NAME

nicermergeclean - Merge NICER MPU data and apply standard screening

USAGE

nicermergeclean indir outdir ...

DESCRIPTION

The nicermergeclean task is a high-level task that merges data from multiple NICER MPU slices, and applies standard screening. It is equivalent to running the tasks nimpumerge (for merging MPU data) and nicerclean (for applying screening).

An input to the task is a set of several MPU event files, which have been calibrated but not finely screened. These are typically named niNNNNNNNNNN_0mpuN_ufa.evt, where the "ufa" indicates unscreened but calibrated data. 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. Here "mpu7" means all MPUs, numbered 0-6, have been merged into one file designated as "mpu7."

Another input to the task is a GTI (good time interval) file which contains the desired screening good time intervals. Note that nicermergeclean 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 nicermergeclean.

This task runs the following lower-level NICER tasks to complete its work.

nimpumerge - to merge per-MPU data into a single file.
nicerclean - to apply screening criteria.
niautoscreen - apply per-FPM and per-MPU screening.

In addition to applying good time screening, the nicerclean task also applies per-event screening based on event type and pulse height range. See the documentation for nicerclean for more information.

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, nicermergeclean 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. See nicerclean for more information.

In addition to automatic screening by time, nicerl2 also screens on a per-FPM and per-MPU basis in order to exclude modules that may have problematic conditions, such as high noise rates or high undershoots. This filtering is done when autoscreen=YES, which is set to YES by default. nicermergeclean passes the default screening thresholds to the niautoscreen task which does the actual screening, but these thresholds can be adjusted by setting them to non-default values. For more information on how these screenings are applied, please see the help page for niautoscreen.

PARAMETERS

infiles [string]: The names of input calibrated per-MPU event files. This should either be a comma-separated list, or an @filename.lis style batch file. Nominally, there should be 7 files (MPUs 0-6), and this should match the mpulist selection.
ufafile [filename]: The name of the output merged and calibrated but unscreened file. This is an intermediate step between merging and screening.
clfile [filename]: The name of the output merged, calibrated and screened file (cleaned file). A value of "NONE" is allowed to indicate no cleaned file should be produced, only the ufa file.
(mpulist = "0-6") [string]: List of MPUs to process, either as a comma-seprated list, or as a hypenated range. For example, "0,1,2,3,4,5,6" is the same as "0-6".
(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.
(pirange="20:1500") [string]: Pulse height screening criteria to apply. See above for examples. Either low:high or low-high notation is allowed.
(datamode="so+s+f") [string]: X-ray event type screening, as described in the help for nicerclean.
(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.
(autoscreen=YES) [boolean]: Automatically apply per-FPM and per-MPU screening criteria? If yes, then the niautoscreen task is used to deselect detectors with problematic conditions during individual pointing snapshots. If no, then niautoscreen is not used, but the other filtering criteria are used to screen out global bad times.
(underonlyscr="DEFAULT") [string]: Screening criteria for the high undershoot condition. The value is of the form "nsigma:rbuf", or DEFAULT to use the niautoscreen default values.
(overonlyscr="DEFAULT") [string]: Screening criteria for the high overshoot condition. The value is of the form "nsigma:rbuf", or DEFAULT to use the niautoscreen default values.
(noise25scr="DEFAULT") [string]: Screening criteria for the high noise peak rate condition. The value is of the form "nsigma:rbuf", or DEFAULT to use the niautoscreen default values.
(noiseextscr="DEFAULT") [string]: Screening criteria for the 0.3-0.7 keV "X-ray" band. This band may occasionally have high count rates associated with an extended noise peak, which indicates detector problems. The value is of the form "nsigma:rbuf", or DEFAULT to use the niautoscreen default values.
(mpugtiscr="DEFAULT") [string]: Screening criteria for the per-MPU shredded GTI condition. The value is of the form "nsigma:rbuf", or DEFAULT to use the niautoscreen default values.
(roundrobbinscr="DEFAULT") [string]: Screening criteria for the "round robbin" condition. The value is of the form "nsigma:rbuf", or DEFAULT to use the niautoscreen default values.
(lowmemscr="DEFAULT") [string]: Screening criteria for the LOWMEM FIFO loss amount. This is the number of lost events per GTI. The value is of the form "nsigma:rbuf:min:max", or DEFAULT to use the niautoscreen default values.
(cleaninfiles=NO) [boolean]: If YES, then remove the input per-MPU ufa files. Note that by setting this to YES, the input data will be destroyed. NO is the default.
(nicerclean_args="NONE") [string]: Any additional arguments to nicerclean, such as "EVENT_FLAGS=bx1x000 fastsig=250.0". See the help file for nicer clean for more information. The gtifile, trumpetfilt, and pirange parameters are automatically passed and there is no need to specify them again with nicerclean_args.
(nomerge="NO") [boolean]: If yes, then skip the merging of per-module "ufa" files into the mpu7 merged event file. Other steps are processed normally. Set nomerge=YES if the merged mpu7 has already been created separately.
(mpugtimerge="OR") [string]: How to merge per-MPU GTIs into a single GTI. Either AND or OR. For versions of NICER software before June 2021, "AND" was the implicit default; for later versions "OR" is the default.
(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.

  nicercal indir=1706221428 outdir='$INDIR/xti/event_cl' \
     outfilefile=ufalist.lis
  nimaketime infile=1706221428/auxil/ni1706221428.mkf \
     outfile=standard.gti
  nicermergeclean infiles=@ufalist.lis \
    ufafile=1706221428/xti/event_cl/ni1706221428_0mpu7_ufa.evt \
    clfile=1706221428/xti/event_cl/ni1706221428_0mpu7_cl.evt \
    gtifile=standard.gti

The first two commands are calls to the tasks nicercal and nimaketime. The output of nicercal is a set of calibrated files in the event_cl directory. nicercal also produces an inventory of the files it created, here named ufalist.lis. This file is used as input to nimergeclean. Note that you can also use 'ls' with a wildcard match to find the relevant files, such as

  ls 1706221428/xti/event_cl/ni*_0mpu[0-6]_ufa.evt > ufafiles.lis

The nimaketime call produces a good time file called standard.gti. This is also used as input to nimergeclean.

Finally, the call to nicermergeclean is used to combine the calibrated files into a single file and apply the good time filtering GTI file produced by nimaketime.

LAST MODIFIED