NAME
ftmarfrmf -- multiplies/divides a detector redistribution matrix by
an ancillary response dataset or a scalar
USAGE
ftmarfrmf rmffile[ext#] (ebdfile[ext#]) arffile[ext#] outfile (rmfversn)
(qoverride) telescop instrume filter detnam (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
- rmffile [filename]
- 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.
- (ebdfile = '%') [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 "ebdfile = %"
indicating that the rmffile will be used.
- arffile [filename]
- 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.
- outfile [filename]
- 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 outfile prompt.
- (rmfversn) [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 [string]
- The user-supplied string for the telescope name, required if
QOVERRIDE=Y
- instrume [string]
- The user-supplied string for the instrument name, required if
QOVERRIDE=Y
- filter [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 [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.
- (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 arffile = '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') [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.
EXAMPLES
ftmarfrmf test.rmf test.arf test.rsp
LAST MODIFIED
January 2022