.help rbnpha April94 ftools.heasarc 
.ih
NAME
rbnpha -- Physically compresses (rebins) a PHA dataset in channel-space.
.ih
USAGE
rbnpha infile outfile fchan finchan cmpmode
.ih
DESCRIPTION

  RBNPHA compresses a FITS PHA file (in an OGIP-standard format) to a
user-defined number of channels. The output is a new file containing the
revised PHA extension, along with a direct copy of any other extensions in
the original file. The output PHA dataset consists of the sum of the
original counts (or count rate) in each new channel, along with the
statistical and systematic errors added in quadrature. It should be noted
that if any channels are defined as bad (quality not equal to zero) in the
input file, when compressed, the bin containing that channel is also set to 
bad (quality = 5). 

 A new parameter (fchan) is added in V2.1.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.
     
  The mode (or 'type') of compression performed is specified via the
user-defined "cmpmode" parameter. 
.le
.ls cmpmode='LINEAR'
- only mode applicable for all but some ASCA SIS PHA datasets
.le
.ls cmpmode='BRIGHT2LINEAR'
- for use with ASCA SIS PHA datasets that have the non-linear bright
mode energy scale. By default, the current ASCA SIS data processing will 
go through event files that have the bright mode energy scale, while all
the response matrices have a linear energy scale. Running RBNPHA with
this option is therefore necessary for SIS spectral analysis. However,
PHA files produced with XSELECT 0.99 or later will have this compression
done by default, so you do not need to run RBNPHA outside XSELECT.
A more detailed description of each mode is provided below.

.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 for a
given compression factor F (calculated from the number of channels
requested by the user and the number of channels in the input PHA dataset),
the data within rows (channels) 1 to F of the original PHA dataset will
form row (channel) 1 of the new dataset, rows F+1 to 2*F of the old dataset
row 2 of the new dataset 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 PHA file constructed whilst the instrument was operating in 'BRIGHT'
datamode. The mode is designed to compensate for the fact that the SIS
spectra have only 2048 channels in this datamode (compared to 4096 channels
available within SIS 'FAINT' datamode) which is achieved by a non-linear
binning-up the data 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). For this cmpmode, RBNPHA calculates and
applies three separate compression factors (F1, F2 & F3) to the input
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 possible PHA channels in the input 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 file. Nout must therefore
be Nin/2 or smaller (by a factor divisible by 2) for RBNPHA to work in this
mode. The task thus compensates for (or linearizes) the on-board rebinning.
The net result is that the resultant PHA file has a linear
channel-numbering scheme, equivalent to that used by the 'FAINT' datamode.
Thus spectral analysis can be performed using this PHA file in conjunction
with a detector response matrix defined using the same linear
channel-numbering scheme. 
.le
.ls cmpmode='FAINT2BRIGHT'
This is a non-linear compression mode which should only be used on an ASCA
SIS PHA file constructed whilst the instrument was operating in 'FAINT'
datamode. The mode is designed to essentially perform the opposite task to
the 'BRIGHT2LINEAR' (see above). Again RBNPHA calculates and applies three
separate compression factors (B1, B2 & B3) to the input dataset 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 possible PHA channels in
the input file. 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 file. Nout must be Nin/2 or smaller (by a
factor divisible by 2) for RBNPHA to work in this mode. The task thus
compensates for (or linearizes) the The net result is that the resultant
PHA file has a NON-LINEAR channel-numbering scheme, equivalent to that used
by the 'BRIGHT' datamode. Thus spectral analysis can be performed using
this PHA file in conjunction with a detector response matrix defined using
the same non-linear channel-numbering scheme. 



.ih
WARNINGS ON USAGE

  Note NO checking of the quality flags in the original PHA dataset is
performed. RBNPHA should NOT be used as a replacement to GRPPHA.

  The non-linear compression modes available for use with ASCA SIS data
should be used with extreme care. These RBNPHA 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 good indication). Unfortunately, at the present time it is not possible
to provide software checks for such errors, and it is the responsibility of
the user to determine & pay attention to the channel-numbering scheme used
to construct the PHA & RMF files. 

.ih
SUPPORTED FITS FORMATS

  Currently only the following OGIP standards are supported by this task:
.ls HDUCLAS1/HDUVERS1 = 'SPECTRUM'/'1.*.*'
    (commonly also known as "PHAVERSN=1992a")
.le
.ls HDUCLAS2 = 'TOTAL'/'NET'/'BKG'
.le
.ls HDUCLAS3 = 'COUNT'/'RATE'
.le


.ih
PARAMETERS
.le
.ls infile [character string]
 The name of the FITS PHA file to be compressed 
.le 
.ls outfile [character string]
 The name of the FITS file to be written containing the compressed PHA dataset
.le
.ls (binfile=none) [character string]
 The name of the ascii file specifying the binning informations. The ascii file
should contain lines with three space-separated numbers : the start channel, then
end channel, and the compression factor for this channel range. e.g.
.br
.ce
 1 20 2
.ce
 21 30 5
.ju
where channels 1 to 20 are binned by a factor of 2 and 21 to 30 by a factor of 5.
If binfile is set then the finchan and cmpmode parameters are ignored.
.le
.ls (fchan=%) [character string]
 The option to define the output first channel no.  By default(%) it is same 
as input.
.le
.ls finchan [integer]
 The number of channels required in the compressed PHA 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 [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
BUGS
None known

.ih
SEE ALSO
.br
.nj
 Arnaud etal, 1992. Legacy, 2, 65 (OGIP/92-007)
.br
.nj
 The ftools/caltools task RBNRMF
.ju

.ih
LOG OF SIGNIFICANT CHANGES

.ls v1.0.0 (1993 JULY)
    Beta test version
.le
.ls v2.0.0 (1996 Mar)
    provision for binfile is added
.le
.ls v2.1.0 (1996 Nov)
    provision for fchan is added
.le


.ih
PRIMARY AUTHOR

.nj
Rehana Yusaf
.br
.nj
HEASARC
.br
.nj
NASA/GSFC
.br
.nj
http://heasarc.gsfc.nasa.gov/cgi-bin/ftoolshelp
.br
.nj
(301) 286-6115
.ju

.endhelp
