MARFRMF (Apr95) ftools.caltools MARFRMF (Apr95) NAME marfrmf -- multiplies/divides a detector redistribution matrix by an ancillary response dataset or a scalar USAGE marfrmf rmfil[ext#] (ebfil[ext#]) arfil[ext#] outfil (rmfversn) (qoverride) telescop instrume filter detnam (chatter) (clobber) scalar (qdivide) (arfcol) DESCRIPTION A detector redistribution matrix (aka response matrix) basically consists of a 2-dimensional array (detector channel vs incident photon energy) giving the probability that an incident photon of a given energy will be detected in a given detector channel. An ancillary response dataset is a 1-dimensional array as a function of incident photon energy (containing, for example, the effective area of the optics, corrections for the spatial point spread function etc). Provided the input files are in an OGIP-approved FITS format, this task provides the facility to multiply the redistribution array for each channel (along the incident energy dimension) by the ancillary response array. The output is thus a new FITS 'RMF' file containing the new redistribution matrix. A detailed description of the both the i/p & o/p FITS file formats is given in George etal (1992 Legacy, 2, 51), and in the OGIP Calibration Memos CAL/GEN/92-002 & CAL/GEN/92-002a available via the OGIP anonymous ftp account on legacy.gsfc.nasa.gov (see caldb/docs/memos/README).In brief, the o/p file consists of a FITS file with 2 BINTABLE extensions (both of which have HDUCLAS1 = RESPONSE), containing: (1) the redistribution matrix (with HDUCLAS2 = RSP_MATRIX) (2) the nominal energies of the channel boundaries, (with HDUCLAS2 = EBOUNDS) The data contained in Extension (1) above is in a compressed format whereby only elements for which the value of the redistribution matrix above a given threshold are stored. This provides a significant reduction in disk-storage requirements for sparsely populated matrices. The default threshold is read from the i/p file. Users are reminded that the threshold is defined in absolute units (NOT relative to the value of the maximum value in the matrix). PARAMETERS rmfil [character string] The name of the RMF file containing the i/p redistribution matrix (and extension number in square brackets) to be used. If no extension number is specified, or an asterisk is supplied for the extension number, then all extensions in the FITS file will searched for an extension containing an RSP_MATRIX dataset, and (assuming only one is found) that extension used. (ebfil = '%') [character string] The name of the file containing the i/p EBOUNDS dataset (and extension number in square brackets) to be used. If no extension number is specified, or an asterisk is supplied for the extension number, then all extensions in the FITS file will searched for an extension containing an EBOUNDS dataset, and (assuming only one is found) that extension used. Since the EBOUNDS extension corresponding to a given RSP_MATRIX usually resides in the same file as the RSP_MATRIX, this parameter is HIDDEN with the default value "ebfil = %" indicating that the rmfil will be used. arfil [chracter string] The name of the ARF file (and extension number in square brackets) containing the ancillary spectral response dataset with which the i/p redistribution matrix is to be multiplied/divided. If no extension number is specified, or an asterisk is supplied for the extension number, then all extensions in the FITS file will searched for an extension containing an SPECRESP dataset, and (assuming only one is found) that extension used. If a value of 'NONE', 'none' or ' ' is entered the user will be prompted for the scalar value by which the the i/p redistribution dataset is to be multiplied/divided. outfil [character string] The name of the RMF file to be created. For safety, the name of the o/p file CANNOT be the same as one of the i/p files, and the task will stop if this is the case. Under unix/ultrix, an o/p filename identical to a file which already exists on disk is also considered illegal, and the task will stop. However, the existing file can be automatically removed, and the new file written if the o/p filename is preceeded by "!" at the outfil prompt. (rmfversn) [character string] The OGIP FITS format version for RMF files in which the o/p FITS is to be written. (qoverride = no) [boolean] Logical indicating whether the user wishes to override the deconvolution of the mission and instrument strings derived from the corresponding string supplied in the SF file. This is often necessary since the task only performs a rather crude deconvolution itself and since the RSP file often contains non-OGIP-standard strings, and/or insufficient information. The default is QOVERRIDE=N telescop [character string] The user-supplied string for the telescope name, required if QOVERRIDE=Y instrume [character string] The user-supplied string for the instrument name, required if QOVERRIDE=Y filter [character string] The user-supplied string for the name of any moveable filter in use, required if QOVERRIDE=Y. FILTER=NONE should be used if on such moveable filter is in use. detnam [character string] The user-supplied string for the sub-instrument name, required if QOVERRIDE=Y. DETNAM=NONE should be used if the specification of a sub-instrument is unneccessary. (chatter = 9) [integer] Flag to indicate how chatty the task is at execution. A value of 9 is the default, with lower/higher values producing quieter/verbose output respectively. (clobber = false) [boolean] Flag specifying whether or not a pre-existing file with the same name as that requested as the output file from this task will be overwritten. scalar [real] Scalar value by which the RSP_MATRIX dataset is divided or multiplied. This parameter is only used when arfil = 'NONE', 'none' or ' ' is entered. (qdivide = no) [boolean] Flag to indicate whether the RSP_MATRIX dataset is DIVIDED (qdivide = yes) or MULTIPLIED (qdivide = no) by the SPECRESP dataset/scalar. (arfcol = 'SPECRESP') [character string] The column name to use to read the ARF data. SPECRESP is the standard but this parameter allows another column to be read if necessary. BUGS None known SEE ALSO CAL/GEN/92-002 (George etal 1992 Legacy, 2, 51), CAL/GEN/92-002a LOG OF SIGNIFICANT CHANGES v3.2.6 (2005 Jul) Added arfcol parameter v2.2.0 (1995 Apr) Added scalar & qdivide parameters v2.0.0 (1993 Aug) Added dynamic memory allocation v1.0.0 (1992 Oct) Beta-test version PRIMARY AUTHOR Ian M George HEASARC NASA/GFSC http://heasarc.gsfc.nasa.gov/cgi-bin/ftoolshelp (301) 286-6094