NAME

ftgcorrmf - Remaps a detector redistribution matrix in channel or energy space.

USAGE

ftgcorrmf infile ebdfile shftfile eshftfile outfilel clobber

DESCRIPTION

This task remaps a detector redistribution matrix in channel or energy 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 erroneous 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 columns of the array to the left or right (ie down or up in channel-space) and the rows of the arrays up and down (ie up or down in energy-space). 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.

Channel Shifting

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 SHIFT FACTOR

denoting all 'columns' of the i/p detector redistribution matrix between detector channels MINCHAN and MAXCHAN (inclusive) are to be shifted by an additive SHIFT and multiplicative FACTOR. SHIFT and FACTOR can be any REAL value, thereby supporting positive, negative, and fractional channel shifts. If the first line of the file starts with "! " followed by an energy unit then SHIFT will be assumed to be those energy units and shifting will be calculated using the EBOUNDS extension. 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. Note that the channel number can be either 0-based or 1-based as specified in the TLMIN keyword for the F_CHAN column in the MATRIX extension of the input file.

Energy Shifting

The shift to be applied to each energy bin 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 either

MINEBIN MAXEBIN SHIFT

or
MINEBIN MAXEBIN SHIFT FACTOR

The contents of the energy bin with minimum energy Elow and maximum energy Ehigh are redistributed over the energy range Elow*FACTOR+SHIFT to Ehigh*FACTOR+SHIFT. Any energy bins "implied" by their exclusion from the text file will not be shifted. Note that should the shift applied to two or more 'rows' result in those rows being in the same o/p energy bin, then their respective probabilities (that an incident photon of a given energy will be detected in a given detector channel) WILL BE SUMMED. Similarly, should the applied shifts result in an o/p energy bin 'row' NOT being populated, then the probability will be set to zero. However, shifts below the minimum, and above the maximum legal energy bin number for the instrument will result in those probabilities being excluded. Note that energy bins count from 0 i.e. the first energy bin number is 0.

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 and energy 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.

PARAMETERS

infile [filename]
The name of the FITS RMF file to be remapped.

ebdfile [string]
The name of the FITS EBOUNDS file. This is a hidden parameter which defaults to "%", indicating that the EBOUNDS extension is to be taked from infile.

shftfile [filename]
The name of a text file giving the channel remapping information. Each line should contain 3 or 4 numbers, the first two listing the minimum and maximum channels to be remapped, the third the additive shift, and the optional fourth the multiplicative factor.

eshftfile [filename]
A hidden parameter for the name of a text file giving the energy remapping information. Each line should contain 3 or 4 numbers, the first two listing the minimum and maximum energy bins to be remapped, the third the additive shift, and the optional fourth the multiplicative factor.

outfile [filename]
The name of the output RSP file.

clobber [bool]
If clobber = yes then overwrite the output files if a file of the appropriate name already exists.

EXAMPLES

Shift all channels by half a channel using the file shift.txt containing

1 128 0.5
and the command
ftgcorrmf file1.rsp shift.txt fileout.rsp

SEE ALSO

LAST MODIFIED

Jan 2013