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 file (RMF; aka a response matrix) 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 file (ARF) is a 1-dimensional array containing the effective area of the optics as a function of incident photon energy. MARFRMF provides the capability to multiply the redistribution array for each channel (along the incident energy dimension) by the ancillary response array (as long as both the RMF and ARF follow the HEASARC file formats). A detailed description of the both the input & output FITS file formats is given in George et al. (1992 Legacy, 2, 51), and in the OGIP Calibration Memos CAL/GEN/92-002 & CAL/GEN/92-002a.

The output of MARFRMF is a new FITS file containing the new redistribution matrix multiplied by the ancillary response. The output file is 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 in which only the values 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 input 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 input 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 is used.

(ebfil = '%') [character string]

The name of the file containing the input 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 is 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 input 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 is used. If a value of 'NONE', 'none' or ' ' is entered the user will be prompted for the scalar value by which the the input redistribution dataset is to be multiplied/divided.

outfil [character string]

The name of the RMF file to be created. The name of the output file CANNOT be the same as any of the input files unless CLOBBER = Y. However, the existing file can be automatically removed, and the new file written if the output filename is preceeded by "!" at the outfil prompt.

(rmfversn) [character string]

The OGIP FITS format version for RMF files in which the output FITS file is to be written.

(qoverride = no) [boolean]

Logical. If "yes", use the TELESCOP, INSTR, DETNAM and FILTER keywords from MARFRMF parameter file. If "no", then use the keyword values from the input file. 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 no 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. Default is no.

(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

CATEGORY