pcaextlc1 HEADAS help file

NAME

pcaextlc1 - Extract PCA Standard1 light curve and background, and optional deadtime correction

USAGE

         pcaextlc1 src_infile bkg_infile outfile gtiandfile pculist binsz

DESCRIPTION

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

pcaextlc1 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 'pcaextlc1' 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 pcaextlc1 will automatically de-select the detectors which are disabled, or having a breakdown, etc. This functionality relies on the "zero_bad" capabilities of the "pcadeadcalc1" 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 Standard1 files. To gain full benefit of this tool, the user *MUST* provide dead-time calculated version of the Standard1 file. For beginning users, the output files of the 'pcaprepfile1' task are sufficient. For advanced users, the equivalent output of 'pcadeadcalc1' is acceptable.

If background estimates are required, the user must supply background Standard2 files, also with dead-time quantities calculated. These are produced by pcaprepobsid or pcaprepfile2.

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

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.

IMPORTANT CAVEATS

There are some important caveats related to the results of this tool.

**THE DEAD-TIME RESULTS ARE ESTIMATES, NOT 100% ACCURATE**.

Please see the help documentation for pcadeadcalc1 for some of these important discussions.

Also, pcaextlc1 takes the standard PCA background, which is sampled at 16 second timescales, and interpolates it to the requested bin size for the light curve. Interpolation itself introduces some error.

Also, if the requested light curve time bin size is larger than 16 seconds, the interpolation of the background will not be as accurate as rebinning the background would be. For 16 second or larger time bins, you should typically use the Standard2 data instead.

PARAMETERS

src_infile [string - file name or @filename]: Name of an input "source" PCA Standard1 file or @filename.txt file name list. These files should have been processed by 'pcadeadcalc1', 'pcaprepfile1' 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").
binsz = 1.0 [real]: Time bin size for light curve samples, in seconds. This value must be an integer multiple of 0.125 because that is the time sample size of Standard1 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 dead-time corrected light curve. Use "ON" for the on-time column, which results in a standard non-dead-time corrected light curve (the raw on-time per bin 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]: Setting passed to 'saextrct'. Not recommended to change unless needed.
(chmax = INDEF) [string]: Setting passed to 'saextrct'. Not recommended to change unless needed.
(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:: pcaextlc1 [ interactive prompts follow ] Input Standard1 file name or @file-of-filenames: @93067-01-42-01-result/FP_dtstd1.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 Light curve time bin size (multiple of 16 sec): 16
2. Calling from command line:: pcaextlc1 src_infile=@93067-01-42-01-result/FP_dtstd1.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 chatter=5 deadcorrtype=LIVE lcmode=RATE

CAVEATS

Although it is possible to run this task against the "original" raw Standard1 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 pcaprepfile1/pcaprepobsid/pcadeadcalc1. If zerobad=NO, then it is possible for the calculated exposures to be incorrect.

BUGS

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