Source Files

Release Notes

GCORRMF (Aug95)              ftools.caltools             GCORRMF (Aug95)



NAME
    gcorrmf -- remaps a detector redistribution matrix in channel-space.
    
    
USAGE
    gcorrmf infile shftfile outfile
    
    
DESCRIPTION
    
    This task remaps a detector redistribution matrix in  channel-space.
    IT  SHOULD  ONLY  BE  USED  IF  ONE  KNOWS  WHAT ONE IS DOING, or AS
    INSTRUCTED  by  the  relevant  guest  investigator   facility.   The 
    incorrect   use   of  this  task  ,  or  without  understanding  the 
    implications will result in  errorneous  results  during  subsequent
    spectral analysis.
    
    A  detector  redistribution  matrix  (aka  detector response matrix)
    basically consists of a 2-dimensional  array  (detector  channel  vs
    incident  photon  energy)  giving  the  probability that an incident
    photon of a given energy  will  be  detected  in  a  given  detector
    channel.  For  the following discussion it is useful to think of the
    matrix as a column  of  values  (probability  for  various  incident
    photon energies) for each detector channel.
    
    Given  an  OGIP-approved  FITS format input file, this task provides
    the facility to move the  user-defined  elements  (columns)  of  the
    array  to  the  left  or right (ie down or up in channel-space) by a
    user-defined number of channels.  It  is  difficult  to  generalise,
    but  such  a  facility  may  be  useful  for  converting  a detector
    redistribution matrix constructed for a given (standard) gain  of  a
    detector  to  the  gain actually applicable to an observation.Again,
    if you have no idea what we're talking  about  here,  and  have  not
    been  explicitly  instructed  to  use  this  task,  then we strongly
    recommend you seek further advice.
    
    The shift to  be  applied  to  each  channel  of  the  i/p  detector
    redistribution  matrix  must  be specified by an ASCII i/p file. The
    format of each row of this i/p ASCII file must be
                           MINCHAN MAXCHAN NCHAN
    denoting all 'columns' of the  i/p  detector  redistribution  matrix
    between  detector channels MINCHAN and MAXCHAN (inclusive) are to be
    shifted by NCHAN. The shift, NCHAN, can be  any REAL value,  thereby
    supporting  positive,  negative, and  fractional channel shifts. Any
    channel ranges "implied" by their  exclusion  from  the  ASCII  file
    will  be  shifted  by  zero  channels.  Note  that  should the shift
    applied to two or more 'columns' result in those  columns  being  in
    the  same  o/p detector channel, then their respective probabilities
    (that an incident photon of a given energy will be detected in  that
    detector  channel)  WILL  BE  SUMMED.  Similarly, should the applied
    shifts  result  in  an  o/p  detector  channel  'column'  NOT  being 
    populated,  then the probability (that an incident photon of a given
    energy will be detected in that detector channel)  will  be  set  to
    zero.   However,  shifts  below  the  minimum, and above the maximum
    legal channel  number  for  the  instrument  will  result  in  those
    probabilities being excluded.
    
    
LIMITATONS ON USE
    
    Users  should be aware that, at the current time, this task does NOT
    alter the EBOUNDS  extension  of  the  i/p  detector  redistribution
    matrix.  This may be formally incorrect under certain circumstances,
    but the error introduced will not  effect  spectral  analysis  using
    XSPEC, and is minimal under most circumstances.
    
    
WARNINGS ON USAGE
    
    This  task remaps a detector redistribution matrix in channel-space.
    It should only be used if  one  knows  what  one  is  doing,  or  as
    instructed  by  the relevant guest investigator facility. The use of
    this task incorrectly, or  without  understanding  the  implications
    WILL   RESULT   IN  INCORRECT  RESULTS  DURING  SUBSEQUENT  SPECTRAL 
    ANALYSIS.
    
      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'.
    The (approx) swap space required by the current version of this
    task: 21 Mbyte
    
    
    
SUPPORTED FITS FILE FORMATS
    
       Currently only the following  OGIP  standards  are  supported  by
    this task
    
    For the RSP_MATRIX extension:
        HDUCLAS1/HDUVERS1= 'RESPONSE'/'1.0.0'
        
        HDUCLAS2/HDUVERS2= 'RSP_MATRIX'/'1.1.0'
                (commonly also known as "RMFVERSN=1992a")
    
    For the EBOUNDS extension:
        HDUCLAS1/HDUVERS1= 'RESPONSE'/'1.0.0'
        
        HDUCLAS2/HDUVERS2= 'EBOUNDS'/'1.1.0'
    
    For further details see OGIP Calibration Memo CAL/GEN/92-002a.
    
    
    
PARAMETERS
    
    infile [character string]
         The name of the FITS RMF file to be remapped in channel-space
    
    (ebdfile="%") [character string]
         The  name  of  the  FITS  EBOUNDS  file,  this  is  usually  an 
        extension in the  rmf file, therefore this is the default.
    
    outfile [character string]
         The name  of  the  FITS  file  to  be  written  containing  the
        remapped RMF dataset
    
    shftfile [character string]
         The   name   of   an   ascii   file  specifying  the  remapping 
        information. The ascii  file format should be of the form :
                                     1 20 -1
                                     21 30 0
         where channels 1 to 20 are shifted back by one, and  21  to  30
        stay as they are.
    
    (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 remap the channel-space in "my_file.rmf" to obtain a new file
       with remapped matrix, "remap.rmf" by  using  a  file,  "shft.txt"
    containing    the remapping info:
    
    ca> gcorrmf my_file.rmf remap.rmf shft.txt
    
    
    
BUGS
    None known
    
    
    
SEE ALSO
    CAL/GEN/92-002 (George etal 1992 Legacy, 2, 51),
    CAL/GEN/92-002a
    
    
LOG OF SIGNIFICANT CHANGES
    
    
    v1.0.0 (1995 Aug)
            Initial public release
    
    v1.2.0 (1996 Aug)
            Fractional shifts added
    
    
PRIMARY AUTHOR
    
    Rehana Yusaf
    HEASARC
    NASA/GFSC
    http://heasarc.gsfc.nasa.gov/cgi-bin/ftoolshelp
    (301) 286-6115