PCABACKEST (Nov98) ftools.xte PCABACKEST (Nov98)
NAME
pcabackest -- Creates an estimated PCA background spectrum for a
specific observation from the background model created by the PCA
instrument team.
USAGE
pcabackest infile outfile modelfile(s) filterfile modeltype
interval propane layers gaincorr gcorrfile fullspec interp syserr
maxmodels
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.
PARAMETERS
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.
outfile [filename]
Name for output file containing the background estimate created
by pcabackest.
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.
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.
(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.
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.
(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.)
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.
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
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.
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.
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.
(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.
(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.
(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.
(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.
(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.
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.
SEE ALSO
saextrct, seextrct