NAME

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

USAGE

nimpumerge infiles outfile ...

DESCRIPTION

The nimpumerge task merges event data from multiple MPU slices into a single output event list file.

nimpumerge can also merge files from multiple observations. You must start with the individual MPU files when doing this.

IMPORTANT NOTE: Only combine the calibrated but unfiltered output files, so called "ufa" files. These can be produced using the nicercal task. It is possible to combined raw unfiltered data ("uf" files) without errors. However, it will be impossible to calibrate these files with standard tasks.

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".
(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.
(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 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 data from multiple observations.

  ls {obs1,obs2}/xti/event_cl/ni*_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.

SEE ALSO

nicercal, niextract-events

LAST MODIFIED

Mar 2018