pcaextlc2 HEADAS help file

NAME

pcaextlc2 - Extract PCA Standard2 light curve and background, and optional deadtime correction

USAGE

         pcaextlc2 src_infile bkg_infile outfile gtiandfile pculist 
            layerlist binsz

DESCRIPTION

pcaextlc2 extracts a light curve from PCA data stored in the Standard2 format. This task performs light curve extraction for both source and background, and optionally performs both background subtraction and/or dead-time correction.

pcaextlc2 is a "convenience" script which makes it easier and less error-prone to extract a light curve for most users.

A key benefit is that users do not need special knowledge of when detectors become "dead" for various reasons. Instead, the user can request *all* of the detectors they are interested in, and 'pcaextlc2' will produce a light curve which contains the subset of those detectors which have good live time, and is represents the average rate per detector.

For example, users can request all of the detectors all of the time (pculist="0,1,2,3,4"), and pcaextlc2 will automatically de-select the detectors which are disabled, or having a breakdown, etc. This functionality relies on the "zero_bad" capabilities of the "pcadeadcalc2" task.

Advanced users can still use the more basic tools for fine-grained control instead of this task. Because extraction and dead-time correction require the user to perform several careful operations, the use of this tool is recommended to make sure that the operations are done consistently. Generally, the PCA team and the RXTE GOF recomend to not change the default for the advance parameters of this tool without specific need.

The input to this tool is a set of PCA Standard2 files. To gain full benefit of this tool, the user *MUST* provide dead-time calculated version of the Standard2 file. For beginning users, the output files of the 'pcaprepfile2' task are sufficient. For advanced users, the equivalent output of 'pcadeadcalc2' is acceptable.

If background estimates are required, the user must supply background Standard2 files, also with dead-time quantities calculated.

The output of the task is a light curve file (.lc) file which contains the source count rate. Using the default settings to this task, the output light curve file has rates that are dead-time corrected, and contain only counts and exposure from live detectors, as described in the help file for the task 'pcadeadcalc2'.

By default, pcaextlc2 uses the full energy range of the input Standard2 data. If you want to be more selective, then use the chmin and chmax parameters.

If lcmode=RATE, the output is a RATE column (counts per live detector per unit live time), and the ERROR column represents the Poisson rate error. If lcmode=COUNTS, the output is a COUNTS column (total counts during each time bin), ERROR is the Poisson counting error. For lcmode=COUNTS, the FRACEXP value can be greater than 1.0, indicating more than one PCU is enabled. In this case, the rate per live PCU can be computed as COUNTS/TIMEDEL/FRACEXP.

For dead-time purposes, if deadcorrtype=LIVE then the live-time-corrected values of the light curve samples is computed, and the live time is reported in the column LiveTime. Dead-time corrected samples are indicated by the presence of the DEADAPP='T' keyword. If deadcorrtype=ON, then the light curve samples are corrected for number of PCUs enabled (i.e. "on-time"), but not for dead-time. The on-time is then reported in the OnTime column. If only correcting for on-time, then DEADAPP='F'alse.

For background subtraction purposes, a set of background estimates must be supplied in the bkg_infile parameter. If bkgsub=NO, then background values are produced and reported in the BACKV and BACKE columns, but they are not subtracted. If bkgsub=YES, then the background is subtracted, i.e. RATE is recomputed as (RATE-BACKV), and ERROR is recomputed as SQRT(ERROR*ERROR+BACKE*BACKE). The presence of background subtraction is indicated by the BACKAPP='T' keyword.

PARAMETERS

