FCOLLECT (Aug96)               ftools.xte               FCOLLECT (Aug96)



NAME
    fcollect  --  First half of XTEFILT, which creates a filter file for
    an observation based on housekeeping, attitude and orbit data.
    
    
USAGE
    fcollect obsid fdpath appidfile outfile deltat maxgap clobber
    
    
DESCRIPTION
    This task represents the first half of XTEFILT, which is designed to
    be   used   (with   MAKETIME)   to  select  data  on  the  basis  of 
    spacecraft-related or orbit-related  items.  Specifically,  FCOLLECT
    is  used to search for and collect the specified AppIds from various
    files and to interpolate them onto a  common  timescale.   The  user
    provides   the   ObsId   code  identifying  the  observation  to  be 
    processed, the pathname to the  XTE  FITS  Database  (XFD)  and  the
    pathname  to an ascii file which tabulates the AppIds to be used for
    the  filtering.  An  optional  parameter,  deltat,  sets  the   time 
    granularity  for  the output FITS file (which will be overwritten if
    the  clobber  parameter  is  enabled).  Another  (maxgap)  sets  the 
    maximum  gap between successive data points over which FCOLLECT will
    interpolate. If there are larger gaps, the corresponding  times  are
    written   as   INDEF.    The  output  file  (FP_startMET_stopMET  if 
    outfile=XFD) is written into the current directory.
    
    fcollect can also read a PCA breakdown history file.  This file is
    stored outside of the observation directory, usually found in the
    Calibration Database (CALDB).
    
    
PARAMETERS
    
    obsid [string - observation name]
        The alphanumeric code, ObsId, which identifies  the  observation
        to be processed.
    
    fdpath [string - directory name]
        The  fully qualified pathname for the top level of the XFD. This
        directory must contain a FMI (master index) file.
    
    appidfile [string - file name]
        Filename for an ascii file which  contains  the  information  on
        which  AppIds  should  be processed. File format is one line per
        quantity to be collected, with each  line  having  two  columns:
        AppId#   ColumnName.   An optional third column will be taken as
        the name to use for the column in the output filter file.
    
    deltat = 16.0 [double - time resolution]
        The timestep to be used in  the  output  FITS  file.  All  AppId
        information  will  be  interpolated  onto  a  common  time frame
        having this deltaT.  Default is 16 seconds.
    
    (outfile = XFD) [string - output file name]
        Name for the output FITS file. If left as  the  default  ("XFD")
        then     the     conventional     Standard     Products     name    
        (FP_startMET_stopMET) is used.
    
    (breakfile = NONE) [string - name of PCA breakdown history file ]
        Name of PCA breakdown history file, or "NONE" for no history.  The value
        of "CALDB" is allowed, indicating to use the RXTE Calibration Database.
    
    (maxgap = 128.0) [double - maximum gapsize]
        The maximum gap in the original  AppId  data  across  which  the
        program  should  interpolate.  Large gaps can lead to unexpected
        and unwanted results. Default  is  128  seconds  (to  allow  for
        ACSALTITUDE   and   other   relatively   infrequently   read-out  
        housekeeping AppIDs).
    
    (clobber = no) [boolean]
        Tells  if  existing  files  having  the  same  name  are  to  be 
        overwritten.
    
    (fname = tmp) [string - last filename written]
        This  parameter  is  written  at  runtime by FCOLLECT itself and
        should *not* be set by the user!
    
    (mode = ql) [string]
        FTOOLS internal -- users should not need to change.
    
    
EXAMPLES
    1.  Collect the  AppId  information  tabulated  in  the  ascii  file
    "appidlist"  for  observation 94018-01-01-00 using a timestep of 1.0
    sec:
    
    fcollect 94018-01-01-00 /data/osiris02/xtegof/FITS/FD appidlist 1.0
    
    where each line of "appidlist" contains entries in this format:
    
    AppID# ColumnName
    
    The list of appids currently used in the XTE-GOF  is  given  in  the
    help file for XTEFILT ("xtefilt -h" or "fhelp xtefilt").
    
    
NOTES:
    Appidlist entries of the form:
    
    AppId# InputColName OutputColName
    
    may  be  used  to  specify the output column name in cases where the
    names in the  original  housekeeping  file  would  be  identical  or
    ambiguous.   This SHOULD NOT, however, be used on any of the columns
    which XTEDERIVE will need to recognize.
    
    While FCOLLECT may be run by the user as described here, the use  of
    XTEFILT to run FCOLLECT and XTEDERIVE is strongly recommended.
    
    Any  column  which  is  stored  as a scaled "I" type in the original
    housekeeping files will (as of version 3.1 of FCOLLECT)  be  written
    as  "E"  type  in  the output filter file. This allows FMERGE (which
    can run  into  trouble  when  dealing  with  scaled  data)  to  work
    correctly when applied to XTE filter files.
    
    
BUGS
    
    Please report problems to xtehelp@athena.gsfc.nasa.gov.
    
    
SEE ALSO
    MAKETIME XTEDERIVE XTEFILT FMERGE