NAME

pcaextspect2 - Extract PCA Standard2 spectrum and background, and optional deadtime correction


USAGE

         pcaextspect2 src_infile bkg_infile src_phafile bkg_phafile 
            gtiandfile pculist layerlist respfile

DESCRIPTION

pcaextspect2 extracts a spectrum from PCA data stored in the Standard2 format. This task performs spectrum extraction for both source and background, dead-time correction, and optionally calculates a PCA response matrix which corresponds to the observation.

pcaextspect2 is a "convenience" script which makes it easier and less error-prone to extract a spectrum 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 'pcaextspect2' will produce a spectrum which contains the subset of those detectors which have good live time. For example, users can request all of the detectors all of the time (pculist="0,1,2,3,4"), and pcaextspect2 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' or 'pcaprepobsid' tasks are sufficient. For advanced users, the equivalent output of 'pcadeadcalc2' is acceptable.

The user must provide *both* the source *and* background Standard2 files. Beginning users can use the output of 'pcaprepfile2' / 'pcaprepobsid'; advanced users may use the output of 'pcabackest' if desired.

The output of the task is a source spectrum file (.pha file) and a background spectrum file for the same time interval. These files are dead-time corrected, and contain only counts and exposure from live detectors, as described in the help file for the task 'pcadeadcalc2'.

The output will be the total counts spectrum of all live detectors, with an exposure that is the sum of the exposures for the individual PCU detectors. Thus, the rate spectrum appearing in software like XSPEC will have units of "counts per detector" ("counts per PCU").

By default, PCA team-recommended systematic error will be assigned to the spectrum. This can be disabled by setting syserrfile=NONE.

The task can also optionally calculate a response matrix. This matrix is tailored for the specific observation and weighted appropriately. In this case, users must specify the filter file using the 'filtfile' parameter.


CALCULATING A RESPONSE MATRIX

If users wish to calculate their own response matrix at a later time, they can use 'pcarsp' task. Because of the complexity of selecting the proper detectors and layers, the RXTE GOF and PCA teams recommend to allow this task to compute the response matrix, but it can be done "by hand."

The important parameters for calling pcarsp are,

         -l (choose same layer list as used to extract spectrum)
         -p (choose same detector list as used to extract spectrum)
         -w INFILE (applies appropriate PCU weights for observation)

The output spectrum produced by this task contains PCU weighting keywords than can be used automatically by selecting the "-w" parameter.

By default the response is computed at the exposure-weighted centroid time of the observation but the 'respdate' parameter can be used to select another time.

NOTE: the PCA response changes over time. This task computes only one response matrix at a given date. Merging data spanning more than ~6 months and using a single response may lead to response-related spectral errors.


COMBINING SPECTRA

If the user wishes to combine spectra produced by pcaextspect2 in some form of downstream processing, then these instructions may be of help.

Users should combine the spectra with the following general settings:

        * sum the counts
        * sum the exposure
        * sum the responses weighted by relative exposure

For the task 'mathpha' the settings should be

        * expr="spectrum1.pha + spectrum2.pha + spectrum3.pha + ..."
        * units='C' (output in counts)
        * exposure='CALC'

Of course, this operation needs to be performed separately for both the source and background files.

To combine the responses, the user should use the 'addrmf' task and an input file with weights. The weights should be calculated according to the relative exposure. For example, if spectrum1.pha has 1000 seconds of exposure and spectrum2.pha has 500 seconds of exposure then the weighting file should look like this:

        spectrum1.rsp   0.6667
        spectrum2.rsp   0.3333

Note how 0.6667 equals (1000/1500) and 0.3333 equals (500/1500), where 1500 seconds is the total exposure of both. By definition, the weights in the file must sum to 1.0.


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

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

src_phafile [string - file name]
Name of output "source" spectrum, which will be corrected for dead-time. The BACKFILE and RESPFILE keywords will be updated to point to the correct background and response files, if appropriate.

bkg_phafile [string - file name]
Name of output "background" spectrum, which will be corrected for dead-time.

gtiandfile = "-" [string]
Name of GTI "AND" time filtering, which is identical to the gtiandfile passed to 'saextrct' to produce the input spectrum. 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.

respfile = "NONE" [string]
Name of output response matrix file, or "NONE". The response matrix will be tailored for the specific observation. The 'filtfile' parameter must also be supplied when a response matrix is desired. A value of "NONE" means to not calculate a response matrix.

filtfile = "NONE" [string - file name]
Name of RXTE filter file which covers the complete requested observation duration, and is used for calcalating a response matrix. This parameter is not required if respfile=NONE. You may give an @filtfile.lis type file, but the filtfile.lis file must list only a single filter file (not multiple files).

(syserrfile = "CALDB") [string]
Systematic error vector to be applied to the resulting source spectrum. A value of CALDB (the default) causes the task to retrieve this file from RXTE CALDB (dated 20230501 or later). A value of NONE disables the application of a systematic error estimate.

