pcaprepobsid - Prepare one XTE observation for PCA analysis
pcapreobs indir outdir
pcaprepobsid is a high-level task that prepares a single RXTE observation ID (obsid) for scientific analysis with the PCA instrument (Standard1 and Standard2 data modes).
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 Standard1, Standard2 and background files. These outputs are suitable for extracting spectra and light curves.
pcaprepobsid runs the basic tasks that prepare Standard1 and Standard2 data for further analysis, using the recommended settings for most users. The tasks that pcaprepobsid runs are:
* xtefilt - create XTE filter file
* pcaprepfile1 - prepare each Standard1 file for analysis
- pcadeadcalc1 - calculate dead time quantities
* 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 pcaprepfile1, 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.
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. Thus, it is suitable to use pcaprepobsid upon archived or read-only data. All outputs and modifications occur in the requested output directory, which must be writable.
If you are planning to analyze offset pointings, or different pointing directions that cover the same target, then you will want to use special care. Here, we mean the target position, meaning the celestial coordinates of the astrophysical object, which may be different than the direction the RXTE observatory was pointing.
By default, pcaprepobsid assumes the OBJECT, RA_OBJ and DEC_OBJ keywords correctly reflect the target location. If you are using observations with offset pointings, then these keyword values may be incorrect. In some rare cases, you may wish to combine observations with different pointings that contain the same target in the field of view. Again, the required keywords may have an incorrect (or undesireable) value in that case. Failing to register the correct target position will lead to processing errors and likely incorrect scientific results (incorrect data screening and response matrix).
In these cases, you shoud use the 'srcra' and 'srcdec' parameters to explicitly tell the task what the desired target position is. The target position is used in creating the filter file, and also to estimate an accurate response matrix.
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
outdir/FS46_nnnnnnnnn-nnnnnnnnn_dt - Standard 1 file with deadtime quantities
outdir/FS46_nnnnnnnnn-nnnnnnnnn.log - log file from pcaprepfile1
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. It similarly calls pcaprepfile1 to estimate dead-time quantities for Standard1 files.
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
outdir/FP_dtstd1.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 @filename.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; similar for the FP_dtstd1.lis file). 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.
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.
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.
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.
# 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.
The user is strongly recommended to use an updated RXTE Calibration database (CALDB), and to set breakfile=CALDB, modelfile=CALDB, saahfile=CALDB.
There may be additional caveats in the individual task documentation for pcaprepfile1 and pcaprepfile2, which discusses specific issues in more detail. Please read those task help files.
Please report problems to xtehelp@athena.gsfc.nasa.gov.
pcaprepfile2, xtefilt, pcadeadcalc2, pcabackest, pcaprepfile1