src_infile [string - file name or @filename]: Name of an input "source" PCA Standard2 file or @filename.txt file name list. These files should have been processed by 'pcadeadcalc2', 'pcaprepfile2' or 'pcaprepobsid'.
bkg_infile [string - file name or @filename]: Name of an input "background" PCA Standard2 file or @filename.txt file name list. Note that this file list should match one-for-one with the input files specified by the 'src_infile' parameter. These files should have been processed by 'pcadeadcalc2', 'pcaprepfile2' or 'pcaprepobsid'. A value of "NONE" indicates no background estimates are desired.
outfile [string - file name]: Name of output light curve file.
gtiandfile = "-" [string]: Name of GTI "AND" time filtering, which is identical to the gtiandfile passed to 'saextrct' to produce the light curve. See 'saextrct' for more information.
pculist = "ALL" [string]: A comma-separated list of PCU detector numbers, or "ALL". The list of detectors should be in the range 0-4. The value of "ALL" means use all detectors, i.e. ("0,1,2,3,4").
layerlist = "ALL" [string]: A comma-separated list of PCU anode layer numbers, or "ALL". The list of layers should be in the range 1-3. The value of "ALL" means use all layers, i.e. ("1,2,3"). It is also possible to specify an explicit list of anode symbols, for example "X1L,X2L,X3L" for all left anodes or "X1R,X2R,X3R" for all right anodes.
binsz = 16.0 [real]: Time bin size for light curve samples, in seconds. This value must be an integer multiple of 16 because that is the time sample size of Standard2 data.
(lcmode = "RATE") [string]: String giving the binning mode for accumulating counts, either "RATE" or "SUM". A setting of lcmode="RATE" produces a rate light curve (counts per on-time or per live-time). A setting of lcmode="SUM" produces a counts light curve (total counts per bin).
(deadcorrtype = "LIVE") [string]: Name of live-time correction type to use. Use "LIVE" for the true live-time correction, which results in a true dead-time corrected light curve. Use "ON" for the on-time column, which results in a standard non-dead-time corrected light curve (the basic detector on-time exposure is calculated).
(bkgsub = YES) [boolean]: Setting that determines whether background is subtracted or not. If bkgsub=YES, then background is subtracted. If bkgsub=NO, then background is listed in the output file (columns BACKV and BACKE) but not subtracted. This setting is ignored if bkg_infile="NONE".
(gtiorfile = "APPLY") [string]: Name of GTI "OR" time filtering, which is identical to the gtiorfile passed to 'saextrct' to produce the light curve.
(gticols = "START STOP") [string]: Name of GTI start/stop column names, which is identical to the gticols passed to 'saextrct' to produce the light curve.
(timecol = "TIME") [string]: Name of TIME column used for extraction, which is identical to the timecol passed to 'saextrct' to produce the light curve.
(timemin = INDEF) [double precision real]: Minimum start time (MET) used for accumulation, which is identical to the timemin passed to 'saextrct' to produce the light curve.
(timemax = INDEF) [double precision real]: Maximum start time (MET) used for accumulation, which is identical to the timemax passed to 'saextrct' to produce the light curve.
(timeint = INDEF) [double precision real]: Comma-separated list of time intervals (MET), which is identical to the timeint passed to 'saextrct' to produce the light curve.
(lcbinarray = INDEF) [string]: Setting passed to 'saextrct'. Not recommended to change unless needed.
(gtiarray = INDEF) [string]: Setting passed to 'saextrct'. Not recommended to change unless needed.
(maxmiss = INDEF) [string]: Setting passed to 'saextrct'. Not recommended to change unless needed.
(phasefile = INDEF) [string]: Setting passed to 'saextrct'.
(timezero = INDEF) [string]: Setting passed to 'saextrct'. Not recommended to change unless needed.
(chmin = INDEF) [string]: The minimum PCA channel to use for analysis. The extracted light curve will cover channels 'chmin' to 'chmax'. The default value, INDEF, indicates to use the full energy range of the Standard2 data. This number is in the original 0-249 energy channel system of the PCA, and not the 0-128 bin range of Standard2. For more documentation see the help of <a href="saextrct.html">saextrct</a>.
(chmax = INDEF) [string]: The maximum PCA channel to use for analysis. The extracted light curve will cover channels 'chmin' to 'chmax'. The default value, INDEF, indicates to use the full energy range of the Standard2 data. For more documentation see the help of <a href="saextrct.html">saextrct</a>. This number is in the original 0-249 energy channel system of the PCA, and not the 0-128 bin range of Standard2. For more documentation see the help of <a href="saextrct.html">saextrct</a>.
(chint = INDEF) [string]: Setting passed to 'saextrct'. Not recommended to change unless needed.
(chbin = INDEF) [string]: Setting passed to 'saextrct'. Not recommended to change unless needed.
(ephem = INDEF) [string]: Setting passed to 'saextrct'. Not recommended to change unless needed.
(period = INDEF) [string]: Setting passed to 'saextrct'. Not recommended to change unless needed.
(phaseint = INDEF) [string]: Setting passed to 'saextrct'. Not recommended to change unless needed.
(obsdate = "MJDREF") [string]: Setting passed to 'saextrct'. Not recommended to change unless needed.
(obstime = "TSTART TSTOP") [string]: Setting passed to 'saextrct'. Not recommended to change unless needed.
(sensecase = NO) [string]: Setting passed to 'saextrct'. Not recommended to change unless needed.
(negative = IGNORE) [string]: Setting passed to 'saextrct'. Not recommended to change unless needed.
(mfracexp = INDEF) [string]: Setting passed to 'saextrct'. Not recommended to change unless needed.
(tnull = 0.0) [string]: Setting passed to 'saextrct'. Not recommended to change unless needed.
(cleanup = yes) [boolean]: Clean up scratch files?
(chatter = 2) [int] range 0-5: Verbosity level of output
(clobber = no) [boolean]: Overwrite output file?
(history = yes) [boolean]: Write standard HEADAS parameter history into output file?

EXAMPLES

1. Calling interactively:

                    pcaextlc2 
                     [ interactive prompts follow ]
                     Input Standard2 file name or @file-of-filenames: @93067-01-42-01-result/FP_dtstd2.lis
                     Input background file name or @file-of-filenames: @93067-01-42-01-result/FP_dtbkg2.lis
                     Output light curve file: corrected_93067.lc
                     Input GTI file to be AND'd with INFILE:[-] 
                     Comma-separated list of PCU detectors to accmulate (0-4): ALL
                     Comma-separated list of PCU layers to accmulate (1-3): ALL
                     Light curve time bin size (multiple of 16 sec): 16

2. Calling from command line:

                   pcaextlc2 src_infile=@93067-01-42-01-result/FP_dtstd2.lis \
                             bkg_infile=@93067-01-42-01-result/FP_dtbkg2.lis \
                             outfile=corrected_93067.lc \
                             binsz=32.0 \
                             gtiandfile=my_data_selection.gti \
                             pculist=ALL layerlist=ALL chatter=5 deadcorrtype=LIVE lcmode=RATE

CAVEATS

Although it is possible to run this task against the "original" raw Standard2 files, the PCA team cannot attest to its correctness. Also, the running of this task assumes that "zero_bad=YES" has been used when running pcaprepfile2/pcaprepobsid/pcadeadcalc2. If zerobad=NO, then it is possible for the calculated exposures to be incorrect.

BUGS

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