GCORRMF (Aug95) ftools.caltools GCORRMF (Aug95) NAME gcorrmf -- remaps a detector redistribution matrix in channel-space. USAGE gcorrmf infile shftfile outfile DESCRIPTION This task remaps a detector redistribution matrix in channel-space. IT SHOULD ONLY BE USED IF ONE KNOWS WHAT ONE IS DOING, or AS INSTRUCTED by the relevant guest investigator facility. The incorrect use of this task , or without understanding the implications will result in errorneous results during subsequent spectral analysis. A detector redistribution matrix (aka detector 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. For the following discussion it is useful to think of the matrix as a column of values (probability for various incident photon energies) for each detector channel. Given an OGIP-approved FITS format input file, this task provides the facility to move the user-defined elements (columns) of the array to the left or right (ie down or up in channel-space) by a user-defined number of channels. It is difficult to generalise, but such a facility may be useful for converting a detector redistribution matrix constructed for a given (standard) gain of a detector to the gain actually applicable to an observation.Again, if you have no idea what we're talking about here, and have not been explicitly instructed to use this task, then we strongly recommend you seek further advice. The shift to be applied to each channel of the i/p detector redistribution matrix must be specified by an ASCII i/p file. The format of each row of this i/p ASCII file must be MINCHAN MAXCHAN NCHAN denoting all 'columns' of the i/p detector redistribution matrix between detector channels MINCHAN and MAXCHAN (inclusive) are to be shifted by NCHAN. The shift, NCHAN, can be any REAL value, thereby supporting positive, negative, and fractional channel shifts. Any channel ranges "implied" by their exclusion from the ASCII file will be shifted by zero channels. Note that should the shift applied to two or more 'columns' result in those columns being in the same o/p detector channel, then their respective probabilities (that an incident photon of a given energy will be detected in that detector channel) WILL BE SUMMED. Similarly, should the applied shifts result in an o/p detector channel 'column' NOT being populated, then the probability (that an incident photon of a given energy will be detected in that detector channel) will be set to zero. However, shifts below the minimum, and above the maximum legal channel number for the instrument will result in those probabilities being excluded. LIMITATONS ON USE Users should be aware that, at the current time, this task does NOT alter the EBOUNDS extension of the i/p detector redistribution matrix. This may be formally incorrect under certain circumstances, but the error introduced will not effect spectral analysis using XSPEC, and is minimal under most circumstances. WARNINGS ON USAGE This task remaps a detector redistribution matrix in channel-space. It should only be used if one knows what one is doing, or as instructed by the relevant guest investigator facility. The use of this task incorrectly, or without understanding the implications WILL RESULT IN INCORRECT RESULTS DURING SUBSEQUENT SPECTRAL ANALYSIS. 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 (approx) swap space required by the current version of this task: 21 Mbyte SUPPORTED FITS FILE FORMATS Currently only the following OGIP standards are supported by this task For the RSP_MATRIX extension: HDUCLAS1/HDUVERS1= 'RESPONSE'/'1.0.0' HDUCLAS2/HDUVERS2= 'RSP_MATRIX'/'1.1.0' (commonly also known as "RMFVERSN=1992a") For the EBOUNDS extension: HDUCLAS1/HDUVERS1= 'RESPONSE'/'1.0.0' HDUCLAS2/HDUVERS2= 'EBOUNDS'/'1.1.0' For further details see OGIP Calibration Memo CAL/GEN/92-002a. PARAMETERS infile [character string] The name of the FITS RMF file to be remapped in channel-space (ebdfile="%") [character string] The name of the FITS EBOUNDS file, this is usually an extension in the rmf file, therefore this is the default. outfile [character string] The name of the FITS file to be written containing the remapped RMF dataset shftfile [character string] The name of an ascii file specifying the remapping information. The ascii file format should be of the form : 1 20 -1 21 30 0 where channels 1 to 20 are shifted back by one, and 21 to 30 stay as they are. (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. EXAMPLES 1. To remap the channel-space in "my_file.rmf" to obtain a new file with remapped matrix, "remap.rmf" by using a file, "shft.txt" containing the remapping info: ca> gcorrmf my_file.rmf remap.rmf shft.txt BUGS None known SEE ALSO CAL/GEN/92-002 (George etal 1992 Legacy, 2, 51), CAL/GEN/92-002a LOG OF SIGNIFICANT CHANGES v1.0.0 (1995 Aug) Initial public release v1.2.0 (1996 Aug) Fractional shifts added PRIMARY AUTHOR Rehana Yusaf HEASARC NASA/GFSC http://heasarc.gsfc.nasa.gov/cgi-bin/ftoolshelp (301) 286-6115