RSP2RMF (Mar94) ftools.caltools RSP2RMF (Mar94) NAME rsp2rmf -- converts old-style (SF) format response matrices to OGIP FITS format USAGE rsp2rmf rspfil rmffil 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: (1) the redistribution matrix (with EXTNAME = SPECRESP MATRIX) (2) the nominal energies of the channel boundaries (with EXTNAME = 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, 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. SUPPORTED FITS FILE FORMATS Currently only the following OGIP standards are supported by this task (via the parameter rmfversn): For the RSP_MATRIX extension: HDUCLAS1/HDUVERS1= 'RESPONSE'/'1.0.0' HDUCLAS2/HDUVERS2= 'RSP_MATRIX'/'1.0.1' (commonly also known as "RMFVERSN=1992a") For the EBOUNDS extension: HDUCLAS1/HDUVERS1= 'RESPONSE'/'1.0.0' HDUCLAS2/HDUVERS2= 'EBOUNDS'/'1.0.1' For further details see OGIP Calibration Memo CAL/GEN/92-002a. 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'. 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. PARAMETERS rspfil [character string] The name of the old-style (SF) RSP file to be converted to OGIP-standard FITS format. rmffil [character string] The name of the OGIP-standard FITS file to be created (origin = 'UNKNOWN') [character string] The name of the organization and/or author running the task. The default value is ORIGIN=UNKNOWN. (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. (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. threshold [real] New threshold at which the matrix is to be truncated (only required if QREGRP=Y) (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 (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. (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 (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 (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 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 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. 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. (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. BUGS None known SEE ALSO CAL/GEN/92-002 (George etal 1992 Legacy, 2, 51), CAL/GEN/92-002a LOG OF SIGNIFICANT CHANGES v3.1.0 (1994 Jun) Improved dynamic memory allocation to minimize requirements v3.0.0 (1994 Mar) Added dynamic memory allocation v2.0.0 (1993 Aug) Added variable length arrays for RSP_MATRIX extension 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