.help pcabackest Nov98 ftools.xte
.ih
NAME
pcabackest -- Creates an estimated PCA background spectrum for a specific
observation from the background model created by the PCA instrument team.
.ih
USAGE
pcabackest infile outfile modelfile(s) filterfile modeltype 
interval propane layers
gaincorr gcorrfile fullspec interp syserr maxmodels
.ih
DESCRIPTION
The background spectrum in the XTE Proportional Counter Array is
modelled based upon measured rates which are recorded in the Standard
Mode 2 data file.  The PCA instrument team provides file(s) for one
or more background models, which are interpreted by pcabackest (see
"modelfile" parameter, below). pcabackest reads a Standard Mode 2 FITS
file and produces a background spectrum for each PCU for each record
in the Standard Mode 2 file.  The output of pcabackest can be further
processed by saextrct to generate background spectra or light curves
appropriate to a given observation.
.ih
PARAMETERS
.ls infile [filename]
The name of the Standard Mode 2 file for which the corresponding
background model will be created.  This file is also the source of some
of the values of the parameters upon which the model is based.
.le
.ls outfile [filename]
Name for output file containing the background estimate
created by pcabackest.
.le
.ls modelfile [filename or @list-of-files-filename]
The name of the file(s) containing the model created by the PCA
instrument team.  This may be a list of model files containing
different model components or "caldb" to select the appropriate
model files from the calibration database.  At this time, model
files are being improved with great rapidity, so the PCA TEAM DOES
*NOT* RECOMMEND USE OF THE "CALDB" OPTION.  Instead, users should
select appropriate model files from the RXTE GOF anonymous-FTP area
(ftp://legacy.gsfc.nasa.gov/xte/calib_data/pca_bkgd)
The PCA team produces models as separate files for each model
component.  Users should download the model components appropriate for
their work and input them at the modelfile prompt, either giving the
full path name of the model file(s) or the name of an ascii file listing
the full path name of each model to be used, one model file per line.
.le
.ls filterfile [filename]
The name of the filterfile created by xtefilt which contains additional
parameters required by the models to estimate the background.  If all the
parameters required are available in the Standard mode 2 file then the
value "none" can be used instead of a file name. However, as of FTOOLS
v4.2, a filter file is required for all recommended models.
.le
.ls (modeltype=both) [INTERNAL, EXTERNAL, BOTH]
For older models *ONLY* (eg., "Q6"), this parameter can be used to
specify construction of internal background only, external, or both.
For the new models (eg., "faint" or "sky" models), this parameter
MUST BE SET TO "BOTH" - these models combine external and internal
background features in a single file.  Specification of "internal" or
"external" with these models will cause pcabackest to reject them.
.le
.ls interval=16 [integer]
The interval between successive background estimates in the output file.
The Standard mode 2 file contains data for every 16 seconds, but longer
intervals may be specified for output, and will be created by integration.
Shorter values may not be specified at this time.
.le
.ls (propane=no) [boolean]
Setting propane=yes will cause pcabackest to generate background estimates for
the propane layer of each PCU.  (Note: there are no model files to support 
this feature.)
.le
.ls layers=no [boolean]
Normally, pcabackest computes the overall background spectrum for each PCU.
Setting layers=yes will cause pcabackest to produce a separate background
estimate for each anode of each layer of each PCU.
.le
.ls gaincorr=no [boolean]
Setting gaincorr=yes will cause pcabackest to perform the gain and offset 
correction to the background which the EDS applies to data in modes where the
data from multiple PCUs are combined.  Setting this flag forces the output
spectrum to contain 256 channels
.le
.ls gcorrfile [filename]
The name of the file containing the EDS gain and offset corrections.  The
default value of "caldb" causes pcabackest to search the calibration
database for the correct file to apply.  Note: If you explicitly specify a
gain correction file you should specify the extension of this file you wish
to use.  By default, pcabackest will use the first extension and does no
checking of the validity of the extension it uses for the data being
analyzed.
.le
.ls fullspec=no [boolean]
By default, pcabackest produces a 129 channel background spectrum which
correspond to the 129 channels of Standard Mode 2.  Setting fullspec=yes
will cause pcabackest to produce a 256 channel background spectrum.
This flag is automatically set when gaincorr is set.
.le
.ls saahfile=none [filename]
The name of the file containing information about the particle dose from
each passage through the South Atlantic Anomaly (SAA).  This file is
needed for models based upon an exponential decay of activation caused
by passage through the SAA.  The special value "caldb" will search the
calibration database  for  the  appropriate file (note: SAA history
files will not be in the CALDB for this release).  This file will
be periodically updated by the PCA team as the XTE mission continues.
Check the URL listed under the "modelfile" parameter for the location
of the latest SAA history file.
.le
.ls (interp=yes) [boolean]
Some models contain a small number of bins in the modelled parameter(s) but
contain additional information so that intermediate values can be obtained by
interpolation.  Setting this parameter to "no" inhibits this interpolation
but setting it to "yes" does not cause models without the additional 
information to be interpolated.
.le
.ls (syserr=no) [boolean]
Forces the detailed computation of the estimated systematic error
in the background.  Setting this parameter to "no" causes pcabackest
to execute much faster.  It is likely that the systematic error for a
particular PCA background spectrum can be determined without performing
the detailed calculation.  Setting this parameter to "yes" causes
pcabackest to create additional spectral columns in its output which
contain information related to the systematic error estimate.
Work is still underway to determine the best methods for analysis
of these errors; users are encouraged to consult the PCA team page
(http://lheawww.gsfc.nasa.gov/docs/xray/xte/pca/) before using using
this parameter.
.le
.ls (maxmodels=256) [integer]
The limit on the number of background models that can be processed at one time.
If a background estimate involves many different model components then this
may have to be larger but that is unlikely.  Note: The number of "models" is
not the number of model files.  Each model file usually contains 30 models.
You should only change this value if pcabackest tells you that it must be
larger.
.le
.ls (timeslop=32) [integer]
The number of seconds by which the filter file is allowed to be shorter than 
the input file.  Data beyond the ends of the filter file will not be very 
intelligently extrapolated but the program will run.
.le
.ls (clobber=yes) [boolean]
If set to "yes" then pcabackest will overwrite any existing file with the
same name as the background estimate file being created.
.le
.ih
BUGS
Systematic error estimates are still mostly meaningless and in any case 
they are output in a format such that there is only one person on this 
Earth who knows what they mean.
.ih
SEE ALSO
saextrct, seextrct
.endhelp
