NAME
ftrbnrmf -- Physically compresses (rebins) an RMF dataset in
channel-space and/or energy space. Optionally compress an ARF with
the same energy space binning.
USAGE
ftrbnrmf infile [ebdfile] cmpmode [ecmpmode] [binfile] [phafile] nchan
[ebinfile] [ebfact] outfile [inarffile] [outarffile] [clobber]
DESCRIPTION
FTRBNRMF compresses a FITS RMF matrix (redistribution matrix file in an
OGIP-standard format) in channel-space and/or energy-space to give a
user-defined number of resultant channels and energy bins. The output
is a new file containing the revised (compressed) MATRIX extension,
and the corresponding EBOUNDS extension containing the nominal
energies of the revised set of channel boundaries.
Caution is urged before FTRBNRMF is used. The primary use of the task is
likely to be to compress RMF datasets in channel-space such that the
resultant number of channels matches that in a given PHA dataset.
Hence downstream spectral analysis packages can be used to
unambiguously map the channels in the PHA spectrum and Response
matrix. The binning can be either defined via a text file using the
hidden binfile parameter, from a grouping column in a pha file using the
hidden phafile parameter or using a specific mode (or 'type') of compression
defined by the cmpmode parameter.
If both inarffile and outarffile are set and energy-space binning is
in use then the given ARF file will be rebinned to match the RMF.
CHANNEL COMPRESSION MODES
The following modes of compression (only) are currently allowed
when binning in channel-space :
- cmpmode='binfile'
- Read the binning information from the filename specified by the
binfile parameter. This can be used to perform different linear
compressions over different channel ranges.
- cmpmode='phafile'
- Read the binning from the GROUPING column in the filename specified by the
phafile parameter.
- cmpmode='linear'
- In most cases (i.e. for most instruments and operating modes) only
a linear compression is allowed. The compression is such that
for a given compression factor F (calculated from the number of channels
in the original RMF extension and the number requested by the
user), the data applicable to channels 1 to F of the original
RMF matrix will be co-added to form channel 1 of the new matrix,
channels F+1 to 2*F of the old dataset channel 2 of the new
matrix etc. The number of channels requested in the output file
should be a factor of the number of channels in the input file.
- cmpmode='bright2linear'
- This is a non-linear compression mode which should only be used
on an ASCA SIS RMF which has the 'non-linear' channel-numbering
scheme appropriate for 'BRIGHT' datamode data, but which the
user wishes to use in conjunction with a PHA file from the same
instrument constructed whilst the instrument was operating in
another datamode (such as the SIS 'FAINT' datamode). In the
'BRIGHT' datamode SIS PHA spectra have only 2048 channels
(compared to 4096 PHA channels available within SIS 'FAINT'
datamode). This is is achieved by a non-linear binning-up the
PHA dataset carried out on-board ('FAINT' channels 1024 -> 2047
are binned by a factor 2 by the on-board electronics, and
'FAINT' channels 2048 -> 4096 by a factor 4). RMFs constructed
for use with 'BRIGHT' datamode data therefore are similarly
rebinned and hence have a 'non-linear' channel-numbering
scheme. The mode is designed to compensate for this fact, and
linearize the channel-number scheme such that it is appropriate
for PHA datasets collected whilst the SIS was not operating in
'BRIGHT' datamode. Thus, FTRBNRMF calculates and applies three
separate compression factors (F1, F2 & F3) to the input RMF
dataset over the input channel ranges 1 -> (Nin/2), (Nin/2 + 1)
-> (3Nin/4), and (3Nin/4 + 1) -> Nin (respectively), where Nin
is the number of channels in the input RMF file. The
compression factors are calculated assuming F1 = Ni/2 * 4/Nout
and F2 = F1/2, F3 = F1/4, where Nout is the requested number of
channels in the output RMF matrix. Nout must therefore be Nin/2
or smaller (by a factor divisible by 2) for FTRBNRMF to work in
this mode. The net result is that the resultant RMF file has a
linear channel-numbering scheme (equivalent to that used by the
'FAINT' datamode).
- cmpmode='faint2bright'
- This is a non-linear compression mode which should only be used
on an ASCA SIS RMF which has the linear channel-numbering
scheme appropriate for 'FAINT' datamode data, but which the
user wishes to use in conjunction with an SIS PHA file
constructed whilst the instrument was operating in 'BRIGHT'
datamode. The mode is designed to essentially perform the
opposite task to the 'BRIGHT2LINEAR' (see above). Again FTRBNRMF
calculates and applies three separate compression factors (B1,
B2 & B3) to the input RMF matrix over the input channel ranges
1 -> (Nin/4), (Nin/4 + 1) -> (Nin/2), and (Nin/2 + 1) -> Nin
(respectively), where Nin is the number of channels in the input
matrix. The compression factors are calculated assuming B1 =
Ni/4 * 2/Nout and B2 = 2*B1, B3 = 4*B3, where Nout is the
requested number of channels in the output RMF. Nout must be
Nin/2 or smaller (by a factor divisible by 2) for FTRBNRMF to
work in this mode. The net result is that the resultant RMF
file has a NON-LINEAR channel-numbering scheme, equivalent to
that used by the 'BRIGHT' datamode.
ENERGY COMPRESSION
The following modes of compression (only) are currently allowed
when binning in energy-space :
- ecmpmode='ebinfile'
- Read the binning information from the filename specified by the
ebinfile parameter. This can be used to perform different linear
compressions over different energy ranges.
- ecmpmode='optimal'
- Use the energy optimal binning from Kaastra and Bleeker 2016, A&A 587, A151.
- ecmpmode='linear'
- Perform linear binning using the factor given by the ebfact parameter.
WARNINGS ON USAGE
In order to minimize the disk-space requirements, the RMF matrix
is stored in compressed form (CAL/GEN/92-002), that is all matrix
elements below a given threshold (specified by LO_THRES keyword)
are not stored. Unfortunately the LO_THRES keyword is not always
used correctly, that is elements below this value are stored. When
FTRBNRMF is used on such a matrix, the values below LO_THRES will NOT
be stored. In order to overcome this, users may use the ftool/futil
FPARKEY to change the LO_THRES keyword value in the input RMF file.
The non-linear compression modes available for use with ASCA SIS
data should be used with extreme care. These FTRBNRMF modes are only
required if users wish to perform spectral analysis on a PHA
dataset taken in one on-board datamode in conjuncture with a
detector response designed for use with PHA data obtained in the
other datamode. Users are warned that it is not always immediately
obvious if a PHA file using one channel-numbering scheme is used
with a matrix using the other (though sharp discontinuities are a
dead giveaway). Unfortunately, at the present time it is not
possible to provide software checks for such errors, and it is the
responsiblity of the user to determine and pay attention to
the channel-numbering scheme used to construct the PHA and RMF files.
PARAMETERS
- infile [filename]
- The name of the FITS RMF file to be compressed
- (ebdfile) [string]
- The name of the input file with the EBOUNDS information. The
Default, "%", means that it is same as infile.
- cmpmode [string]
- The channel compression mode to be used. Allowed values are
'binfile', 'phafile, 'linear', 'faint2bright', 'bright2linear'
(see above), with 'linear' as the default.
- (binfile='NONE') [filename]
- The name of an ASCII file specifying the channel binning
information. NOTE the default for this is NONE.
The ASCII file format should be of the form :
1 256 2
where 1 is the starting channel, 256 the ending channel, and 2
the compression factor. NOTE : a compression factor of -1,
omits the channel(s),ie:
1 250 2
251 256 -1
in this case channels 1 to 250 are rebinned by a factor of 2,
and channels 251 to 256 are omitted.
The number of channels in each entry should be the multiple of
the compression factor.
This parameter will not be prompted for unless cmpmode is 'binfile'.
- (phafile='NONE') [filename]
- The name of standard type I pha file from which to take a grouping
(and quality) column to define the binning. This parameter will
not be prompted for unless cmpmode is 'phafile' or ecmpmode is 'optimal'
(see below).
- nchan [integer]
- The number of channels required in the compressed RMF dataset when
using one of the cmpmode options. This parameter will be prompted
for only if cmpmode is 'linear', 'faint2bright', or 'bright2linear'.
- (ecmpmode) [string]
- The energy compression model to be used. Allowed values are
'linear', 'ebinfile', or 'optimal', with 'linear' as the default.
- (ebinfile='NONE') [filename]
- The name of an ASCII file specifying the energy binning information.
This parameter has a default value of 'NONE', and will not be
prompted for unless ecmpmode is 'ebinfile'. The ASCII file format
is identical to that given above in the description of the binfile
parameter.
- (ebfact) [integer]
- The compression factor for energy binning. This must be a
divisor of the number of response energies in the input RMF.
This parameter will not be prompted for unless ecmpmode is 'linear'.
- outfile [filename]
- The name of the FITS file to be written containing the
compressed RMF dataset
- (inarfile) [filename]
- The name of the ARF file to be rebinned
- (outarfile) [filename]
- The name of the FITS file to be written containing the
compressed ARF dataset
- (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. Bin in channel space by a constant factor
ftrbnrmf infile=file1.rmf cmpmode=linear nchan=4096 outfile=fileout.rmf
2. Bin in energy space by a constant factor
ftrbnrmf infile=file1.rmf cmpmode=none ecmpmode=linear ebfact=2 outfile=fileout.rmf
3. Bin in both channel and energy space by a constant factor
ftrbnrmf infile=file1.rmf cmpmode=linear nchan=2048 ecmpmode=linear ebfact=2 outfile=fileout.rmf
4. Optimal binning in energy space using spectrum
ftrbnrmf infile=file1.rmf cmpmode=none ecmpmode=optimal phafile=file1.pha outfile=fileout.rmf
5. Bin in channel space using bin factors in a text file
ftrbnrmf infile=file1.rmf cmpmode=binfile binfile=binning.txt ecmpmode=none outfile=fileout.rmf
6. Bin in both channel and energy space by a constant factor
ftrbnrmf infile=file1.rmf cmpmode=linear nchan=1700 ecmpmode=linear ebfact=2 outfile=fileout.rmf
LAST MODIFIED
January 2022