NAME

sisrmg -- SIS Response Matrix Generator


USAGE

sisrmg infile arfile rmfile


DESCRIPTION

This task generates the SIS response matrix appropriate to an instrument parameter regime as defined by keywords found in the infile FITS header. If an ancillary response file is found, its energy space information will be used to construct the response matrix. Otherwise, hidden parameters are used to construct the energy space for the resulting response matrix file.


STANDARD USAGE

It is recommended that the user run SISRMG on XSELECT-generated PHA files to ensure that all information required to reliably produce the proper matrix is present in the input PHA file. For example: 

       sisrmg s0c1.pha NONE s0c1.rmf

Optional command line parameters are available to modify the matrix.


PARAMETERS

infile [file name]
The name of the PHA file for which a matrix is to be made. Alternate possibilities are described below.

arfile [file name]
The name of the ancillary response file. If this file is missing the energy domain of the matrix will be constructed from the emin, emax and ebin hidden parameters.

rmfile [file name]
The name of the output SIS response matrix file.


OPTIONAL PARAMETERS


MATRIX CONSTRUCTION OPTIONS

(vers) [real]
The response version to use. The current version is 1.1; however, versions 0.8 and 0.9 are available for backward compatibility.

(datadir) [dir name]
Directory containing the various SISRMG calibration files. Ignored for files specified as "CALDB".

(ecdata) [file name or "CALDB"]
ECD FITS calibration file: separate files are used for each detector, chip and split threshold combination. If "CALDB", use the ECD files from the Calibration Database. Otherwise, look for the named file in datadir.

(phtopi) [file name or "CALDB"]
CTI FITS calibration file: contains the gain history and other CTI related data. If "CALDB", use the CTI file from the Calibration Database. Otherwise, look for the named file in datadir.

(echosh) [file name or "CALDB"]
ECHO FITS calibration file: contains the echo history. If "CALDB", use the ECHO file from the Calibration Database. Otherwise, look for the named file in datadir.

(rddhis) [file name or "CALDB"]
RDD FITS calibration file: contains the residual dark distribution history. If "CALDB", use the RDD file from the Calibration Database. Otherwise, look for the named file in datadir.

(phmin) [integer]
The minimum pulse height for which response is to be generated.

(phmax) [integer]
The maximum pulse height for which response is to be generated. Note that the phmin and phmax parameters refer to the intrinsic SIS ADU scale before any compression for telemetry (BRIGHT and FAST modes) and any rebinning. Thus these values are typically 0 and 4095.

(sisde) [boolean]
Determines whether the SIS detector efficiency is included in the matrix. The default (yes) is to include it.

(sispi) [boolean]
Determines whether the output response matrix is to be used with PI channels. The default (no) is generate a matrix for the actual instrument PHA. This parameter is ignored if a valid PHA/PI file is used.

(gains) [integer]
A parameter which controls the smoothness of the energy to PH mapping in the EBOUNDS extension. A value of zero (the default) gives a piecewise linear function tracking the energy-ph peak in the response; the values 1-12 provide increasing smoothness of this function; the values -1 gives a linear function between the endpoints; and the value -2 gives a linear function of the mean slope.

