Source Files

Release Notes

RBNRMF (Oct06)               ftools.caltools              RBNRMF (Oct06)



NAME
    rbnrmf  --  Physically  compresses  (rebins)  an  RMF   dataset   in 
    channel-space and/or energy space.
    
    
USAGE
    rbnrmf infile [ebdfile] [binfile] [fchan] nchan cmpmode [ebinfile]
           [ebfact] outfile [chatter] [clobber]
    
    
DESCRIPTION
    
      RBNRMF  compresses  a  FITS RMF matrix (redistribution matrix file
    in an OGIP-standard format) in channel-space and/or energy-space
    to give a  user-defined number of resultant channels and energy
    bins. The output is a new file containing the  revised (compressed)
    MATRIX 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.
    
      The hidden parameter fchan allows the users 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.
    
    
    
    
CHANNEL COMPRESSION MODES
    
    The following modes of compression (only) are currently allowed
    when binning in channel-space :
    
    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.
        
ENERGY COMPRESSION

      Only linear binning is allowed when compressing in energy-space. 
    If the ebinfile parameter is set then this file is used to get the
    compression information otherwise a linear compression with binning 
    factor ebfact is performed.
        
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.
    
    
    
    
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.
    
    (binfile='NONE') [character string]
         The name of an ascii file specifying the channel 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 channel compression mode to be  used.  Currently the only
         values allowed are 'LINEAR', 'FAINT2BRIGHT' and 'BRIGHT2LINEAR'
         (see above), with 'LINEAR' as  the default.
    
    (ebinfile='NONE') [character string]
         The name of an ascii file specifying the energy binning 
        information. NOTE the default for this is NONE. If a filename is 
        specified then the parameter ebfact is not prompted for. The 
        ascii file format is identical to that given in the description 
        of the binfile parameter.

    (ebfact) [integer]
         The compression factor for energy binning. This must be a 
        divisor of the number of response energies in the input RMF.
        
    outfile [character string]
         The  name  of  the  FITS  file  to  be  written  containing the
        compressed RMF dataset
    
    (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
    
    2. Suppose my_file has 1024 channels and 2048 energy bins and we
       wish to bin up in energy space to give 1024 bins :

    ca> rbnrmf my_file.rmf 1024 linear compress.rmf ebfact=2
    
    
    
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
    
    v5.0.0 (2006 Oct)
             Added binning in energy space.
    
    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