S-Lang function to read a Redistribution Matrix File (RMF)
Struct_Type readrmf( filename )
Error Return Value: NULL
Argument:
filename is a String_Type variable
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" )
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:
| _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]
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]
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.
The routines no longer crash when reading a file
within a directory whose name contains
the string "::".
There are now separate ahelp files for the individual
functions, rather than having all the information
placed into this document.
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 );
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".
|
![[CIAO Logo]](../imgs/ciao_logo_navbar.gif){kind=logo}