nimpumerge HEADAS help file

NAME

nimpumerge - Merge NICER event data from multiple MPUs (or observations)

USAGE

nimpumerge infiles outfile ...

DESCRIPTION

The nimpumerge task merges NICER MPU event data.

Typically nimpumerge will be used to merge event data from multiple MPU slices into a single output event list file. The task is able to merge the MPU slice event data from a single observation, but also multiple observations.

In addition, nimpumerge is able to merge data from already-merged "MPU 7" files, with the setting mpulist=7. This would typically be used to merge data from multiple observations into a single file. Note that "MPU 7" data is assumed to have FPM Selection data.

IMPORTANT NOTE: Only combine the calibrated but unfiltered output files, so called "ufa" or "cl" files. "ufa" files can be produced using the nicercal task. Although it is possible to combined raw unfiltered data ("uf" files) without errors, it will be impossible to calibrate these files with standard tasks afterward. Therefore, only use this task on "ufa" or "cl" files.

The output file contains a merged event list from all input files. The standard "GTI" extension is present and represents the common observation times of all MPUs (i.e. the intersection or "AND" merge of the individual MPUs). If multiple observations are combined from disjoint times, these good times are combined with union or "OR" merger. In addition to the combined GTI, the individual per-MPU GTIs are also stored in the output with extension names, GTI_MPUn, where n is MPU slice number between 0 and 6.

PARAMETERS

infiles [string]: List of one or more input files, or an @filename.lis list file. The individual files should be individual MPU files and not an already-merged file.
outfile [filename]: Name of output file. A merged event file with this name will be created.
(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". The allowed values are "0-6" for per-MPU slice data or "7" for a merged list.
(timesort = "YES") [boolean]: If YES, then the output is sorted ascending by the TIME column. If NO, then the resulting output is not sorted in any particular way.
(timefile = "NONE") [string]: Time filtering GTI to be applied, or NONE if no GTI is to be applied.
(filtexpr = "NONE") [string]: Extractor-like interval filtering expression to apply to the events before merging. This can be a shorthand way to apply additional screening before combining individual inputs. A value of NONE means do no special event screening. See documentation for niextract-events for more information about interval filtering expressions.
(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.
(mpupat = "mpu(\d+)") [string]: Perl-style regular expression to capture the MPU slice number from the file name. The default value captures the number N from the mpuN in NICER standard event files. There must be exactly one capture phrase in the expression which identifies the MPU slice number.
(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

1. Merge per-slice data from multiple MPUs from one observation.

  ls obs1/xti/event_cl/ni*_ufa.evt > evtfiles.lis
  nimpumerge infiles=@evtfiles.lis outfile=merged.evt

The input directory is a NICER observation with name 'obs1'. The first command is ls which lists the calibrated but unfiltered event files and saves it as a list file (evtfiles.lis). The call to nimpumerge combines these files into a single output called merged.evt.

2. Merge per-slice data from multiple observations.

  ls {obs1,obs2}/xti/event_cl/ni*_0mpu[0-6]_ufa.evt > evtfiles.lis
  nimpumerge infiles=@evtfiles.lis outfile=merged.evt

This is basically the same command as variation 1 listed above, but the "ls" command lists calibrated files from two different observation directories, here listed as obs1 and obs2. MPU data from both observations is combined into a single time-sorted event list file.

3. Merge "MPU 7" data from multiple observations using "ufa" file.

  ls {obs1,obs2}/xti/event_cl/ni*_0mpu7_ufa.evt > evtfiles.lis
  nimpumerge infiles=@evtfiles.lis outfile=merged_ufa.evt mpulist=7

4. Merge "MPU 7" data from multiple observations using "cl" file.

  ls {obs1,obs2}/xti/event_cl/ni*_0mpu7_cl.evt > evtfiles.lis
  nimpumerge infiles=@evtfiles.lis outfile=merged_cl.evt mpulist=7

LAST MODIFIED