.help rsp2rmf Mar94 ftools.caltools 
.ih
NAME
rsp2rmf -- converts old-style (SF) format response matrices to OGIP FITS format 
.ih
USAGE
rsp2rmf rspfil rmffil 
.ih
DESCRIPTION

  rsp2rmf reads i/p data from an old-stle (SF) format response matrix (used
by XSPEC versions <8.2), and writes an o/p FITS data file in OGIP standard 
format (able to be read by XSPEC versions >8.2). Users are urged to switch 
to using XSPEC with FITS files as soon as possible.

   A detailed description of the o/p FITS file format 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 (in Postscript) as
caldb/docs/memos/cal_gen_92_002.ps & cal_gen_92_002a.ps respectively. In
brief, the data is written in the form of 2 BINTABLE extensions,
containing: 
.br
.ls (1) the redistribution matrix 
	(with EXTNAME = SPECRESP MATRIX) 
.le
.ls (2) the nominal energies of the channel boundaries 
	(with EXTNAME = 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, but can be altered via the hidden 
parameters gregrp and threshold parameters. Users are reminded that the 
threshold is defined in absolute units (NOT relative to the value of the 
maximum value in the matrix).

  A further reduction in disk-storage space requirements can often be 
achieved by the use a variable-length array for the BINTABLE column 
containing the matrix. In such a case, the number of elements within this 
column varies between different rows of the BINTABLE. The current version of 
rsp2rmf will automatically write a variable-length array if a saving of 
greater than a factor 3 in storage space is indeed achieved.

.ih
SUPPORTED FITS FILE FORMATS

   Currently only the following OGIP standards are supported by this task 
(via the parameter rmfversn): 
.ls For the RSP_MATRIX extension:
.ls HDUCLAS1/HDUVERS1= 'RESPONSE'/'1.0.0'
.le
.ls HDUCLAS2/HDUVERS2= 'RSP_MATRIX'/'1.0.1'
    (commonly also known as "RMFVERSN=1992a")
.le
.le
.ls For the EBOUNDS extension:
.ls HDUCLAS1/HDUVERS1= 'RESPONSE'/'1.0.0'
.le
.ls HDUCLAS2/HDUVERS2= 'EBOUNDS'/'1.0.1'
.le
.le

For further details see OGIP Calibration Memo CAL/GEN/92-002a.

.ih
WARNINGS ON USAGE

  The current version of this task assumes that the matrix elements of the
input SF file have already been multipled by the total effective area of
the focussing/collimating optics, filters & detector efficiency (since this
is the case for all RSP files currently available within the OGIP). Thus
the redistribution matrix extension has the keyword HDUCLAS3= 'FULL'. This 
value of HDUCLAS3 is however incorrect in cases where the redistribution
matrix alone is stored, and hence the values of the HDUCLAS3 keyword of the
output file should be changed appropriately (see calibration memo OGIP/92-002a) 

  Users are reminded that the EBOUNDS extension contains only the nominal 
energies associated with each PHA/PI channel. Extreme care should be 
exercised if these are to be used by downstream software (see George
etal 1992 Legacy, 2, 51, section 3.2). The OGIP-supplied spectral fitting 
package, XSPEC, only uses the data within this extension for plotting 
purposes.

  The facility to override the deconvolution of the mission and instrument 
strings derived from the corresponding string supplied in the SF file
is often useful since the strings required to specify for which mission, 
instrument, detector and/or filter the dataset is valid in the case of the 
output FITS file are often very different to those used in the SF file.
Specifically, the SF RSP files often contain non-OGIP-standard strings, and/or 
insufficient information. A list of OGIP-standard strings can be found in
the OGIP Memos OGIP/93-013 available via the OGIP anonymous ftp account on
legacy.gsfc.nasa.gov (in Postscript) as caldb/docs/memos/ogip_93_013.ps.
The current version of the task only performs a rather crude deconvolution. 

  In order to handle the biggest matrices, this task employs a number of
relatively large internal arrays. These arrays are dynamically allocated,
but problems can arise at execution if the local machine runs out of swap
space. When this occurs, often an appropriate system error message will be
displayed or the program may simply crash. Under these circumstances users
will have to free up space by closing unwanted applications (windows,
tasks etc). Under unix/ultrix, the total used/available swap space on the
local machine can be listed (in kbytes) using the command 'pstat -T'.
.br
.nj
The largest matrix able to be handled by the current version of this task is
4096 channels by 2048 energies (requiring 35 Mbytes of swap space). Due to
dynamic memory allocation, the swap space requirements of most matrices are
dramatically smaller.
.ju


.ih
PARAMETERS
.ls rspfil [character string]
 The name of the old-style (SF) RSP file to be converted to OGIP-standard 
 FITS format.
.le
.ls rmffil [character string]
 The name of the OGIP-standard FITS file to be created
.le
.ls (origin = 'UNKNOWN') [character string] 
 The name of the organization and/or author running the task.
 The default value is ORIGIN=UNKNOWN.
.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 (qregrp = no) [boolean] 
 Logical as to whether the matrix read in from the RSP file is to be 
 truncated at a higher threshold, or simply written out to the FITS 
 file with the current threshold. The default is QREGRP=N.
.le
.ls threshold [real]
 New threshold at which the matrix is to be truncated 
 (only required if QREGRP=Y)
.le
.ls (qcif = no) [boolean] 
 Logical as to whether the CIF keywords are to be added to the FITS 
 file. The default is QCIF=N. 
 NOTE: NO ALTERNATIVES ARE CURRENTLY ALLOWED
.le 
.ls (rmfversn = '1.1.0') [charcter string]
 The OGIP FITS format version for response matrices in which the 
 o/p FITS is to be writen. The default is RMFVERSN=1.1.0 (previously 
 known as '1992a'), and is currently to only format allowed.
.le
.ls (qrmfcomm = no) [boolean] 
 Logical indicating whether comments are to be added to the RMF extension 
 from a previously prepared ASCII i/p file. The default is QRMFCOMM=N.
 NOTE: NO ALTERNATIVES ARE CURRENTLY ALLOWED
.le
.ls (qebdcomm = no) [boolean] 
 Logical indicating whether comments are to be added to the EBOUNDS extension 
 from a previously prepared ASCII i/p file. The default is QEBDCOMM=N.
 NOTE: NO ALTERNATIVES ARE CURRENTLY ALLOWED
.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 RSP 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 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 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 (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
.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.1.0 (1994 Jun)
    Improved dynamic memory allocation to minimize requirements
.le
.ls v3.0.0 (1994 Mar)
    Added dynamic memory allocation
.le
.ls v2.0.0 (1993 Aug)
    Added variable length arrays for RSP_MATRIX extension
.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

