RBNPHA (April94) ftools.heasarc RBNPHA (April94) NAME rbnpha -- Physically compresses (rebins) a PHA dataset in channel-space. USAGE rbnpha infile outfile fchan finchan cmpmode 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. cmpmode='LINEAR' - only mode applicable for all but some ASCA SIS PHA datasets 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. 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 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. 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. 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. 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. SUPPORTED FITS FORMATS Currently only the following OGIP standards are supported by this task: HDUCLAS1/HDUVERS1 = 'SPECTRUM'/'1.*.*' (commonly also known as "PHAVERSN=1992a") HDUCLAS2 = 'TOTAL'/'NET'/'BKG' HDUCLAS3 = 'COUNT'/'RATE' PARAMETERS infile [character string] The name of the FITS PHA file to be compressed outfile [character string] The name of the FITS file to be written containing the compressed PHA dataset (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. 1 20 2 21 30 5 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. (fchan=%) [character string] The option to define the output first channel no. By default(%) it is same as input. finchan [integer] The number of channels required in the compressed PHA 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 [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. BUGS None known SEE ALSO Arnaud etal, 1992. Legacy, 2, 65 (OGIP/92-007) The ftools/caltools task RBNRMF LOG OF SIGNIFICANT CHANGES v1.0.0 (1993 JULY) Beta test version v2.0.0 (1996 Mar) provision for binfile is added v2.1.0 (1996 Nov) provision for fchan is added PRIMARY AUTHOR Rehana Yusaf HEASARC NASA/GSFC http://heasarc.gsfc.nasa.gov/cgi-bin/ftoolshelp (301) 286-6115