sisrmg -- SIS Response Matrix Generator
sisrmg infile arfile rmfile
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.
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.
sisrmg s0c1.pha NONE s0c1.rmf
Optional command line parameters are available to modify the matrix.
- 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.
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,
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,
- (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,... )
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
- (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
- (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
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, firstname.lastname@example.org.
Documentation for XSPEC, various OGIP documents, the other Ftools,
http://heasarc.gsfc.nasa.gov/docs/asca, http://space.mit.edu/~gbc, etc.