NAME

pcarsp -- construct RXTE PCA response matrix for spectral data (RMF+ARF)

DESCRIPTION

This script runs the various tools necessary to construct response matrices for XTE PCA spectral data. The user inputs the PCA layers and detectors which were used in the construction of the PHA file (third and fifth inputs, below). The script creates .rsp files for these layers and detectors respectively, and combines them as required by the PHA file (fourth and sixth inputs, below).

The script creates matrices by first constructing "fundamental" .rmf files by layer or detector, depending on which is requested. If required by the data mode, the EDS gain and offset values are applied. The .rmf is then binned according to the binning in the input .pha file. A corresponding .arf file is constructed using the pointing information for the observation. The .rmf and .arf are then multiplied into a .rsp file. Layer .rsp files may be combined into a detector .rsp file or left separate. Likewise, detector .rsp files may be combined into a single pca instrument .rsp file or left separate The name(s) of the final .rsp file(s) are written back to the input .pha file.

Files created by the script are named by pcu number, a layer id ("xe" if entire detector), and the date (yyyy-mm-dd) of the observation. Through the -n <filename> command line option, the user may specify an alternate name for the final output file instead of using the default. Note that this applies only when the product of the script is a single matrix. The only files needed by XSPEC are certain .rsp files. The user has the option to retain or delete the .arf, .rmf, .txt, and unnecesarry .rsp files created by the script.

PARAMETERS

The user inputs to the script are as follows:

"Input the PHA file: "

the name of the .pha file, assumed to be the output of SA/SEEXTRCT. Both Type I and Type II files are supported. Command line option: -f <pha filename>.

"Input the Attitude file: "

the name of the file containing the spacecraft pointings for the observation. This file may be either the XTE FILTER file, or the estimated quaternions ("FH0e_*"), either of which may be obtained via the XTE Data Finder (XDF). This may also be of the form @filename for an ascii file containing the name of the attitude file. Finally, a value of 'none' may be used when the attitude file is unavailable or inadequate. With 'none' the resulting rsp file will assume an on-axis pointing to the target. Command line option: -a <attitude filename>.

"Input the layers included in the PHA file [L1,R1,LR1, etc, or all] "

The layers included in the input pha file. The user may input halves of particular layers (e.g. L1,R1) or combined halves (e.g. LR1 for layer 1). Ignored when using the "-s" option. Command line option: -l <layer list>.

"Are the layers added ? [y/n]: "

whether the pcu detector layers have been added in creating the .pha file. If yes, then detector response matrices will be constructed. If no, then a separate response matrix for each requested layer will be constructed. As a special case, if all layers are included and added, then a single detector response matrix is created for each desired detector. Ignored when using the "-s" option. Command line option: -j <y/n>.

"Input the detectors included in the PHA file [0,1,2,3,4, or all]: "

The detectors included in the input pha file. A range may be given, e.g. 0-2,4. Ignored when using the "-s" option. Command line option: -p <pcu list>.

"Are the detectors added ? [y/n]: "

Whether the detectors have been added in creating the input pha file. If yes, a single response matrix is produced from the sum of the requested detectors. The yes option is appropriate only for Type I pha files containing a single spectrum. If no, the detector matrices are left separate. The no option is appropriate for Type II pha files containing multiple spectra. Ignored when using the "-s" option. Command line option: -m <y/n>.

Additional command line options:

        pcarsp -n <filename> -d <date> -e <e2c_file> -x <ra> -y <dec> 
                 -c <partial charge fraction> -z

-n <filename>

The user may specify the name of the final response matrix instead of using the default name. Note that this applies only when a single matrix results from the script (e.g. when the detectors are added).

-d <date>

The user may specify the date for which the matrices should be created, in the format yyyy-mm-dd. By default, matrices are created for the observation date contained in the pha file. This option is superceded by the "-s" option.

-e <e2c_file>

The user may specify either a local calibration file or "caldb" (the default) for the energy-to-channel file.

-x <ra>

The user may specify an alternate right ascension for the source position. By default, matrices are created using the object's ra contained in the pha file.

-y <dec>

The user may specify an alternate declination for the source position. By default, matrices are created using the object's declination contained in the pha file.

-c <fraction>

The user may input the partial charge fraction to be used when computing the matrix. A non-zero value affects the shape of lines in the spectrum. As of pcarmf v8.0 the default value is 0.02 (was 0.0). This script now uses the value found in the pcarmf par file as the default.

-z <keep ?>

The user may keep unnecessary intermediate files created by the script by specifying this option. Default is to delete the files.

-s

Indicates that the script should use "Smart Standard2" processing which uses the ROWID keywords to determine the relevant layer and detector information and generates a single response file for the date in the .pha file. This option supercedes the "-l", "-j", "-p", "-m", and "-d" options.

-w <weights>

Sum the responses with the requested <weights>. <weights> can either be a comma-separated list of real values, or "@INFILE". A list must be five quantities of the form "1.0,1.0,1.0,1.0,1.0" and represent the weighting factors used by 'addrmf' to sum the responses of the individual PCUs. If "@INFILE" is used, then the the input PHA file must contain five keywords of the form PCU_WTn (n=0,1,2,3,4), which gives the same weights. Default: "-w 1.0,1.0,1.0,1.0,1.0" (equal summed weights)

CATEGORY