.help marfrmf Apr95 ftools.caltools 
.ih
NAME
marfrmf -- multiplies/divides a detector redistribution matrix by an 
ancillary response dataset or a scalar
.ih
USAGE
marfrmf rmfil[ext#] (ebfil[ext#]) arfil[ext#] outfil (rmfversn) (qoverride)
        telescop instrume filter detnam (chatter) (clobber) scalar (qdivide)
        (arfcol)
.ih
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: 
.ls (1)  the redistribution matrix
	(with HDUCLAS2 = RSP_MATRIX)
.le
.ls (2) the nominal energies of the channel boundaries,
	 (with HDUCLAS2 = EBOUNDS) 
.le

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

.ih
PARAMETERS
.ls 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.
.le 
.ls (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.
.le
.ls 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. 
.le
.ls 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.
.le
.ls (rmfversn) [character string]
 The OGIP FITS format version for RMF files in which the o/p FITS is to be
 written.
.le
.ls (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
.le
.ls telescop [character string]
 The user-supplied string for the telescope name, required if QOVERRIDE=Y
.le
.ls instrume [character string]
 The user-supplied string for the instrument name, required if QOVERRIDE=Y
.le
.ls 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.
.le
.ls 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.
.le
.ls (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.
.le
.ls (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.
.le
.ls 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.
.le
.ls (qdivide = no) [boolean]
 Flag to indicate whether the RSP_MATRIX dataset is DIVIDED (qdivide = yes) 
 or MULTIPLIED (qdivide = no) by the SPECRESP dataset/scalar. 
.le
.ls (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.
.le

.ih
BUGS
None known

.ih
SEE ALSO
.br
.nj
CAL/GEN/92-002 (George etal 1992 Legacy, 2, 51),
.br
.nj
CAL/GEN/92-002a
.ju

.ih
LOG OF SIGNIFICANT CHANGES
.ls v3.2.6 (2005 Jul)
    Added arfcol parameter
.le
.ls v2.2.0 (1995 Apr)
    Added scalar & qdivide parameters
.le
.ls v2.0.0 (1993 Aug)
    Added dynamic memory allocation
.le
.ls v1.0.0 (1992 Oct)
    Beta-test version
.le

.ih
PRIMARY AUTHOR

.nj
Ian M George
.br
.nj
HEASARC
.br
.nj
NASA/GFSC
.br
.nj
http://heasarc.gsfc.nasa.gov/cgi-bin/ftoolshelp
.br
.nj
(301) 286-6094
.ju


.endhelp
