NAME
    pcamergeobsids - merge multiple 'pcaprepobsid' directories into one

USAGE
    pcamergeobsids indir outdir

DESCRIPTION

    The task pcamergeobsids is a high-level convenience task that
    combines multiple Standard2 directories into a single directory.
    This task eases the job of merging multiple observations into a
    single observation, and thus extracting spectra or light curves.

    The task essentially concatenates list files, which list filter
    files and Standard2 files, into a single list file for the
    combined set.  It also creates a single RXTE filter file covering
    all observations, which has been merged and time-sorted.

    As an alternative to using pcamergeobsids, the user can collect
    the desired files by their own methods.

INPUTS and OUTPUTS

    The input to the task is a list of input directories, either
    comma-separated or as a .lis list file.  These
    directories must have the directory and file structure produced by
    pcaprepobsid.  Thus, you should run pcaprepobsid at least once for
    each observation of interest, and then merge those outputs with
    pcamergeobids.

    Your input list may optionally point to each subdirectory's
    "pcaprepobsid_done.txt" file instead of the parent subdirectory.
    This is a convenient way to search for only those observation
    directories that have successfully been processed by pcaprepobsid.
    For example the shell command:

        ls 96443-*/pcaprepobsid_done.txt > indirs.lis

    Will automatically find any 96443-* subdirectory that has been
    successfully processed by pcaprepobsid.  pcamergeobsids will
    automatically uses the parent subdirectory for further processing.

    The output of pcamergeobsids is a new results directory, also of
    the same format as produced by pcaprepobsid, which can be used for
    further scientific processing.

    The output of pcamergeobsids is suitable to be used as input to
    itself.  Thus, it is possible to merge sub-groups of data with
    pcamergeobsids, and then use the same task to merge those
    sub-grouped results into a single master data set, ad infinitum.

COPY or LINK

    pcamergeobsids gives you a choice to LINK or COPY the raw data.
    The setting copymeth=COPY will copy all relevant inputs to the
    output directory, including Standard2 files, backgrounds, and
    files with dead-time quantities.  Use this setting if you plan on
    deleting the individual observation data, or plan on moving
    observation data around.  This option has the down side of using
    twice the disk space as the original data.

    The setting copymeth=LINK will create new list files, and a merged
    filter file, but none of the Standard2 files, backgrounds or files
    with dead-time quantities are copied into the output directory.
    Use this setting if you wish to save disk space, or are
    experimenting with merging different data sets.  This option has
    the down side of forcing you to preserve the input directories
    where the original data lives.

PARAMETERS

    indir [filename]
        Name of one or more input directories containing
        pcaprepobsid-style data.  This parameter should be either a
        comma-separated list of directories given on the command line,
        or a .lis list file (ASCII file with one subdirectory
        per line).

    outdir [filename]
        Name of output directory which will contain output products.
        If the directory does not exist, then it will be created.  See
        the help for 'pcaprepobsid' for description of output products.

    (abspath = 'NO') [boolean]
        If YES, then absolute path names will be written to *.lis
        files.  If NO, then relative path names will be written,
        relative to the current working directory when the task is
        run.  Any existing relative paths will be converted to
        absolute paths.

    (copymeth = 'LINK') [string]
        Either 'LINK' or 'COPY'.  If COPY, then all files are copied
        to the output directory.  If LINK, then new list files are created
        by other files are not copied.  See above.

    (skipbad = no) [boolean]
        If skipbad = YES, then input directories with missing or
        partial information are ignored.  If skipbad = no, a single
        missing or partial observation will cause the task to stop
        with an error message.

    (cleanup = yes) [boolean]
        Clean up scratch files?

    (chatter = 1) [int] range 0-5
        Verbosity level of output

    (clobber = yes) [boolean]
        Overwrite output files?  By default this is YES, and the task does
        not function properly if you set it to NO.

    (history = yes) [boolean]
        Write standard HEADAS parameter history into output file?

EXAMPLES

   # Merging results for 96443-01-01-16 and 96443-01-01-17, which have been
   # created by running pcaprepobsid.

   pcamergeobsids indir=96443-01-01-16-result,96443-01-01-17-result 
       outdir=merged-96443


   # Same example but using an file
   # Create the @ file  
   ls 96443-01-01-*/pcaprepobsid_done.txt > merged-96443.lis
   # Merge the data
   pcamergeobsids -96443.lis  outdir=merged-96443

CAVEATS

    The user is strongly recommended to use an updated RXTE
    Calibration database (CALDB), and to set breakfile=CALDB,
    modelfile=CALDB, saahfile=CALDB.

BUGS
    Please report problems to xtehelp@athena.gsfc.nasa.gov.

SEE ALSO
    pcamergeobsids