SISRMG (Apr97) ftools.asca SISRMG (Apr97) 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.