Source Files

Release Notes

RSP2RMF (Mar94)              ftools.caltools             RSP2RMF (Mar94)



NAME
    rsp2rmf  -- converts old-style (SF) format response matrices to OGIP
    FITS format
    
    
USAGE
    rsp2rmf rspfil rmffil
    
    
DESCRIPTION
    
      rsp2rmf reads i/p data  from  an  old-stle  (SF)  format  response
    matrix  (used  by  XSPEC versions <8.2), and writes an o/p FITS data
    file in OGIP standard format (able to  be  read  by  XSPEC  versions
    >8.2).  Users  are urged to switch to using XSPEC with FITS files as
    soon as possible.
    
       A detailed description of the o/p FITS file format  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   (in   Postscript)   as  
    caldb/docs/memos/cal_gen_92_002.ps       &        cal_gen_92_002a.ps      
    respectively.  In  brief,  the  data  is  written  in  the form of 2
    BINTABLE extensions, containing:
    
    (1) the redistribution matrix 
                (with EXTNAME = SPECRESP MATRIX)
    
    (2) the nominal energies of the channel boundaries 
                (with EXTNAME = 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,  but  can be altered via the hidden parameters gregrp and
    threshold parameters. Users  are  reminded  that  the  threshold  is
    defined  in absolute units (NOT relative to the value of the maximum
    value in the matrix).
    
      A further reduction in disk-storage space requirements  can  often
    be  achieved  by  the  use  a variable-length array for the BINTABLE
    column containing  the  matrix.  In  such  a  case,  the  number  of
    elements  within  this  column  varies between different rows of the
    BINTABLE. The current version of rsp2rmf will automatically write  a
    variable-length  array  if  a  saving  of greater than a factor 3 in
    storage space is indeed achieved.
    
    
    
SUPPORTED FITS FILE FORMATS
    
       Currently only the following  OGIP  standards  are  supported  by
    this task (via the parameter rmfversn):
    
    For the RSP_MATRIX extension:
        HDUCLAS1/HDUVERS1= 'RESPONSE'/'1.0.0'
        
        HDUCLAS2/HDUVERS2= 'RSP_MATRIX'/'1.0.1'
                (commonly also known as "RMFVERSN=1992a")
    
    For the EBOUNDS extension:
        HDUCLAS1/HDUVERS1= 'RESPONSE'/'1.0.0'
        
        HDUCLAS2/HDUVERS2= 'EBOUNDS'/'1.0.1'
    
    For further details see OGIP Calibration Memo CAL/GEN/92-002a.
    
    
    
WARNINGS ON USAGE
    
      The  current version of this task assumes that the matrix elements
    of the input SF file  have  already  been  multipled  by  the  total
    effective  area  of  the  focussing/collimating  optics,  filters  & 
    detector efficiency (since this  is  the  case  for  all  RSP  files
    currently  available  within  the  OGIP).  Thus  the  redistribution 
    matrix extension has the keyword HDUCLAS3=  'FULL'.  This  value  of
    HDUCLAS3  is  however  incorrect  in  cases where the redistribution
    matrix alone is  stored,  and  hence  the  values  of  the  HDUCLAS3
    keyword  of  the  output  file  should be changed appropriately (see
    calibration memo OGIP/92-002a)
    
      Users are reminded that the EBOUNDS extension  contains  only  the
    nominal  energies  associated with each PHA/PI channel. Extreme care
    should be exercised if these are to be used by  downstream  software
    (see   George   etal   1992   Legacy,   2,  51,  section  3.2).  The 
    OGIP-supplied spectral fitting package, XSPEC, only  uses  the  data
    within this extension for plotting purposes.
    
      The  facility  to  override  the  deconvolution of the mission and
    instrument strings derived from the  corresponding  string  supplied
    in  the  SF  file  is  often  useful  since  the strings required to
    specify for which mission, instrument, detector  and/or  filter  the
    dataset  is valid in the case of the output FITS file are often very
    different to those used in the SF file.  Specifically,  the  SF  RSP
    files  often  contain non-OGIP-standard strings, and/or insufficient
    information. A list of OGIP-standard strings can  be  found  in  the
    OGIP  Memos OGIP/93-013 available via the OGIP anonymous ftp account
    on       legacy.gsfc.nasa.gov       (in        Postscript)        as      
    caldb/docs/memos/ogip_93_013.ps.   The  current  version of the task
    only performs a rather crude deconvolution.
    
      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 largest matrix able to be handled by the current version of
    this task is 4096 channels by 2048 energies (requiring 35 Mbytes of
    swap space). Due to dynamic memory allocation, the swap space
    requirements of most matrices are dramatically smaller.
    
    
    
    
PARAMETERS
    
    rspfil [character string]
         The name of the old-style (SF) RSP  file  to  be  converted  to
        OGIP-standard  FITS format.
    
    rmffil [character string]
         The name of the OGIP-standard FITS file to be created
    
    (origin = 'UNKNOWN') [character string] 
         The  name  of  the organization and/or author running the task.
         The default value is ORIGIN=UNKNOWN.
    
    (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.
    
    (qregrp = no) [boolean] 
         Logical as to whether the matrix read in from the RSP  file  is
        to  be   truncated  at a higher threshold, or simply written out
        to the FITS  file with the current  threshold.  The  default  is
        QREGRP=N.
    
    threshold [real]
         New  threshold  at  which  the matrix is to be truncated  (only
        required if QREGRP=Y)
    
    (qcif = no) [boolean] 
         Logical as to whether the CIF keywords are to be added  to  the
        FITS   file.  The default is QCIF=N.   NOTE: NO ALTERNATIVES ARE
        CURRENTLY ALLOWED
    
    (rmfversn = '1.1.0') [charcter string]
         The OGIP FITS format version for  response  matrices  in  which
        the   o/p  FITS  is  to be writen. The default is RMFVERSN=1.1.0
        (previously  known as '1992a'), and is currently to only  format
        allowed.
    
    (qrmfcomm = no) [boolean] 
         Logical  indicating whether comments are to be added to the RMF
        extension  from  a  previously  prepared  ASCII  i/p  file.  The
        default  is  QRMFCOMM=N.    NOTE:  NO ALTERNATIVES ARE CURRENTLY
        ALLOWED
    
    (qebdcomm = no) [boolean] 
         Logical indicating whether comments are  to  be  added  to  the
        EBOUNDS  extension   from  a previously prepared ASCII i/p file.
        The  default  is  QEBDCOMM=N.    NOTE:   NO   ALTERNATIVES   ARE 
        CURRENTLY ALLOWED
    
    (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 RSP 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
    
    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.
    
    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.
    
    (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
    CAL/GEN/92-002 (George etal 1992 Legacy, 2, 51),
    CAL/GEN/92-002a
    
    
    
LOG OF SIGNIFICANT CHANGES
    
    
    v3.1.0 (1994 Jun)
            Improved dynamic memory allocation to minimize requirements
    
    v3.0.0 (1994 Mar)
            Added dynamic memory allocation
    
    v2.0.0 (1993 Aug)
            Added variable length arrays for RSP_MATRIX extension
    
    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