About Chandra Archive Proposer Instruments & Calibration Newsletters Data Analysis HelpDesk Calibration Database NASA Archives & Centers Chandra Science Links

Skip the navigation links
Last modified: December 2006

URL: http://cxc.harvard.edu/ciao3.4/readrmf.html
Hardcopy (PDF): A4 | Letter
AHELP for CIAO 3.4 readrmf Context: varmm

Synopsis

S-Lang function to read a Redistribution Matrix File (RMF)

Syntax

Struct_Type readrmf( filename )

Error Return Value: NULL

Argument:
filename is a String_Type variable

Description

The readrmf() function provides a high-level interface to reading in a Redistribution Matric File (ARF) from a FITS binary table that follows the relevant OGIP standard. The ahelp page for readfile describes the features of this routine that are common to all the "read" functions provided by the Varmm module. This page describes those features that are unique to the readrmf() command.

The filename argument should be a string that contains the name of the file to be read in. Although it can include Data-Model filters it is best not to use them when reading in RMF, since any filter may well remove needed information from the file. As an example of how the function is used:

  chips> rmf = readrmf( "src.rmf" )

What does the function return?

The function returns a structure whose fields contain the data read in from the file. If an error occurred - such as the file not being found, or it does not contain a RMF - then NULL is returned instead. The returned structure follows the format of the other "read" functions: metadata - i.e. information about the file - is stored in fields beginning with an underscore character followed by fields containing the image data and coordinate-transformation information. The initial fields are discussed in "ahelp readfile"; here we concentrate on those fields specific to RMFs.

Fields specific to RMFs:

Field name: Description:
_ncols Gives the number of arrays in the structure.
_nrows Gives the number of rows read from the RMF.
elow The minimum energy of each bin.
ehigh The maximum energy of each bin.
numgroups The number of 'channel subsets' for each energy bin.
fchans This array lists the start position for each 'channel subset'. The length of this array equals the sum of the numgroups array.
numchans This array lists the number of channels within each 'channel subset' given by the fchans array.
response This one-dimensional array stores the values of the redistribution matrix.
eboundsmin The approximate minimum energy for each channel (PI or PHA depending on the type of the RMF).
eboundsmax The approximate maximum energy for each channel (PI or PHA depending on the type of the RMF).

For example:

  _filename        =  src.rmf
  _path            =  /data/analysis/
  _filter          =  NULL
  _filetype        =  10
  _header          =  NULL
  _ncols           =  8
  _nrows           =  1090
  elow             =  Float_Type[1090]
  ehigh            =  Float_Type[1090]
  numgroups        =  Short_Type[1090]
  fchans           =  Short_Type[1094]
  numchans         =  Short_Type[1094]
  response         =  Float_Type[453356]
  eboundsmin       =  Float_Type[1024]
  eboundsmax       =  Float_Type[1024]

Example

Reading in a RMF using readrmf()

  chips> rmf = readrmf("source.rmf") 
  chips> print( rmf )
  _filename        =  source.wrmf
  _path            =  /data/analysis/
  _filter          =  NULL
  _filetype        =  10
  _header          =  NULL
  _ncols           =  8
  _nrows           =  880
  elow             =  Float_Type[880]
  ehigh            =  Float_Type[880]
  numgroups        =  Short_Type[880]
  fchans           =  Short_Type[887]
  numchans         =  Short_Type[887]
  response         =  Float_Type[304629]
  eboundsmin       =  Float_Type[1024]
  eboundsmax       =  Float_Type[1024]

FORMAT OF THE RESPONSE MATRIX

The OGIP standard requires that the redistrbution matrix be stored in a compressed form, where all elements in the matrix with a value below a given threshold (which is stored in the file header as the LO_THRES keyword). The structure returned by readrmf() uses a slightly-more efficient scheme for representing this data, which closely matches the OGIP notation. The difference is that the F_CHAN, N_CHAN, and MATRIX vector arrays are converted to scalar arrays called fchans, numchans, and response.

The fchans and numchans arrays are created by converting the F_CHAN and N_CHAN vectors into one-dimensional arrays and then removing all the elements whose value is 0.

The response array is created by taking the MATRIX vector and converting to one dimension after removing all the empty values. Its length is therefore given by the sum of the elements in the numchans array.

CHANGES IN CIAO 3.1

Reading a file in a directory containing the string '::'

The routines no longer crash when reading a file within a directory whose name contains the string "::".

Enhanced documentation

There are now separate ahelp files for the individual functions, rather than having all the information placed into this document.

CHANGES IN CIAO 3.0.2

Stack Underflow errors

It is now possible to use readfile() - or any of the other read functions described here - in an if statement. Prior to CIAO 3.0.2 you could not write something like

  if ( NULL == readfile("evt2.fits") ) error("Failed to read file.");

since it would result in a "Stack Underflow" error message. This means that many routines that use readfile() - such as Sherpa's load_dataset() and related functions - can also now be used in an if statement such as:

  if ( 1 != load_image(imgname) )
    verror( "Unable to load %s as an image.", imgname );

CHANGES IN CIAO 3.0

New field "_filetype"

A new field called "_filetype" has been added to the data structure which describes the type of the file read in. The contents of the field are described in the "Format of data structure" section in "ahelp readfile".

Bugs

See the bugs page for the Varmm library on the CIAO website for an up-to-date listing of known bugs.

Hardcopy (PDF): A4 | Letter
Last modified: December 2006



The Chandra X-Ray Center (CXC) is operated for NASA by the Smithsonian Astrophysical Observatory.
60 Garden Street, Cambridge, MA 02138 USA.    Email: cxcweb@head.cfa.harvard.edu
Smithsonian Institution, Copyright © 1998-2004. All rights reserved.