Source Files

Release Notes

MARFRMF (Apr95)              ftools.caltools             MARFRMF (Apr95)



NAME
    marfrmf  --  multiplies/divides  a detector redistribution matrix by
    an ancillary response dataset or a scalar
    
    
USAGE
    marfrmf  rmfil[ext#]  (ebfil[ext#])  arfil[ext#]  outfil  (rmfversn) 
    (qoverride)           telescop   instrume  filter  detnam  (chatter) 
    (clobber) scalar (qdivide) (arfcol)
    
    
DESCRIPTION
    
      A detector redistribution matrix (aka 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. An
    ancillary response dataset is a 1-dimensional array  as  a  function
    of  incident  photon  energy (containing, for example, the effective
    area of  the  optics,  corrections  for  the  spatial  point  spread
    function  etc).  Provided  the  input  files are in an OGIP-approved
    FITS format,  this  task  provides  the  facility  to  multiply  the
    redistribution  array  for  each  channel (along the incident energy
    dimension) by the ancillary response array.  The output  is  thus  a
    new FITS 'RMF' file containing the new redistribution matrix.
    
       A  detailed  description  of  the  both  the  i/p & o/p FITS file
    formats is given in George etal (1992 Legacy, 2,  51),  and  in  the
    OGIP  Calibration  Memos  CAL/GEN/92-002 & CAL/GEN/92-002a available
    via the OGIP anonymous  ftp  account  on  legacy.gsfc.nasa.gov  (see
    caldb/docs/memos/README).In  brief,  the o/p file consists of a FITS
    file with 2 BINTABLE extensions  (both  of  which  have  HDUCLAS1  =
    RESPONSE), containing:
    
    (1)  the redistribution matrix
                (with HDUCLAS2 = RSP_MATRIX)
    
    (2) the nominal energies of the channel boundaries,
                 (with HDUCLAS2 = EBOUNDS)
    
      The  data  contained  in  Extension  (1)  above is in a compressed
    format  whereby  only  elements  for  which   the   value   of   the 
    redistribution  matrix  above  a  given  threshold  are stored. This
    provides a significant reduction in  disk-storage  requirements  for
    sparsely  populated matrices. The default threshold is read from the
    i/p file. Users are  reminded  that  the  threshold  is  defined  in
    absolute  units  (NOT  relative to the value of the maximum value in
    the matrix).
   
PARAMETERS
    
    rmfil [character string]
         The  name  of  the  RMF  file containing the i/p redistribution
        matrix  (and extension number in square brackets)  to  be  used.
        If  no  extension   number  is  specified,  or  an  asterisk  is 
        supplied for the extension number,  then all extensions  in  the
        FITS   file  will  searched  for  an  extension   containing  an 
        RSP_MATRIX dataset,  and  (assuming  only  one  is  found)  that
         extension used.
    
    (ebfil = '%') [character string]
         The  name  of  the file containing the i/p EBOUNDS dataset (and
        extension   number  in  square  brackets)  to  be  used.  If  no 
        extension  number  is specified,  or an asterisk is supplied for
        the extension number, then all  extensions  in   the  FITS  file
        will  searched  for  an extension containing an EBOUNDS dataset,
         and (assuming only one is found)  that  extension  used.  Since
        the  EBOUNDS   extension  corresponding  to  a  given RSP_MATRIX
        usually resides in  the  same   file  as  the  RSP_MATRIX,  this
        parameter  is  HIDDEN  with  the  default  value   "ebfil  =  %" 
        indicating that the rmfil will be used.
    
    arfil [chracter string]
         The name of the  ARF  file  (and  extension  number  in  square
        brackets)  containing   the  ancillary spectral response dataset
        with  which  the   i/p   redistribution    matrix   is   to   be 
        multiplied/divided.  If no extension number is specified, or  an
        asterisk  is  supplied  for  the  extension  number,  then   all 
        extensions  in  the   FITS  file  will searched for an extension
        containing an SPECRESP  dataset,   and  (assuming  only  one  is
        found)  that  extension used. If a value of 'NONE',  'none' or '
        ' is entered the user will be prompted for the scalar value   by
        which   the   the   i/p   redistribution   dataset   is   to  be 
        multiplied/divided.
    
    outfil [character string]
         The name of the RMF file to be created. For  safety,  the  name
        of  the  o/p   file  CANNOT be the same as one of the i/p files,
        and the task will stop  if this is the case. Under  unix/ultrix,
        an  o/p  filename  identical  to a  file which already exists on
        disk is also  considered  illegal,  and  the   task  will  stop.
        However,  the  existing  file can be automatically removed,  and
        the new file written if the o/p filename is preceeded by "!"  at
         the outfil prompt.
    
    (rmfversn) [character string]
         The  OGIP  FITS  format  version for RMF files in which the o/p
        FITS  is  to  be   written.
    
    (qoverride = no) [boolean]
         Logical indicating whether the  user  wishes  to  override  the
        deconvolution   of  the  mission  and instrument strings derived
        from the corresponding  string supplied in the SF file. This  is
        often  necessary  since  the  task  only performs a rather crude
        deconvolution itself and since  the  RSP   file  often  contains
        non-OGIP-standard   strings,  and/or  insufficient  information. 
         The default is QOVERRIDE=N
    
    telescop [character string]
         The user-supplied string for the telescope  name,  required  if
        QOVERRIDE=Y
    
    instrume [character string]
         The  user-supplied  string for the instrument name, required if
        QOVERRIDE=Y
    
    filter [character string]
         The user-supplied string for the name of  any  moveable  filter
        in  use,   required if QOVERRIDE=Y.   FILTER=NONE should be used
        if on such moveable filter is in use.
    
    detnam  [character string]
         The user-supplied string for the sub-instrument name,  required
        if   QOVERRIDE=Y.     DETNAM=NONE   should   be   used   if  the 
        specification of a sub-instrument is  unneccessary.
    
    (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.
    
    scalar [real]
         Scalar value by which the  RSP_MATRIX  dataset  is  divided  or
        multiplied.    This  parameter is only used when arfil = 'NONE',
        'none' or ' ' is  entered.
    
    (qdivide = no) [boolean]
         Flag to indicate whether  the  RSP_MATRIX  dataset  is  DIVIDED
        (qdivide  =  yes)   or MULTIPLIED (qdivide = no) by the SPECRESP
        dataset/scalar.

    (arfcol = 'SPECRESP') [character string]
         The column name to use to read the ARF data. SPECRESP is the
         standard but this parameter allows another column to be read 
         if necessary.
 
    
BUGS
    None known
    
    
    
SEE ALSO
    CAL/GEN/92-002 (George etal 1992 Legacy, 2, 51),
    CAL/GEN/92-002a
    
    
    
LOG OF SIGNIFICANT CHANGES

    v3.2.6 (2005 Jul)
            Added arfcol parameter
        
    v2.2.0 (1995 Apr)
            Added scalar & qdivide parameters
    
    v2.0.0 (1993 Aug)
            Added dynamic memory allocation
    
    v1.0.0 (1992 Oct)
            Beta-test version
    
    
    
PRIMARY AUTHOR
    
    Ian M George
    HEASARC
    NASA/GFSC
    http://heasarc.gsfc.nasa.gov/cgi-bin/ftoolshelp
    (301) 286-6094