NAME

mecatobs - conCATenate files belonging to same OBServing period (MECS)

SYNOPSIS

mecatobs [filelist=] [parameter=value ...]

DESCRIPTION

mecatobs is used to concatenate MECS event list files (both, _rev and _lev types are supported) that logically belong to the same observing period into one larger sum file. For each input file it is checked whether a corresponding science HK and eng files exist. If this is the case, the program creates a sum HK file and a sum eng file as well. The primary and all Bintable extension headers of the sum files are copies of the corresponding headers of the first file in the list of files specified for concatenation. All time related keywords, such as TSTOP, TELAPSE, etc. are updated where necessary to reflect the larger time coverage of the sum files. In addition, history keywords are added to the primary headers and the N_OBIS keyword value is set to the number of input files.

The list of input files given in the file filelist is strictly processed from up to down. Therefore, to ensure a proper time order of the event list data in the sum file, the individual files have to be specified in the right temporal order, i.e., in ascending order of the values of the TSTART keyword. Also, the program expects the very last file in the filelist list to contain the largest time tag values. Under this assumption the values of various time-related header keywords in the sum events files are derived from the headers of this last file in the list. The meselobs task can be used to obtain a list of compatible event list files in the proper temporal order. They may be executed together on a single command line using a pipe.

PARAMETERS

The following command line parameters are recognized by the program:

fileslist = "" [string: file containing a list of event files]

If set to stdin the program expects the file names to be typed manually separated by carriage returns.
Note that the files are strictly processed from up to down and, consequently, have to be in the proper temporal order (see the warning in the above note). If a file in filelist does not exist or is found to be impossible to be appended to the sum file, a warning message is issued and the processing continues with the next file in the list.



stemoutfile = "-" [string]

This determines the file name stem of the sum file(s) to be created. The stem of a file name is defined to be everything before any extension _???.fits, e.g., the name stem of kv492_rev.fits is just kv492. Specifying "-" for stemoutfile means that the actual value shall be derived from the name of the first file in the infiles list which is expected to follow the naming scheme used by the FOT ingestor foting:

     <Stem>_<FOT_ID>_<Instrument_ID>_<ObsID>_<Number>_rev.fits

If the first file is found to match this pattern the sum file will get the name

     <Stem>_<FOT_ID>_<Instrument_ID>_<Sum_ID>_rev.fits

otherwise, sum_rev.fits.



outdir = "=" [string: name of existing directory or "="]

The name of a directory to which the output file(s) shall be written. "=" means that the resulting sum file(s) shall be created in the directory the very first file in the infiles list was found. Note that write access for outdir is needed.



hkconcat = yes [boolean: yes|no]

If set to "yes", for each input event file it is checked whether a corresponding science HK file exists. If this is the case, a concatenated version of all single HK files is created similar to the event list sum file. "no" as value suppresses the HK sum file creation.



engconcat = yes [boolean: yes|no]

If set to "yes", for each input event file it is checked whether a corresponding engeneering file exists. If this is the case, a concatenated version of all single eng files is created similar to the event list sum file. "no" as value suppresses the eng sum file creation.



rmfiles = no [boolean: yes|no]

If set to "yes", the individual input files are removed after the corresponding sum file(s) has/have been successfully created.



verbosity = 2 [integer: 0|1|2|3]

Specifies the program verbosity level, i.e. the amount of screen output that will be issued during program execution. Level 0 means "mute", only fatal error messages will be printed. Verbosity level 3 results into detailed diagnostic messages. Default is level 2.



help = no [boolean: yes|no]

A boolean flag which, when set to yes triggers that the program prints out a brief on-screen description of all available command line parameters together with the current program version number and exits successfully.

EXAMPLES

1. Concatenate the event files in the list FL.concat:

        mecatobs filelist=FL.concat 
   

1. Select and concatenate the event files using the tool with meselobs.

       /bin/ls /dirname/*M1*_rev.fits > FL.out
       meselobs filelist=FL.out | mecatobs filelist=stdin
   

   Note: in this case any output of meselobs is passed to mecatobs. This means that any possible warning or error message will be processed by mecatobs which will probably fail. In this case it is recommended to inspect the output of meselobs separately.

FURTHER DOCUMENTATION

1. The SAX LEGSPC Data Analysis System - Software User Manual,
   U. Lammers, Doc. SAX/LEDA/0010
2. Contents and structures of event and HK files in the SAX/LEGSPC data analysis system,
   U. Lammers and M. Busetta, Doc. SAX/LEDA/0002

BUGS

None known.

SEE ALSO

mksaxobs, meselobs,