.help fcollect Aug96 ftools.xte
.ih
NAME
fcollect -- First half of XTEFILT, which creates a filter file for an
observation based on housekeeping, attitude and orbit data.
.ih
USAGE
fcollect obsid fdpath appidfile outfile deltat maxgap clobber
.ih
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).
.ih
PARAMETERS
.ls obsid [string - observation name]
The alphanumeric code, ObsId, which identifies the observation to be processed.
.le
.ls fdpath [string - directory name]
The fully qualified pathname for the top level of the XFD. This directory
must contain a FMI (master index) file.
.le
.ls 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.
.le
.ls 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.
.le
.ls (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.
.le
.ls (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.
.le
.ls (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).
.le
.ls (clobber = no) [boolean]
Tells if existing files having the same name are to be overwritten. 
.le
.ls (fname = tmp) [string - last filename written]
This parameter is written at runtime by FCOLLECT itself and 
should *not* be set by the user!
.le
.ls (mode = ql) [string]
FTOOLS internal -- users should not need to change.
.le
.ih
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:
.nf

fcollect 94018-01-01-00 /data/osiris02/xtegof/FITS/FD appidlist 1.0

.fi
where each line of "appidlist" contains entries in this format:
.nf

AppID# ColumnName

.fi
The list of appids currently used in the XTE-GOF is given in the 
help file for XTEFILT ("xtefilt -h" or "fhelp xtefilt").
.ih    
NOTES:
.le
Appidlist entries of the form:
.nf

AppId# InputColName OutputColName

.fi
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.
.ih
BUGS
.le
.ls Please report problems to xtehelp@athena.gsfc.nasa.gov.
.le
.ih
SEE ALSO
MAKETIME XTEDERIVE XTEFILT FMERGE
.endhelp

