.help sisrmg Apr97 ftools.asca
.ih
NAME
sisrmg -- SIS Response Matrix Generator
.ih
USAGE
sisrmg infile arfile rmfile
.ih
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.
.ih
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:

.nf
  sisrmg s0c1.pha NONE s0c1.rmf
.fi

Optional command line parameters are available to modify the matrix.
.ih
PARAMETERS
.ls infile [file name]
The name of the PHA file for which a matrix is to be made.
Alternate possibilities are described below.
.le
.ls 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.
.le
.ls rmfile [file name]
The name of the output SIS response matrix file.
.le
.ih
OPTIONAL PARAMETERS
.ih
MATRIX CONSTRUCTION OPTIONS
.ls (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.
.le
.ls (datadir) [dir name]
Directory containing the various SISRMG calibration files.  Ignored for
files specified as "CALDB".
.le
.ls (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.
.le
.ls (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.
.le
.ls (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.
.le
.ls (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.
.le
.ls (phmin) [integer]
The minimum pulse height for which response is to be generated.
.le
.ls (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.
.le
.ls (sisde) [boolean]
Determines whether the SIS detector efficiency is included in the matrix.
The default (yes) is to include it.
.le
.ls (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.
.le
.ls (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.
.le
.ls (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.
.le
.ih
ENERGY SPACE OPTIONS
.ls (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.
.le
.ls (emin) [real]
The minimum of the energy range for which response is desired.
.le
.ls (emax) [real]
The maximum of the energy range for which response is desired.
.le
.ih
PHA FILE OPTIONS
.ls (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.
.le
.ls (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.
.le
.ls (detr) [integer]
The detector:  0 for SIS0 and 1 for SIS1.  Use 2 for unknown.
.le
.ls (chip) [integer]
The chip:  0, 1, 2 or 3.  Use 4 if unknown.
.le
.ls (xcen) [real]
The mean RAWX coordinate of the photons.  Use 0 if unknown.
.le
.ls (ycen) [real]
The mean RAWY coordinate of the photons.  Use 0 if unknown.
.le
.ls (xwid) [real]
The width (in RAWX) of the region of interest.  Use 0 if unknown.
.le
.ls (ywid) [real]
The width (in RAWY) of the region of interest.  Use 0 if unknown.
.le
.ls (evth) [integer]
The event threshold, usually at least 100.  Use 0 if unknown.
.le
.ls (spth) [integer]
The split threshold, usually 40.  A split threshold on echo corrected
FAINT data is also supported.  Use 0 if unknown.
.le
.ls (grades) [string]
A list of the digits 0..7 signifying the grades present in the spectrum,
or UNKNOWN.
(Cf. gmask.)
.le
.ls (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.)
.le
.ls (dmode) [string]
The datamode:  one of BRIGHT, BRIGHT2, FAST or UNKNOWN.  (Cf. gmask.)
.le
.ls (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:

.nf
	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,... )
.fi

Sample choices:

.nf
	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
.fi

.le
.ls (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.
.le
.ls (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.
.le
.ls (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.
.le
.ls (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.
.le
.ls (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.
.le
.ls (clobber) [boolean]
This parameter makes it possible to overwrite the output file,
should it exist.
.le
.ls (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:

.nf
        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          *       *
.fi

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

.ih
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:

.nf
  sisrmg NONE NONE s0c1.rmf ...
.fi

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:

.nf
  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

.fi

.ih
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.
.ih
SEE ALSO
Documentation for XSPEC, various OGIP documents, the other Ftools,
http://heasarc.gsfc.nasa.gov/docs/asca, http://space.mit.edu/~gbc, etc.
.endhelp
