NAME
    pcaprepfile2 - Estimate background and dead-time values for Standard2 file

USAGE
    pcaprepfile2 infile filterfile hkfiles bkgfile dtfile dtbkgfile ...

DESCRIPTION

    pcaprepfile2 does standard preparation activities for one 
    PCA Standard2 data file.  It represents the best practices
    recommended by the RXTE PCA team for preparing Standard2
    for scientific analysis.

    The prerequisites for this tool are:
      * one Standard2 file ('infile')
      * an RXTE filterfile for the observation ('filterfile')
      * list of RXTE housekeeping files ('hkfiles')

    When complete, pcaprepfile2 will produce:
      * raw estimated Standard2 background file ('bkgfile')
      * Standard2 file with dead-time quantities ('dtfile')
      * estimated background with dead-time quantities ('dtbkgfile')

    There are several settings that the user can alter, but the user
    is recommended to use the defaults except with good reason.  The
    defaults will compute dead-time related quantities for each PCU
    and filter out known times of bad data (see pcadeadcalc2).  It
    will also estimate the PCA background for the same interval.

    After running this tool, the 'dtfile' and 'dtbkgfile' files are
    suitable for use with pcaextspect2 (recommended) or saextrct.

    Calculating dead-time quantities is optional.  If dtfile='NONE'
    and dtbkgfile='NONE', then they are not computed.  However, the
    PCA team recommends to produce the dead-time calculations, and to
    use the dead-time quantity files for all subsequent analysis.
    (i.e. ignore the original Standard2 file and background, and use
    the dtfile and dtbkgfile instead).

PARAMETERS

    infile [filename]
        Name of single input Standard2 file.

    filterfile [filename]
        Name of single input RXTE filter file, which has been created
        by xtefilt.

    hkfiles [string]
        Specify a list of PCA housekeeping files, i.e. the FH5* files
        in the pca subdirectory.  This can either be a comma-separated
        list, or a @filename.txt where filename.txt contains a list
        of files.  There must be exactly five files specified because
        there are five PCUs.

    bkgfile [filename]
        Upon successful completion, the name of the output file
        containing estimated background.

    dtfile [string]
        Upon sucessful completion, the name of the output file
        containing Standard2 data with dead-time quantities.  The
        PCA team recommends to use this file for subsequent analysis.
        A value of 'NONE' indicates to not create this file.

    dtbkgfile [string] 
        Upon sucessful completion, the name of the output file
        containing background estimates with dead-time quantities.
        The PCA team recommends to use this file for subsequent
        analysis of background.  A value of 'NONE' indicates to not
        create this file.

    (modelfile = 'CALDB') [string]
        Comma-separated list of RXTE PCA background model files, or an
        @files.lis listing of files.  See the help file for pcabackest
        for more information.  A setting of 'CALDB' instructs the task
        to query the Calibration Database (CALDB) for the correct model.

    (bkginterval = 16.0) [real]
        The interval between successive background estimates.  See the
        help file for pcabackest ('interval' parameter) for more
        information.

    (bkglayers = 'YES') [boolean]
        If set, then compute background estimates for each PCU layer.
        See the help file for pcabackest ('layers' parameter) for
        more information.

    (bkgfullspec = 'NO') [bookean]
        If set, then compute a full 256-channel background estimate
        instead of Standard2's 129 bins.  See the help file for
        pcabackest ('fullspec' parameter) for more information.

    (saahfile = 'CALDB') [string]
        Name of SAA History file used for background estimates.  See
        the help file for pcabackest for more information.

    (breakfile = 'CALDB') [string]
        Set to a file name which contains PCU breakdown GTI
        information.  If set to 'CALDB', then the task will query
        CALDB for the appropriate file.  If set to 'NONE', then no PCU
        breakdown processing will be done (not recommended).

    (zero_bad = YES) [boolean]
        If set, then the task will set the Xenon counts to zero any
        PCU which is considered to be in a "bad" science state at the
        given time, as described above.  If not set, then Xenon counts
        are not changed.

    (transition_bad = YES) [boolean]
        If set, then PCU high voltage transitions are considered "bad"
        science times (+/- 16 sec).  If not set, then only PCU high
        voltage "off" is considered bad.

    (propane_bad = YES) [boolean]
        If set, then PCUs are considered "bad" if their propane layers
        are gone.  If not set, then the propane layer status is not
        considered.

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

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

    (clobber = no) [boolean]
        Overwrite output file?

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

EXAMPLES

    # Create list of PCA housekeeping files    
    ls FH5* > hkfiles_file3.lis

    # Run on FS4a_file.gz
    pcaprepfile2 infile=FS4a_file3.gz filterfile=filt_file3.xfl.gz 
      hkfiles=@hkfiles_file3.lis 
      bkgfile=FS4a_file3_bkg dtfile=FS4a_file3_DT dtbkgfile=FS4a_file3_DTbkg 

    # Outputs are FS4a_file3{_bkg,_DT,_DTbkg}

CAVEATS

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

    The user is strongly recommended to compute the files with
    dead-time quantities and use those for downstream processing.

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

SEE ALSO
    pcadeadcalc2, pcabackest