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