(first) [integer]
The naming convention for the pulse height channels. The intrinsic SIS pulse height numbering (ADU's) starts with 0, but earlier versions of XSPEC and RBNPHA favored a value of 1 as the first channel. Either convention works, provided consistent information is passed via the TLMIN/TLMAX keywords in the PHA and RMF files.


ENERGY SPACE OPTIONS

(ebin) [integer]
If no ARF is provided, SISRMG will generate a simple ARF with unit effective area based on the values of ebin, emin and emax. If ebin is positive, the energy range is partitioned in a linear fashion; if it is negative, logarithmically spaced bins are used. If ebin is zero, these values are taken from the telescope ascii file, if available. Such a file contains a list of triplets: energy, telescopy effective area, and tranmission factor. By setting the effective area and transmission to unity, you can construct an RMF with virtually any energy domain.

(emin) [real]
The minimum of the energy range for which response is desired.

(emax) [real]
The maximum of the energy range for which response is desired.


PHA FILE OPTIONS

(epch) [real]
The epoch (time in ASCA seconds) of the observation. The optional parameters in this section supply information that should be obtained from the PHA file. Use 0.0 if unknown.

(cmode) [integer]
CCD clocking mode: use 1, 2 or 4 for 1CCD, 2CCD or 4CCD mode, and use 0 for FAST mode. Use 3 if unknown.

(detr) [integer]
The detector: 0 for SIS0 and 1 for SIS1. Use 2 for unknown.

(chip) [integer]
The chip: 0, 1, 2 or 3. Use 4 if unknown.

(xcen) [real]
The mean RAWX coordinate of the photons. Use 0 if unknown.

(ycen) [real]
The mean RAWY coordinate of the photons. Use 0 if unknown.

(xwid) [real]
The width (in RAWX) of the region of interest. Use 0 if unknown.

(ywid) [real]
The width (in RAWY) of the region of interest. Use 0 if unknown.

(evth) [integer]
The event threshold, usually at least 100. Use 0 if unknown.

(spth) [integer]
The split threshold, usually 40. A split threshold on echo corrected FAINT data is also supported. Use 0 if unknown.

(grades) [string]
A list of the digits 0..7 signifying the grades present in the spectrum, or UNKNOWN. (Cf. gmask.)

(rebin) [string]
A string describing the degree and type of rebinning of the channels: 1,2,4,8 correspond to 4096, 2048, 1024, and 512 channel linear spectra; 1b, 2b, 4b, 8b correspond to 2048, 1024, 512 and 256 channel trilinear (BRIGHT mode) spectra. Use UNKNOWN if not known. (Cf. gmask.)

(dmode) [string]
The datamode: one of BRIGHT, BRIGHT2, FAST or UNKNOWN. (Cf. gmask.)

(gmask) [string]
The information of the parameters grades, rebin, and dmode may be coded in the single parameter gmask as follows. Gmask is a hexadecimal union of flags which specifies which event types are present, and in which fashion the PH data is has been encoded, including any rebinning. The flags are: 

                     Faint PH encoding                0x0001        ( 0 < PH < 4095 )
                     Faint/Bright Singles                0x0002        ( Grade 0 )
                     Faint/Bright Single+Corner        0x0004        ( Grade 1 )
                     Faint/Bright Vertical Split        0x0008        ( Grade 2 )
                     Faint/Bright Left Hor. Split        0x0010        ( Grade 3 )
                     Faint/Bright Right Hor. Split        0x0020        ( Grade 4 )
                     Faint/Bright Split+Corner        0x0040        ( Grade 5 )
                     Faint/Bright L & Square                0x0080        ( Grade 6 )
                     Faint/Bright Others                0x0100        ( Grade 7 )
                     Fast/Bright PH encoding                0x0200        ( 0 < PH < 2047 )
                     Fast Singles                        0x0400        ( Grade 0 )
                     Fast Others                        0x0800        ( Grade 1 )
                     Log2 of Rebin Factor                0xR000        (R == 0,1,2,... )

Sample choices: 

                     Faint Singles             (1024ch)        0x2003
                     Faint Grades 0,2-4    (512ch)        0x303b
                     Faint Grades 0,2-4,6 (4096ch)        0x00bb
                     Bright Singles             (1024ch)        0x1202
                     Bright Grades 0,2-4   (512ch)        0x223a
                     Fast Singles             (1024ch)        0x1600

(rddcorv) [integer]
The version of RDD correction code applied: 0 implies no correction was made before the spectral file was created (hence corrections are applied in making the matrix), a positive value is the version number of the correcting code, and a negative value implies the version should be determined from the input PHA file. This parameter is ignored with a valid PHA/PI input file.

(zerodef) [integer]
The mode of dark frame correction employed by FAINTDFE: 0 for the old FAINTDFE behavior, 1 for the new behavior, 2 for emulation of onboard BRIGHT mode, and 3 for unknown. This parameter is ignored with a valid PHA/PI input file.

(echo) [real]
Echo factor, if known. (A nonzero value signifies echo-corrupt data; the correct value is obtained from the secular history. A zero value indicated echo-corrected data.) The extreme value 1.0 signifies unknown.

(dark) [real]
Average dark frame error. FAINT mode data should be corrected with FAINTDFE. In the case of BRIGHT mode, or FAINT data requiring further correction, this parameter may be used to introduce an offset to the PH scale in the response matrix. The extreme value 100. signifies unknown.

(leak) [real]
The effects of a true light leak (an additional broadening of the response features) may be emulated by positive value for this parameter. The extreme value 100. signifies unknown.

(clobber) [boolean]
This parameter makes it possible to overwrite the output file, should it exist.

(chatr) [string]
SISRMG can produce copious output describing the response generation progress. You can control the amount of output with this parameter: no output (no), some output (yes), copious output (lots), or output on specific aspects of the process using a hexadecimal union of flags: 

                     What                            flag    no      yes     lots
                     Echo inputs to terminal         0x0001                  *
                     Calibration info echoed         0x0002                  *
                     Response Calculation echoed     0x0004          *       *
                     Ebounds Calculation echoed      0x0008          *       *
                     Put RMF in FITS Primary (+)     0x0010                  *
                     Put Inputs in FITS Primary      0x0020          *       *
                     Echo XRT EA information         0x0040
                     Echo RQT info in FITS Primary   0x0080          *       *
                     Factor ARF into RMF             0x0100
                     Calibration commentary          0x0200          *       *

(+) A FITS image of the matrix is produced in addition to the normal binary table extensions.


USAGE WITHOUT A PHA FILE

SISRMG may be used without an input PHA file in one of two modes. It is recommended to use a small number of energy bins to minimize the turn-around time while experimenting with these options.

In the first mode, you may supply all the information that should have been found in the PHA file with parameters on the command line: 

       sisrmg NONE NONE s0c1.rmf ...

In the second mode, you may use any input FITS file that contains a suitable set of RQ* keywords. These keywords are typically copied to the primary header of matrices generated by SISRMG, so you can actually use an existing matrix as the input for subsequent invocations of SISRMG.

Note that SISRMG reads its parameter interface first, then the PHA file, and then looks for RQ* keywords only if there is some problem. If these keywords are found, they override other input (i.e. the parameter interface).

The RQ* keywords are: 

       RQVERS  calibration version--the current version is 1.1.
       RQEPCH  the time of observation in ASCA seconds.  This is used
               to correct gain, echo and RDD secular effects.
       RQEVTH  the event threshold for identifying events
       RQSPTH  the split threshold used in classifying events
       RQXCEN/RQYCEN mean RAWX/Y coordinate for CTI gain correction
       RQXWID/RQYWID width about mean (currently ignored)
       RQTEMP  focal plane temperature (currently ignored)
       RQEVPF  events per frame (currently ignored)
       RQIMHI  image clock hi (currently ignored)
       RQIMLO  image clock lo (currently ignored)
       RQECHO  the amount of echo corruption present in the data.  If nonzero,
               then the appropriate echo value will be obtained from the
               secular file named by RQEHIS.  If this keyword is not present,
               or if the named file does not exist, then the value given in
               RQECHO is used.
       RQLEAK  allows for the inclusion of an average light leak in the
               response.  This produces both a gain shift as well as a
               broadening of certain spectral features.
       RQDARK  used to indicate whether FAINTDFE was applied to clean up faint
               mode data.  If zero, then it is assumed FAINTDFE was applied;
               however, there are known problems with the calibration in this
               case.  If RQDARK is nonzero, then SISRMG will consult the
               file named by RQRDDH for RDD data.  If this keyword is missing,
               or if the named file does not exist, then internal heuristics
               are used.  The actual nonzero RQDARK value is ignored.
       RQDETR  0 or 1 for SIS0 or SIS1.
       RQCHIP  0-3 for chips 0, 1, 2 or 3.
       RQMODE  F, 1, 2, 4 for Fast, 1-CCD, 2-CCD or 4-CCD mode data.
       RQPMIN  minimum intrinsic PH [ADU] in the response
       RQPMAX  minimum intrinsic PH [ADU] in the response
       RQMASK  mask of response features to include (Cf. gmask)
       RQCHTR  level of chattiness during execution
       RQEBIN  number of energy bins in response domain
       RQEMIN  minimum input energy for response domain
       RQEMAX  maximum input energy for response domain
       RQFRST  conventional first output PH channel; should be 1
       RQGANS  controls smoothing of data in EBOUNDS extension.
       RQDEFF  forces inclusion of detector efficiency when nonzero
       RQDOPI  forces generation of PI matrices when nonzero.  Note:
               although the PI gain is time-independent, the resolution
               and other characteristics of the response are secular.
       RQRDCV  External RDD Correction Version: <0,0,>0 == Unknown,None,Applied
       RQDFEZ  FaintDFE style 0,1,2 == Old,New,Bright
       RQFIL0  ascii ARF file
       RQFIL1  ECD gaussian data files
       RQFIL2  high ph tail files
       RQFIL3  grade branching adjustment files
       RQDIR0  root directory of SIS data files
       RQGECD  ECD FITS data file
       RQPHPI  CTI gain transformation file
       RQEHIS  Echo secular history file
       RQRDDH  Residual Dark Distribution history file


BUGS

A complete, new interface has been introduced for SISRMG v1.0. All known bugs were fixed for v1.1.

Please forward comments, feedback, etc. to the author of the software, Geoffrey Crew, gbc@space.mit.edu.


SEE ALSO

Documentation for XSPEC, various OGIP documents, the other Ftools, http://heasarc.gsfc.nasa.gov/docs/asca, http://space.mit.edu/~gbc, etc.

CATEGORY

Apr97 ftools.asca