.help rbnrmf Aug95 ftools.caltools
.ih
NAME
rbnrmf -- Physically compresses (rebins) an RMF dataset in channel-space.
.ih
USAGE
rbnrmf infile finchan cmpmode outfile 
.ih
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.


.ih
COMPRESSION MODES

The following modes of compression (only) are currently allowed:
.le
.ls 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. 
.le
.ls 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).
.le
.ls 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. 

.ih
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'.
.br
.nj
The (approx) swap space required by the current version of this task:
21 Mbyte
.ju
 

.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 compressed 
.le
.ls (ebdfile) [character string]
 The name of the FITS EBD input file. The Default, "%", means that it is same
 as infile.
.le
.ls outfile [character string]
 The name of the FITS file to be written containing the compressed RMF dataset
.le
.ls (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 : 
.br
.ce
 1 256 2
.ju
 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:
.br
.ce
  1  250  2
.ce
 251 256 -1
.ju
 in this case channels 1 to 250 are rebinned by a factor of 2, and channels
 251 to 256 are omitted. 
.br 
 The number of channels in each entry should be the multiple of the 
 compression factor.
.le
.ls (fchan=%) [character string]
 The option to define the output first channel no.  By default(%) it is same
as input.
.le
.ls nchan [integer]
 The number of channels required in the compressed RMF dataset
.le
.ls 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.
.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 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

.fi


.ih
BUGS
None known

.ih
SEE ALSO
.br
.nj
CAL/GEN/92-002 (George etal 1992 Legacy, 2, 51),
.br
.nj
CAL/GEN/92-002a
.br
.nj
the ftools/heasarc task rbnpha
.br
.ju

.ih
LOG OF SIGNIFICANT CHANGES

.ls v4.4.0 (1998 Jun)
     Modify the rebinning algorithm. Preserve the group structure.       
.le
.ls v4.2.0 (1996 Nov)
     Added option of specifying first output channel no.
.le
.ls v3.0.0 (1995 Aug)
    Added option of specifying binning in an ascii file
.le
.ls v2.0.0 (1994 Mar)
    Added dynamic memory allocation
.le
.ls v1.0.0 (1993 Oct)
    Initial public release
.le

.ih
PRIMARY AUTHOR

.nj
Rehana Yusaf
.br
.nj
HEASARC
.br
.nj
NASA/GFSC
.br
.nj
ftoolshelp@athena.gsfc.nasa.gov
.br
.nj
(301) 286-6115
.ju

.endhelp
