NAME

ftrbnpha - Physically compresses (rebins) a PHA dataset in channel-space.

USAGE

ftrbnpha infile outfile [binfile] [phafile] finchan cmpmode properr error [clobber]

DESCRIPTION

FTRBNPHA 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 calculated as required by the properr and error parameters. 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).

The binning is either taken from a text file (binfile parameter), the grouping column from a pha file (phafile parameter), or using one of the compression modes (cmpmode parameter).

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, FTRBNPHA 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 FTRBNPHA 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 FTRBNPHA 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 FTRBNPHA 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.

ERROR CALCULATION

There are a number of options for calculating the statistical error for each bin. If properr=yes then the statistical error is the sum in quadrature of the statistical errors of the constituent channels. If properr=no then the error of the bin is calculated depending on the value of the error parameter. If error=gauss then the error is calculated as 1/sqrt(pha); if error=poiss-0 then no error is calculated and the POISSERR keyword is set to true; if error=poiss-1 then the error in counts is 1+sqrt(N+0.75) where N is the number of counts in the bin; if error=poiss-2 then the error is sqrt(N-0.25); and if error=poiss-3 then the error is the arithmetic mean of poiss-1 and poiss-2. Except in unusual circumstances the only options used should be properr=yes or properr=no and error=poiss-0.

WARNINGS ON USAGE

The non-linear compression modes available for use with ASCA SIS data should be used with extreme care. These FTRBNPHA modes are only required if users wish to perform spectral analysis on a PHA dataset taken in one on-board datamode in conjunction 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.

PARAMETERS

infile [filename]
The name of the FITS PHA file to be compressed

outfile [filename]
The name of the FITS file to be written containing the compressed PHA dataset

binfile [filename]
The name of the text file specifying the binning informations. The text 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.

phafile [filename]
The name of the pha file to be read to get a grouping vector which will be used to define the binning. This filename can be the same as infile. If it is not then it must have the same number of channels.

finchan [int]
The number of channels required in the compressed PHA dataset

cmpmode [string]
The compression mode to be used. Currently the only values allowed are 'LINEAR', 'FAINT2BRIGHT' and 'BRIGHT2LINEAR' (see above), with 'LINEAR' as the default.

properr [bool]
If properr = yes then sum errors in quadrature to get error of bin.
error [string]
If properr = no then the error parameter specifies how to calculate the error. The allowed values are 'GAUSS', 'POISS-0', 'POISS-1', 'POISS-2', and 'POISS-3'. The default (and strong recommendation) is 'POISS-0'.
clobber [bool]
If clobber = yes then overwrite the output file if a file of this name already exists.

EXAMPLES

1. Bin by a constant factor

ftrbnpha infile=file1.pha outfile=fileout.pha finchan=512 cmpmode=linear properr=no error=poiss-0
2. Bin by factors in input file

ftrbnpha infile=file1.pha outfile=fileout.pha binfile=binning.txt properr=no error=poiss-0
3. Do ASCA BRIGHT to LINEAR mode binning

ftrbnpha infile=ascabright.pha outfile=fileout.pha finchan=512 cmpmode=bright2linear properr=no error=poiss-0
4. Propagate errors

ftrbnpha infile=file1.pha outfile=fileout.pha finchan=32 cmpmode=linear properr=yes
5. Rebin using the grouping information in pha file

ftrbnpha infile=file1.pha outfile=fileout.pha phafile=file2.pha properr=no error=poiss-0

SEE ALSO

LAST MODIFIED

Jan 2022