NAME
pcaprepobsid - Prepare one XTE observation for PCA analysis
USAGE
pcapreobs indir outdir
DESCRIPTION
pcaprepobsid is a high-level task that prepares a single RXTE
observation ID (obsid) for scientific analysis with the PCA
instrument (Standard2 data mode).
It is only necessary to run pcaprepobsid once per observation.
Upon output, a filter file is created, Standard2 backgrounds have
been estimated, and dead-time quantities have been computed for
both Standard2 and background files. These outputs are suitable
for extracting spectra and light curves.
pcaprepobsid runs the basic tasks that prepare Standard2 data for
further analysis, using the recommended settings for most users.
The tasks that pcaprepobsid runs are:
* xtefilt - create XTE filter file
* pcaprepfile2 - prepare each Standard2 file for analysis
- pcadeadcalc2 - calculate dead time quantities
- pcabackest - estimate PCA background
As an alternative to running this task, users can run xtefilt and
pcaprepfile2 individually.
pcaprepobsid uses default parameters for the above tasks which the
PCA team recommends for scientific analysis. It is possible to
change any parameter from the default (see below), but not advised.
INPUTS
The input to this task is a single RXTE observation ID, stored in a
single directory, in the format delivered by the RXTE archive. Note
that this task operates on a single observation ID.
pcaprepobsid does not modify the input files in any way.
OUTPUTS
The output of this task is a new directory, which contains several
files. These output files can be used as inputs to extractors like
pcaextspect2 or saextrct.
The outputs are listed below.
outdir/FP_nnnnnnnnnn-nnnnnnnn.xfl - XTE filter file
outdir/xtefilt.log - log file from calling xtefilt
The filter file can be used for time filtering (see maketime task).
It is also used internally to compute PCA background estimates.
outdir/FS4a_nnnnnnnnn-nnnnnnnnn_bkg - estimated PCA background
outdir/FS4a_nnnnnnnnn-nnnnnnnnn_dt - Standard 2 file with deadtime quantities
outdir/FS4a_nnnnnnnnn-nnnnnnnnn_dtbkg - background with deadtime quantities
outdir/FS4a_nnnnnnnnn-nnnnnnnnn.log - log file from pcaprepfile2
pcaprepobsid calls the task pcaprepfile2, and produces an estimated
PCA background file (*_bkg). It also computes estimated deadtime
quantities for each file: *_dt contains deadtime quantities for
observed Standard2 counting rates, and *_dtbkg contains deadtime
quantities for the estimated background.
You should use the *_dt and *_dtbkg for further PCA analysis.
Generally, the PCA team does not recommend that you use the original
Standard2 or background file without deadtime quantities for
scientific analysis. The *.log file contains the results of calling
pcaprepfile2 on each Standard2 file. If there is an error, you may
refer to this file for further information.
outdir/FP_xtefilt.lis
outdir/FP_dtstd2.lis
outdir/FP_dtbkg2.lis
pcaprepobsid also produces "list" files which can be used as inputs
for other tasks. The list files are ASCII files containing one
filename per line. Some tasks, especially extractors, accept
.lis as input. You can use these *.lis files to bundle
together many files quickly for these tasks.
FP_xtefilt.lis contains the name of the filter file produced by this
run. FP_dtstd2.lis contains the names of Standard2 files with
deadtime quantities (*_dt files). FP_dtbkg2.lis contains the names
of background files with deadtime quantities (*_dtbkg files).
outdir/pcaprepobsid_done.txt
This is a "signal" file that indicates that pcaprepobsid
successfully completed its run. Do not use outputs of pcaprepobsid
unless the "done" file is present.
pcaprepobsid may create other files but they are not documented, and
shouldn't be relied upon. Also, because of the nature of the task,
creating multiple and varied outputs, it is essentially required to
set clobber=YES.
NEXT STEPS
If you have multiple observations which you wish to combine, then
use the task 'pcamergeobsids', which will merge multiple pcapreobsid
output directories into a single directory.
For scientific analysis, users should create a good time interval
file using the task 'maketime' (or supplying some external GTI
file).
Finally, users should run an extractor task like 'pcaextspect2' or
'saextrct' to extract a spectrum from one or more Standard2 files
with deadtime quantities.
ABSOLUTE or RELATIVE PATHS
This task has a parameter 'abspath' which determines whether
absolute or relative path names are written to *.lis files.
Relative paths are the default.
Absolute paths (abspath='YES') are suitable for cases where the user
will be combining many different observations, or running tasks from
different working directories. However, some tasks have a limit to
the size of file names (typically ~100 characters), which may
prevent this method from working.
Relative paths (abspath='NO') are suitable for cases where the user
is running the analysis from the same working directory. As long as
follow-up tasks are run from the same working directory, relative
paths should work.
SUPPLYING a DIFFERENT TARGET POSITION
By default, xtefilt uses the RA_OBJ and DEC_OBJ keywords stored in
the FITS index files of the observation. These keywords are based
on RXTE SOF planning inputs.
However, sometimes these inputs are incorrect, or may not represent
the best scientific target location, and the user will wish to enter
a different position. Users can specify a new position with the
'ra' and 'dec' keyword parameters (which are the J2000 target
position in degrees).
There are several reasons one might want to do this. If there is an
offset pointing, the RA_OBJ and DEC_OBJ may represent the offset
pointing direction instead of the true target position. Or, a
better target position may be discovered only after the RXTE data
were processed. Or, different data sets may have been processed by
RXTE with different positions, and the user desires to reprocess all
of the data sets with a single, consistent position.
PARAMETERS
indir [filename]
Name of input directory containing a single RXTE observation
ID. The input directory must be structured as it is stored in
the archive, i.e., an FMI file, subdirectories named pca/,
acs/, and so on.
outdir [filename]
Name of output directory which will contain output products.
If the directory does not exist, then it will be created. See
above for description of output products.
(abspath = 'NO') [boolean]
If YES, then absolute path names will be written to *.lis
files. If NO, then relative path names will be written,
relative to the current working directory when pcaprepobsid is
run.
(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.
(ra = INDEF) [real]
Right ascension of target in J2000 degrees. If ra=INDEF
(which is the default), then the RA_OBJ keyword from the
observation index FITS files is used.
(dec = INDEF) [real]
Declination of target in J2000 degrees. If dec=INDEF
(which is the default), then the DEC_OBJ keyword from the
observation index FITS files is used.
(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 = yes) [boolean]
Overwrite output files? By default this is YES, and the task does
not function properly if you set it to NO.
(history = yes) [boolean]
Write standard HEADAS parameter history into output file?
EXAMPLES
# In this example the user wishes to prepare obsid 93067-01-01-01
# for further analysis. This subdirectory already is present in
# the uers's current working directory.
pcaprepobsid indir=./93067-01-01-01 outdir=./93067-01-01-01-result
# When complete, the new subdirectory ./93067-01-01-01-result
# should be created with the output products listed above.
CAVEATS
The user is strongly recommended to use an updated RXTE
Calibration database (CALDB), and to set breakfile=CALDB,
modelfile=CALDB, saahfile=CALDB.
BUGS
Please report problems to xtehelp@athena.gsfc.nasa.gov.
SEE ALSO
pcaprepfile2, xtefilt, pcadeadcalc2, pcabackest