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