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.

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.

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.
(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