|
RBNRMFSource FilesRelease Notes
RBNRMF (Aug95) ftools.caltools RBNRMF (Aug95)
NAME
rbnrmf -- Physically compresses (rebins) an RMF dataset in
channel-space.
USAGE
rbnrmf infile finchan cmpmode outfile
DESCRIPTION
RBNRMF compresses a FITS RMF matrix (redistribution matrix file
in an OGIP-standard format) in channel-space to give a user-defined
number of resultant channels. The output is a new file containing
the revised (compressed) RMF extension, and the corresponding
"EBOUNDS" extension containing the nominal energies of the revised
set of channel boundaries.
Caution is urged before RBNRMF 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 mode (or 'type') of compression performed is specified
via the user-defined "cmpmode" parameter.
A new parameter (fchan) is added in V4.2.0. This parameter
'fchan' allows users' option to define the first channel no. in the
output file. There are three options as follows:
(1) fchan=% (by default) which means that the first channel no. in
output is same as the first channel no. in input.
(2) fchan=0 which means that whatever be the first channel no. in
input file, the output first channel no. is zero.
(3) fchan=1 which means that whatever be the first channel no. in
input file, the output first channel no. is one.
COMPRESSION MODES
The following modes of compression (only) are currently allowed:
cmpmode='LINEAR'
In most cases (ie for most instruments & operating modes) only
a LINEAR compression is allowed. In such cases the compression
is such that 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, RBNRMF 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 RBNRMF 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 RBNRMF
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 RBNRMF 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.
WARNINGS ON USAGE
In order to minimise 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
RBNRMF 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 RBNRMF 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 & pay attention to the
channel-numbering scheme used to construct the PHA & RMF files.
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 compressed
(ebdfile) [character string]
The name of the FITS EBD input file. The Default, "%", means
that it is same as infile.
outfile [character string]
The name of the FITS file to be written containing the
compressed RMF dataset
(binfile='NONE') [character string]
The name of an ascii file specifying the binning information.
NOTE the default for this is NONE. If a filename is specified
then the parameters nchan and cmpmode are not prompted for.
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.
(fchan=%) [character string]
The option to define the output first channel no. By
default(%) it is same as input.
nchan [integer]
The number of channels required in the compressed RMF dataset
cmpmode [character string]
The compression mode to be used. Currently the only values
allowed are 'LINEAR', 'FAINT2BRIGHT' and 'BRIGHT2LINEAR' (see
above), with 'LINEAR' as the default.
(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 compress the channel-space in "my_file.rmf" to obtain a new
file with 512 channels, with linear compression mode :
ca> rbnrmf my_file.rmf 512 linear compress.rmf
BUGS
None known
SEE ALSO
CAL/GEN/92-002 (George etal 1992 Legacy, 2, 51),
CAL/GEN/92-002a
the ftools/heasarc task rbnpha
LOG OF SIGNIFICANT CHANGES
v4.4.0 (1998 Jun)
Modify the rebinning algorithm. Preserve the group
structure.
v4.2.0 (1996 Nov)
Added option of specifying first output channel no.
v3.0.0 (1995 Aug)
Added option of specifying binning in an ascii file
v2.0.0 (1994 Mar)
Added dynamic memory allocation
v1.0.0 (1993 Oct)
Initial public release
PRIMARY AUTHOR
Rehana Yusaf
HEASARC
NASA/GFSC
http://heasarc.gsfc.nasa.gov/cgi-bin/ftoolshelp
(301) 286-6115
Page author:Michael F. Corcoran Last Update: Thursday, 19-Apr-2012 16:01:40 EDT |