(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 spectrum. Use "ON" for the on-time column, which results in a standard non-dead-time corrected spectrum (the basic detector on-time exposure is calculated).

(ra = "INDEF") [string]
Right ascension of target in J2000 degrees. The value overrides the RA_OBJ keyword value set in the PHA header. If a value of "INDEF" is provided, then the source position in the PHA file is left unmodified.

(dec = "INDEF") [string]
Declination of target in J2000 degrees. The value overrides the DEC_OBJ keyword value set in the PHA header. If a value of "INDEF" is provided, then the source position in the PHA file is left unmodified.

(respdate = "INFILE") [string]
Date to use for computing the response matrix, in the form YYYY-MM-DD. Or use "INFILE" to use exposure-weighted centroid time of the spectrum.

(gtiorfile = "APPLY") [string]
Name of GTI "OR" time filtering, which is identical to the gtiorfile passed to 'saextrct' to produce the input spectrum.

(gticols = "START STOP") [string]
Name of GTI start/stop column names, which is identical to the gticols passed to 'saextrct' to produce the input spectrum.

(timecol = "TIME") [string]
Name of TIME column used for extraction, which is identical to the timecol passed to 'saextrct' to produce the input spectrum.

(timemin = INDEF) [double precision real]
Minimum start time (MET) used for accumulation, which is identical to the timemin passed to 'saextrct' to produce the input spectrum.

(timemax = INDEF) [double precision real]
Maximum start time (MET) used for accumulation, which is identical to the timemax passed to 'saextrct' to produce the input spectrum.

(timeint = INDEF) [double precision real]
Comma-separated list of time intervals (MET), which is identical to the timeint passed to 'saextrct' to produce the input spectrum.

(accumulate = "ONE") [string]
Setting passed to 'saextrct'. Use "ONE" to extract one summed spectrum (RECOMMENDED), or "MANY" to extract a "Type II" spectrum for each Standard2 column (NOT RECOMMENDED). WARNING: setting accumulate=MANY is not compatible with requesting a response matrix.

(phazeroexp = YES) [boolean]
If set to YES, then a spectrum is produced even if zero exposure is detected. This occurs if the combination of GTIs and PCU on-time produces a valid spectrum but it has no live time. If phazeroexp=NO, then no spectrum is produced if zero exposure is detected.

(respzeroexp = NO) [boolean]
If set to YES, then a dummy response matrix is calculated even if zero exposure is detected (all PCUs assigned equal weight). If respzeroexp=NO, then no response is calculated if zero exposure is detected. You must use special care when setting respzeroexp=YES. In particular, when combining spectra, the responses must be weighted according to exposure, otherwise the PCUs will be weighted incorrectly.

(lcbinarray = INDEF) [string]
Setting passed to 'saextrct'. The default value is 400000. Set to a larger value for better performance on larger data sets.

(gtiarray = INDEF) [string]
Setting passed to 'saextrct'. The default value is 30000. Set to a larger value if you exceed the limit.

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

                   pcaextspect2 
                     [ interactive prompts follow ]
                     Input Standard2 file name or @file-of-filenames: FS4a_1ee05555-1ee062c0_DT
                     Input background file name or @file-of-filenames: FS4a_1ee05555-1ee062c0_DT_bkg
                     Output dead-time corrected source spectrum: spectrum_srcDT.pha
                     Output dead-time corrected background spectrum: spectrum_bkgDT.pha
                     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
                     Name of output response matrix file (or NONE): spectrum.rsp
                     Name of XTE filter file (or NONE): filtfile=x95422010409.xfl.gz

2. Calling from command line:

                   pcaextspect2 src_infile=FS4a_1ee05555-1ee062c0_DT \\
                                bkg_infile=FS4a_1ee05555-1ee062c0_DT_bkg \\
                                src_phafile=spectrum_srcDT.pha bkg_phafile=spectrum_bkgDT.pha \\
                                gtiandfile="-" pculist=ALL layerlist=ALL \\
                                respfile=spectrum.rsp filtfile=x95422010409.xfl.gz

3. Using "@-files" instead of simple file names:

                   # Use wild-card to find source files (EXAMPLE ONLY)
                   ls obsid/pca/FS4a*_DT > source.lis
             
                   # Use wild-card to find background files (EXAMPLE ONLY)
                   ls obsid/pca/FS4a*_DT_bkg > background.lis
              
                   pcaextspect2 src_infile=@source.lis bkg_infile=@background.lis \\
                                src_phafile=spectrum_srcDT.pha bkg_phafile=spectrum_bkgDT.pha \\
                                gtiandfile="-" pculist=ALL layerlist=ALL \\
                                respfile=spectrum.rsp filtfile=x95422010409.xfl.gz


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


SEE ALSO

saextrct, pcaprepfile2, pcaprepobs2, pcadeadcalc2, pcadeadspect2, pcaphasyserr

CATEGORY

Jan95 ftools.xte