.help gcorrmf Aug95 ftools.caltools
.ih
NAME
gcorrmf -- remaps a detector redistribution matrix in channel-space.
.ih
USAGE
   gcorrmf infile shftfile outfile 
.ih
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 
.nf
    MINCHAN MAXCHAN NCHAN
.fi
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.
.ih
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.
.ih
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

.ih
SUPPORTED FITS FILE FORMATS

Currently only the following OGIP standards are supported by this task
.ls For the RSP_MATRIX extension:
.ls HDUCLAS1/HDUVERS1= 'RESPONSE'/'1.0.0'
.le
.ls HDUCLAS2/HDUVERS2= 'RSP_MATRIX'/'1.1.0'
    (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.1.0'
.le
.le

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

.ih
PARAMETERS
.le
.ls infile [character string]
 The name of the FITS RMF file to be remapped in channel-space
.le
.ls (ebdfile="%") [character string]
 The name of the FITS EBOUNDS file, this is usually an extension in the
 rmf file, therefore this is the default.
.le
.ls outfile [character string]
 The name of the FITS file to be written containing the remapped RMF dataset
.le
.ls shftfile [character string]
 The name of an ascii file specifying the remapping information. The ascii 
 file format should be of the form :
.br
.ce 
  1 20 -1
.ce
 21 30 0
.ju
 where channels 1 to 20 are shifted back by one, and 21 to 30 stay as they are.
.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 (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
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:
.nf
     ca> gcorrmf my_file.rmf remap.rmf shft.txt
.fi
.ih
BUGS
None known
.ih
SEE ALSO
.nf
CAL/GEN/92-002 (George etal 1992 Legacy, 2, 51),
CAL/GEN/92-002a
.fi
.ih
LOG OF SIGNIFICANT CHANGES
.ls v1.0.0 (1995 Aug)
    Initial public release
.le
.ls v1.2.0 (1996 Aug)
    Fractional shifts added
.le
.ih
PRIMARY AUTHOR
.nf
Rehana Yusaf
HEASARC
NASA/GFSC
http://heasarc.gsfc.nasa.gov/cgi-bin/ftoolshelp
.fi
.endhelp
