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 (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.


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. 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.


SPECIAL NOTES

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.


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
       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.


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.

(datamodes = "Standard1,Standard2") [string]
Specify which DATAMODEs to operate upon, as a comma-separated list. By default, this should be both Standard1 and Standard2, and the PCA team does not recommend to change the defaults.

(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.

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.


BUGS

Please report problems to xtehelp@athena.gsfc.nasa.gov.


SEE ALSO

pcaprepfile2, xtefilt, pcadeadcalc2, pcabackest, pcaprepfile1

CATEGORY

Jan95 ftools.xte