Heasp_guide.dvi Heasp Guide
User Manual:
Open the PDF directly: View PDF 
.
Page Count: 47
| Download | |
| Open PDF In Browser | View PDF |
HEASP Guide
Version 1.0
Keith A. Arnaud
HEASARC
Code 662
Goddard Space Flight Center
Greenbelt, MD 20771
USA
Mar 2012
Contents
1 Introduction
3
2 Python module
5
2.1
Getting started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5
2.2
HEASP features not (yet) supported in Python . . . . . . . . . . . . . . . . . . . . .
6
2.3
Spectrum example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6
2.4
Response example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7
2.5
Table model example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7
3 C++ classes and methods
3.1
3.2
11
Spectra . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
3.1.1
Introduction and example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
3.1.2
pha class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
3.1.3
pha class public methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
3.1.4
Other pha routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
3.1.5
phaII class
3.1.6
phaII class public methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
3.2.1
Introduction and example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
3.2.2
rmf class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
3.2.3
rmf class public methods
3.2.4
Other rmf routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
3.2.5
rmft class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
3.2.6
rmft class public methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
3.2.7
arf class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
i
CONTENTS
1
3.2.8
arf class public methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
3.2.9
Other arf routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
3.2.10 arfII class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
3.2.11 arfII class public methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
3.3
3.4
3.5
Table Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
3.3.1
Introduction and example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
3.3.2
table classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Grouping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
3.4.1
grouping class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
3.4.2
grouping class public methods . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
3.4.3
Other grouping routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Utility routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
4 C interface
4.1
4.2
4.3
4.4
35
PHA files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
4.1.1
PHA structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
4.1.2
PHA routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
RMF files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
4.2.1
RMF structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
4.2.2
RMF routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
ARF files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
4.3.1
ARF structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
4.3.2
ARF routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Binning and utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
4.4.1
BinFactors structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
4.4.2
Binning and utility routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
A Ftools and Heasp
43
B Error Codes
45
2
CONTENTS
Chapter 1
Introduction
HEASP is a C/C++/Python library to manipulate files associated with high energy astrophysics
spectroscopic analysis. Currently this handles PHA, RMF, ARF and xspec table model files. The
eventual plan is to be able to provide at least the functionality available in current ftools but from
a single library.
The main code is written in C++ with classes for each file type. These classes and associated
methods have been run through SWIG to produce Python code. C wrappers are provided for
many of the C++ methods allowing simple use from C programs.
These C wrappers are compatible with an earlier C only version of HEASP with two exceptions: a)
the include file required is now Cheasp.h instead of heasp.h; b) all routines which used to require a
FITS file pointer now just require the filename. One consequence of b) is that files no longer need
to be opened and closed by the calling program.
There are separate chapters describing the Python, C++, and C interfaces although users of Python
should consult the C++ chapter for description of the classes.
Highlights of HEASP are :
• Read and write spectra, responses, arfs and table model files.
• Rebin spectra using grouping arrays.
• Compress responses by removing all elements below some value. Rebin responses in either
energy or channel space based on a grouping array.
• Use a response to generate random channel numbers for a photon of a given energy.
• Sum both rmfs and arfs and multiply rmfs by arfs.
• Construct type II PHA or ARF from sets of spectra or arfs. Also extract individual spectra
or arfs from type II files.
3
4
CHAPTER 1. INTRODUCTION
Chapter 2
Python module
2.1
Getting started
The standard HEAsoft build makes a Python module based on the HEASP C++ classes described
in the next chapter. The standard HEAsoft initialization script adds the location of the HEASP
Python module to PYTHONPATH. To load the module use
UNIX> python
>>>from heasp import *
If this produces name conflicts then loading the module by
UNIX> python
>>>import heasp
requires heasp. in front of all commands.
To set up an HEASP object first give a simple command such as
>>>sp = pha()
for a spectrum. This can then be read in and information about it displayed by
>>>sp.read("file1.pha")
>>>sp.disp()
Individual components of the object can be used by adding the component name to the object
name without “()”. For instance:
>>>first = sp.FirstChannel
5
6
CHAPTER 2. PYTHON MODULE
will place the first channel number in the variable first. The components of each class are given in
the C++ chapter.
Components which are arrays can be used only through their individual element numbers. For
instance:
>>>counts = []
>>>for i in xrange(sp.NumberChannels()):
...
counts.append(sp.Pha[i])
will place the contents of the PHA column in the list called counts. Going the other way, the
current contents of the PHA column can be replaced by those in the counts list by:
>>>for i in xrange(sp.NumberChannels()):
...
sp.Pha[i] = counts[i]
2.2
HEASP features not (yet) supported in Python
At present the HEASP Python module does not support binary operations defined in the C++
classes such as the addition of two responses by resp = resp1 + resp2. What are supported are the
unary equivalents so responses can be added by resp1 += resp2.
2.3
Spectrum example
The following Python example reads a type II PHA file, rebins the channels in each spectrum by
a factor of 2 and writes out the result.
# read the spectrum
spectra = phaII()
spectra.read("testin.pha")
# loop round the spectra in the file
# rebinning by a factor of 2 then placing
# in the output spectra
output = phaII()
Nspectra = spectra.NumberSpectra()
groupInfo = grouping()
for i in xrange(Nspectra):
spectrum = spectra.get(i)
groupInfo.load(2,spectrum.NumberChannels())
status = spectrum.rebinChannels(groupInfo)
output.push(spectrum)
2.4. RESPONSE EXAMPLE
7
# write out the spectrum copying any extra keywords and extensions
# from testin.pha
output.write("testout.pha", "testin.pha")
2.4
Response example
The following Python example reads RMF and ARF files, removes all elements smaller than 10−6
from the RMF, multiplies the compressed RMF and the ARF, and writes out the result.
# read RMF and ARF
inputRMF = rmf()
inputRMF.read("testin.rmf")
inputARF = arf()
inputARF.read("testin.arf")
# compress the RMF
inputRMF.compress(1.0e-6)
# if the RMF and ARF are compatible then multiply them and write
# the result adding extra keywords and extensions from testin.rmf.
if inputRMF.checkCompatibility(inputARF):
inputRMF *= inputARF
inputRMF.write("testout.rsp", "testin.rmf")
2.5
Table model example
The following Python example sets up a table model grid with two parameters and one additional
parameter (for instance abundance). The parameters, energies and fluxes are given arbitrary values,
in practice these could be read from text files.
test = table()
# set table descriptors and the energy array
test.ModelName = "Test"
test.ModelUnits = " "
test.isRedshift = True
test.isAdditive = True
test.isError = False
# set up the energies. note that the size is one greater
# than that of the array for the model fluxes
8
CHAPTER 2. PYTHON MODULE
for i in xrange(100): test.Energies.append(0.1+i*0.1)
test.NumIntParams = 2
test.NumAddParams = 1
# define first parameter and give it 11 values ranging from
# 0.0 to 2.0 in steps of 0.2.
testpar = tableParameter()
testpar.Name = "param1"
testpar.InterpolationMethod = 0
testpar.InitialValue = 1.0
testpar.Delta = 0.1
testpar.Minimum = 0.0
testpar.Bottom = 0.0
testpar.Top = 2.0
testpar.Maximum = 2.0
for i in xrange(11): testpar.TabulatedValues.append(0.2*i)
# and push it onto the vector of parameters
test.pushParameter(testpar)
# define the second parameter and give it 5 values ranging from
# 4.6 to 5.4 in steps of 0.2.
testpar.clear()
testpar.Name = "param2"
testpar.InterpolationMethod = 0
testpar.InitialValue = 5.0
testpar.Delta = 0.1
testpar.Minimum = 4.6
testpar.Bottom = 4.6
testpar.Top = 5.4
testpar.Maximum = 5.4
for i in xrange(11): testpar.TabulatedValues.append(4.6+0.2*i)
# and push it onto the vector of parameters
test.pushParameter(testpar);
# define an additional parameter (usually the elemental abundance)
# does not require tabulated values.
testpar.clear()
2.5. TABLE MODEL EXAMPLE
testpar.Name = "addparam"
testpar.InterpolationMethod = 0
testpar.InitialValue = 0.0
testpar.Delta = 0.1
testpar.Minimum = 0.0
testpar.Bottom = 0.0
testpar.Top = 5.0
testpar.Maximum = 5.0
# and push it onto the vector of parameters
test.pushParameter(testpar)
# now set up the spectra. these are arbitrarily calculated, in a real program
# this step would read a file or call a routine.
addflux = []
testspec = tableSpectrum()
for i1 in xrange(11):
for i2 in xrange(5):
testspec.clear()
testspec.ParameterValues.append(0.2*i1)
testspec.ParameterValues.append(4.6+0.2*i2)
addflux = []
for j in xrange(99):
testspec.Flux.append(0.2*i1+10*(4.6+0.2*i2)+j*0.1)
addflux.append((i1+1)*(i2+1)+j*0.2)
testspec.pushaddFlux(addflux)
test.pushSpectrum(testspec)
# now write out the table.
test.write("test.mod");
9
10
CHAPTER 2. PYTHON MODULE
Chapter 3
C++ classes and methods
3.1
3.1.1
Spectra
Introduction and example
Spectrum files can be manipulated using the pha and phaII classes. The latter is simply a vector
of pha classes and is useful for handling type II PHA files. The grouping class and utility routines
are also useful for some tasks. As an example the code below reads in a type II PHA file, bins up
all the spectra by a factor of 2, then writes out the result. Note that the data types Integer and
Real are defined in heasp.h.
#include "grouping.h"
#include "phaII.h"
using namespace std;
int main(int argc, char* argv[])
{
string infile("testin.pha");
string outfile("testout.pha");
phaII inputSpectra;
Integer Status(0);
// read in all the spectra
Status = inputSpectra.read(infile, 1);
11
12
CHAPTER 3. C++ CLASSES AND METHODS
Integer Nspectra = inputSpectra.NumberSpectra();
// loop round the spectra
for (size_t i=0; i<(size_t)Nspectra; i++) {
// set up the grouping object to rebin by a factor of 2
grouping groupInfo;
groupInfo.load(2, inputSpectra.phas[i].NumberChannels());
// rebin this spectrum
Status = inputSpectra.phas[i].rebinChannels(groupInfo);
}
// write the new spectra out copying extra keywords and extensions from
// the input file
Status = inputSpectra.write(outfile, infile);
exit(0);
}
3.1.2
pha class
class pha{
public:
Integer FirstChannel;
// First legal channel number
vector Pha;
vector StatError;
vector SysError;
// PHA data
// Statistical error
// Statistical error
vector Channel;
vector Quality;
vector Group;
// Channel number
// Data quality
// Data grouping
vector AreaScaling; // Area scaling factor
vector BackScaling; // Background scaling factor
13
3.1. SPECTRA
Real Exposure;
Real CorrectionScaling;
// Exposure time
// Correction file scale factor
Integer DetChans;
bool Poisserr;
string Datatype;
string PHAVersion;
//
//
//
//
string Spectrumtype;
// "TOTAL", "NET", or "BKG"
string
string
string
string
ResponseFile;
AncillaryFile;
BackgroundFile;
CorrectionFile;
//
//
//
//
string
string
string
string
string
string
ChannelType;
Telescope;
Instrument;
Detector;
Filter;
Datamode;
// Value of CHANTYPE keyword
Total legal number of channels
If true, errors are Poisson
"COUNT" for count data and "RATE" for count/sec
PHA extension format version
Response filename
Ancillary filename
Background filename
Correction filename
vector XSPECFilter; // Filter keywords
3.1.3
•
pha class public methods
Integer read(string filename)
Integer read(string filename, Integer PHAnumber)
Integer read(string filename, Integer PHAnumber,
Integer SpectrumNumber)
Read file into object. If PHAnumber is given then look for the SPECTRUM extension with
EXTVER=PHAnumber. The third option is to read the pha from the SpectrumNumber row
of a type II file.
•
pha& operator= (const pha&)
Deep copy.
•
Integer NumberChannels()
Return the size of vector¡Real¿s.
•
string disp()
Display information about the spectrum - return as a string.
14
CHAPTER 3. C++ CLASSES AND METHODS
void clear()
•
Clear information from the spectrum
string check()
•
Check completeness and consistency of information in spectrum, if there is a problem then
return diagnostic in string.
Integer write(string filename)
•
Integer write(string filename, string copyfilename)
Integer write(string filename, string copyfilename,
Integer HDUnumber)
Write spectrum as type I file. If copyfilename is given then copy from it other HDUs and other
keywords in the SPECTRUM extension. If HDUnumber is specified then use the SPECTRUM
extension with EXTVER=HDUnumber in copyfilename. Note that if the output filename
exists and already has a SPECTRUM extension then these methods will write an additional
SPECTRUM extension.
void setGrouping(grouping&, Integer&)
•
Set the pha grouping array from a grouping object.
void rebinChannels(grouping&, Integer&)
•
Rebin spectrum channels based on a grouping object.
3.1.4
•
Other pha routines
Integer PHAtype(string filename, Integer PHAnumber)
Integer PHAtype(string filename, Integer PHAnumber,
Integer& Status)
Return the type of a SPECTRUM extension.
•
bool IsPHAcounts(string filename, Integer PHAnumber)
bool IsPHAcounts(string filename, Integer PHAnumber,
Integer& Status)
Return true if the COUNTS column exists and is integer.
•
Integer NumberofSpectra(string filename,
Integer PHAnumber)
Integer NumberofSpectra(string filename,
Integer PHAnumber, Integer& Status)
Return the number of spectra in a type II SPECTRUM extension.
15
3.1. SPECTRA
3.1.5
phaII class
class phaII{
public:
vector phas;
3.1.6
•
// vector of pha objects
phaII class public methods
Integer read(string filename)
Integer read(string filename, Integer PHAnumber)
Integer read(string filename, Integer PHAnumber,
vector SpectrumNumber)
Read a PHA type II file into an object. If PHAnumber is given then read from the SPECTRUM extension with EXTVER=PHAnumber. If the SpectrumNumber array is given then
read those rows in the extension otherwise read all spectra.
•
phaII& operator= (const phaII&)
Deep copy.
•
pha get(Integer number)
Get pha object (counts from zero).
•
pha push(pha sp)
Push pha object into phaII object
•
Integer NumberSpectra()
Return the number of spectra in the object.
•
string disp()
Display information about the spectra - return as a string.
•
void clear()
Clear information about the spectra
•
string check()
Check completeness and consistency of information in spectrum, if there is a problem then
return diagnostic in string.
•
Integer write(string filename)
16
CHAPTER 3. C++ CLASSES AND METHODS
Integer write(string filename, string copyfilename)
Integer write(string filename, string copyfilename,
Integer HDUnumber)
Write spectra as type II file. If copyfilename is given then copy from it other HDUs and other
keywords in the SPECTRUM extension. If HDUnumber is specified then use the SPECTRUM
extension with EXTVER=HDUnumber in copyfilename. Note that if the output filename
exists and already has a SPECTRUM extension then these methods will write an additional
SPECTRUM extension.
3.2
3.2.1
Responses
Introduction and example
Response files come in two varieties: RMFs and ARFs. The former contain the response matrices
describing the probability of a photon of a given energy being registered in a given channel of
the spectrum. The latter describes the effictive area versus energy. The rmf class is used for
manipulating RMFs and the arf and arfII classes for manipulating ARFs. The arfII class is an
analog of the phaII class and is useful for the case where an ARF file contains many individual
effective area curves. The rmft class handles the transposed response matrix and is of limited use
at present.
The example code below shows a program to read in an RMF file, to compress the matrix to remove
any element below 1.0e-6, to multiply the result by an ARF, and write a new RMF file.
#include "rmf.h"
#ifndef HAVE_arf
#include "arf.h"
#endif
using namespace std;
int main(int argc, char* argv[])
{
string rmffile("testin.rmf");
string arffile("testin.arf");
string outfile("testout.rmf");
rmf inputRMF, outputRMF;
arf inputARF;
Integer Status(0);
17
3.2. RESPONSES
// read in the RMF and the ARF
Status = inputRMF.read(rmffile);
Status = inputARF.read(arffile);
// remove elements from the RMF with values < 1.0e-6
Real threshold(1.0e-6);
inputRMF.compress(threshold);
// multiply the compressed RMF and the ARF to make an output RMF
if ( inputRMF.checkCompatibility(inputARF) ) {
outputRMF = inputRMF * inputARF;
// and write out the result copying any extra HDUs and keywords from
// the input RMF
Status = outputRMF.write(outfile, rmffile);
}
exit(0);
}
3.2.2
rmf class
class rmf{
public:
Integer FirstChannel;
// First channel number
vector NumberGroups;
// Number of response groups for this
// energy bin
// First response group for this energy
// bin (counts from 0)
vector FirstGroup;
vector FirstChannelGroup;
// First channel number in this group
vector NumberChannelsGroup; // Number of channels in this group
vector FirstElement;
// First response element for this group
// (counts from 0)
18
CHAPTER 3. C++ CLASSES AND METHODS
vector OrderGroup;
// The grating order of this group
vector LowEnergy;
vector HighEnergy;
// Start energy of bin
// End energy of bin
vector Matrix;
// Matrix elements
vector ChannelLowEnergy;
vector ChannelHighEnergy;
// Start energy of channel
// End energy of channel
Real AreaScaling;
Real ResponseThreshold;
// Value of EFFAREA keyword
// Minimum value in response
string EnergyUnits;
string RMFUnits;
// Energy units used
// Units for RMF values
string
string
string
string
string
string
string
string
string
string
// Value of CHANTYPE keyword
// MATRIX extension format version
// EBOUNDS extension format version
3.2.3
•
ChannelType;
RMFVersion;
EBDVersion;
Telescope;
Instrument;
Detector;
Filter;
RMFType;
RMFExtensionName;
EBDExtensionName;
// HDUCLAS3 keyword in MATRIX extension
// EXTNAME keyword in MATRIX extension
// EXTNAME keyword in EBOUNDS extension
rmf class public methods
Integer read(string filename)
Integer read(string filename, Integer RMFnumber)
Read the RMF file into an object. If RMFnumber is given read from the MATRIX (or
SPECRESP MATRIX) and EBOUNDS extensions with EXTVER=RMFnumber. If there is
only one EBOUNDS extension then that will be used.
•
Integer readMatrix(string filename)
Integer readMatrix(string filename, Integer RMFnumber)
Read the MATRIX (or SPECRESP MATRIX) extension from an RMF file into an object.
If RMFnumber is given read from the MATRIX (or SPECRESP MATRIX) extension with
EXTVER=RMFnumber.
3.2. RESPONSES
•
19
Integer readChannelBounds(string filename)
Integer readChannelBounds(string filename, Integer RMFnumber)
Read the EBOUNDS extension from an RMF file into an object. If RMFnumber is given
read from the EBOUNDS extension with EXTVER=RMFnumber.
•
void update()
Update the FirstGroup and FirstElement arrays from NumberGroups and NumberChannelsGroup, respectively.
•
void initialize(const arf&)
Initialize from an arf object. Copies members in common between arfs and rmfs
•
rmf& operator= (const rmf&)
Deep copy.
•
Integer NumberChannels()
Return the number of spectrum channels.
•
Integer NumberEnergyBins()
Return the number of response energies.
•
Integer NumberTotalGroups()
Return the number of response groups.
•
Integer NumberTotalElements()
Return the number of response elements.
•
Real ElementValue(Integer Channel, Integer EnergyBin)
Return the value for a particular channel and energy.
•
vector RowValues(Integer EnergyBin)
Return the response array for a particular energy
•
vector RandomChannels(const Real energy,
const Integer NumberPhotons)
Use the response matrix to generate random channel numbers for a photon of given energy.
•
string disp()
Display information about the response. - return as a string.
•
void clear()
Clear information from the response.
20
CHAPTER 3. C++ CLASSES AND METHODS
•
string check()
Check completeness and consistency of information in the rmf, if there is a problem then
return diagnostic in string.
•
void normalize()
Normalize the rmf so it sums to 1.0 for each energy bin.
•
void compress(const Real threshold)
Compress the rmf to remove all elements below the threshold value.
•
Integer rebinChannels(grouping&)
Rebin in channel space using the specified grouping object.
•
Integer rebinEnergies(grouping&)
Rebin in energy space using the specified grouping object.
•
Integer write(string filename)
Integer write(string filename, string copyfilename)
Integer write(string filename, string copyfilename,
Integer HDUnumber)
Write response to a RMF file. If copyfilename is given then copy from it other HDUs and
other keywords in the MATRIX and EBOUNDS extensions. If HDUnumber is specified then
use the MATRIX and EBOUNDS extensions with EXTVER=HDUnumber in copyfilename.
Note that if the output filename exists and already has MATRIX and EBOUNDS extensions
then these methods will write additional extensions.
•
Integer writeMatrix(string filename)
Integer writeMatrix(string filename, string copyfilename)
Integer writeMatrix(string filename, string copyfilename,
Integer HDUnumber)
Write the MATRIX extension to a RMF file. If copyfilename is given then copy from it
other HDUs and other keywords in the MATRIX extension. If HDUnumber is specified then
use the MATRIX extension with EXTVER=HDUnumber in copyfilename. Note that if the
output filename exists and already has a MATRIX extension then these methods will write
an additional extension.
•
Integer writeChannelBounds(string filename)
Integer writeChannelBounds(string filename, string copyfilename)
3.2. RESPONSES
21
Integer writeChannelBounds(string filename, string copyfilename,
Integer HDUnumber)
Write the EBOUNDS extension to a RMF file. If copyfilename is given then copy from it
other HDUs and other keywords in the EBOUNDS extension. If HDUnumber is specified
then use the EBOUNDS extension with EXTVER=HDUnumber in copyfilename. Note that
if the output filename exists and already has a EBOUNDS extension then these methods will
write an additional extension.
rmf& operator*=(const arf&)
•
Multiply current rmf by an arf.
rmf& operator+=(const rmf&)
•
Add another rmf to the current rmf.
bool checkCompatibility(const rmf&)
•
Check compatibility with another rmf.
bool checkCompatibility(const arf&)
•
Check compatibility with an arf.
3.2.4
•
Other rmf routines
rmf operator* (const rmf&, const arf&)
rmf operator* (const arf&, const rmf&)
Multiply an rmf by an arf.
•
rmf operator+ (const rmf&, const rmf&)
Add two rmfs.
•
void compressLine(const vector Response,
const Integer FirstChannel, const Real threshold,
Integer& NumberGroups, vector& oFirstChGrp,
vector& oNumberChsGrp, vector& oMatrix)
Useful routine used in constructing an rmf from individual response arrays for each energy.
Takes in an array and adds on to the rmf.
22
CHAPTER 3. C++ CLASSES AND METHODS
3.2.5
rmft class
class rmft{
public:
Integer FirstChannel;
// First channel number
vector NumberGroups;
//
//
//
//
vector FirstGroup;
Number of response groups for this
channel bin
First response group for this channel
bin (counts from 0)
vector FirstEnergyGroup;
// First energy bin in this group
vector NumberEnergiesGroup; // Number of energy bins in this group
vector FirstElement;
// First response element for this group
// (counts from 0)
vector OrderGroup;
// The grating order of this group
vector LowEnergy;
vector HighEnergy;
// Start energy of bin
// End energy of bin
vector Matrix;
// Matrix elements
vector ChannelLowEnergy;
vector ChannelHighEnergy;
// Start energy of channel
// End energy of channel
Real AreaScaling;
Real ResponseThreshold;
// Value of EFFAREA keyword
// Minimum value in response
string EnergyUnits;
string RMFUnits;
// Energy units
// RMF units
string
string
string
string
string
string
string
string
string
string
// Value of CHANTYPE keyword
// MATRIX extension format version
// EBOUNDS extension format version
ChannelType;
RMFVersion;
EBDVersion;
Telescope;
Instrument;
Detector;
Filter;
RMFType;
RMFExtensionName;
EBDExtensionName;
// HDUCLAS3 keyword in MATRIX extension
// EXTNAME keyword in MATRIX extension
// EXTNAME keyword in EBOUNDS extension
23
3.2. RESPONSES
3.2.6
rmft class public methods
void load(rmf&)
•
Load object from a standard rmf object.
void update
•
Update the FirstGroup and FirstElement arrays from NumberGroups and NumberEnergiesGroup, respectively.
rmft& operator= (const rmft&)
•
Deep copy.
Integer NumberChannels()
•
Number of spectrum channels
Integer NumberEnergyBins()
•
Number of response energies
Integer NumberTotalGroups()
•
Total number of response groups
Integer NumberTotalElements()
•
Total number of response elements
Real ElementValue(Integer Channel, Integer EnergyBin)
•
Return the value for a particular channel and energy.
vector RowValues(Integer Channel)
•
Return the array for a particular channel.
string disp()
•
Display information about the object. - return as a string.
void clear()
•
Clear information from the object.
3.2.7
arf class
class arf{
public:
vector LowEnergy;
vector HighEnergy;
// Start energy of bin
// End energy of bin
24
CHAPTER 3. C++ CLASSES AND METHODS
vector EffArea;
// Effective areas
string EnergyUnits;
string arfUnits;
// Units for energies
// Units for effective areas
string
string
string
string
string
string
// SPECRESP extension format version
3.2.8
•
Version;
Telescope;
Instrument;
Detector;
Filter;
ExtensionName;
// EXTNAME keyword in SPECRESP extension
arf class public methods
Integer read(string filename)
Integer read(string filename, Integer ARFnumber)
Integer read(string filename, Integer ARFnumber,
Integer RowNumber)
Read file into an object. If ARFnumber is given read from the SPECRESP extension with
EXTVER=ARFnumber. The third option is to read an arf from the RowNumber row of a
type II file.
•
arf& operator= (const arf&)
Deep copy.
•
Integer NumberEnergyBins()
Return size of vector¡Real¿s.
•
string disp()
Display information about the arf. - return as a string.
•
void clear()
Clear information from the arf.
•
string check()
Check completeness and consistency of information in the arf, if there is a problem then
return diagnostic in string.
•
Integer write(string filename)
Integer write(string filename, string copyfilename)
25
3.2. RESPONSES
Integer write(string filename, string copyfilename,
Integer HDUnumber)
Write arf as type I file. If copyfilename is given then copy from it other HDUs and other
keywords in the SPECRESP extension. If HDUnumber is specified then use the SPECRESP
extension with EXTVER=HDUnumber in copyfilename. Note that if the output filename
exists and already has a SPECRESP extension then these methods will write an additional
SPECRESP extension.
arf& operator+=(const arf&)
•
Add another arf.
bool checkCompatibility(const arf&)
•
Check compatibility with another arf.
3.2.9
Other arf routines
arf operator+ (const arf&, const arf&)
•
Add two arfs.
Integer NumberofARFs(string filename, Integer HDUumber)
•
Integer NumberofARFs(string filename, Integer HDUumber,
Integer& Status)
Return the number of ARFS in the type II SPECRESP extension.
3.2.10
arfII class
class arfII{
public:
vector arfs;
3.2.11
•
// vector of arf objects
arfII class public methods
Integer read(string filename)
Integer read(string filename, Integer ARFnumber)
26
CHAPTER 3. C++ CLASSES AND METHODS
Integer read(string filename, Integer ARFnumber,
vector RowNumber)
Read an ARF type II file into an object. If ARFnumber is given then read from the
SPECRESP extension with EXTVER=ARFnumber. If the RowNumber array is given then
read those in the extension otherwise read all the arfs.
•
arfII& operator= (const arfII&)
Deep copy.
•
arf get(Integer number)
Get arf object (counts from zero).
•
void push(arf ea)
Push arf object into arfII object
•
Integer NumberARFs()
Return the number of ARFs in the object.
•
string disp()
Display information about the ARFs. - return as a string.
•
void clear()
Clear information from the ARFs.
•
string check()
Check completeness and consistency of information in the arfs, if there is a problem then
return diagnostic in string.
•
Integer write(string filename)
Integer write(string filename, string copyfilename)
Integer write(string filename, string copyfilename,
Integer HDUnumber)
Write ARFs as type II file. If copyfilename is given then copy from it other HDUs and other
keywords in the SPECRESP extension. If HDUnumber is specified then use the SPECRESP
extension with EXTVER=HDUnumber in copyfilename. Note that if the output filename
exists and already has a SPECRESP extension then these methods will write an additional
SPECRESP extension.
3.3. TABLE MODELS
3.3
3.3.1
27
Table Models
Introduction and example
The table model file is used in xspec to provide grids of model calculations on which to interpolate
when fitting a model to data. The table class can be used to create these files. The example code
below sets up a grid with two parameters.
#include "table.h"
using namespace std;
int main(int argc, char* argv[])
{
table test;
// set table descriptors and the energy array
test.ModelName = "Test";
test.ModelUnits = " ";
test.isRedshift = true;
test.isAdditive = true;
test.isError = false;
test.Energies.resize(100);
for (size_t i=0; i<100; i++) test.Energies[i] = 0.1+i*0.1;
test.NumIntParams = 2;
test.NumAddParams = 1;
// define first parameter and give it 11 values ranging from
// 0.0 to 2.0 in steps of 0.2.
tableParameter testpar;
testpar.Name = "param1";
testpar.InterpolationMethod = 0;
testpar.InitialValue = 1.0;
testpar.Delta = 0.1;
testpar.Minimum = 0.0;
testpar.Bottom = 0.0;
testpar.Top = 2.0;
testpar.Maximum = 2.0;
28
CHAPTER 3. C++ CLASSES AND METHODS
testpar.TabulatedValues.resize(11);
for (size_t i=0; i<11; i++) testpar.TabulatedValues[i] = 0.2*i;
// and push it onto the vector of parameters
test.Parameters.push_back(testpar);
// define the second parameter and give it 5 values ranging from
// 4.6 to 5.4 in steps of 0.2.
testpar.Name = "param2";
testpar.InterpolationMethod = 0;
testpar.InitialValue = 5.0;
testpar.Delta = 0.1;
testpar.Minimum = 4.6;
testpar.Bottom = 4.6;
testpar.Top = 5.4;
testpar.Maximum = 5.4;
testpar.TabulatedValues.resize(5);
for (size_t i=0; i<5; i++) testpar.TabulatedValues[i] = 4.6+0.2*i;
// and push it onto the vector of parameters
test.Parameters.push_back(testpar);
// define an additional parameter (usually the elemental abundance)
// does not require tabulated values.
testpar.Name = "addparam";
testpar.InterpolationMethod = 0;
testpar.InitialValue = 0.0;
testpar.Delta = 0.1;
testpar.Minimum = 0.0;
testpar.Bottom = 0.0;
testpar.Top = 5.0;
testpar.Maximum = 5.0;
testpar.TabulatedValues.resize(0);
// and push it onto the vector of parameters
test.Parameters.push_back(testpar);
29
3.3. TABLE MODELS
// now set up the spectra. these are arbitrarily calculated, in a real program
// this step would read a file or call a routine.
tableSpectrum testspec;
testspec.Flux.resize(99);
testspec.ParameterValues.resize(2);
vector addFlux(99);
for (size_t i1=0; i1<11; i1++) {
for (size_t i2=0; i2<5; i2++) {
testspec.ParameterValues[0] = 0.2*i1;
testspec.ParameterValues[1] = 4.6+0.2*i2;
for (size_t j=0; j<99; j++) {
testspec.Flux[j] = testspec.ParameterValues[0]+10*testspec.ParameterValues[1];
addFlux[j] = 1.0*(i1+1)*(i2+1);
}
testspec.addFlux.push_back(addFlux);
test.Spectra.push_back(testspec);
testspec.addFlux.clear();
}
}
// now write out the table.
test.write("test.mod");
exit(0);
}
3.3.2
table classes
The class for parameters:
class tableParameter{
public:
string Name;
int InterpolationMethod;
Real InitialValue;
Real Delta;
Real Minimum;
//
//
//
//
//
//
Parameter name
0==linear, 1==log
Initial value for fit
Delta for fit
Hard lower-limit
(should correspond to first tabulated value)
30
CHAPTER 3. C++ CLASSES AND METHODS
Real Bottom;
Real Top;
Real Maximum;
//
//
//
//
vector TabulatedValues; //
Soft lower-limit
Soft upper-limit
Hard upper-limit
(should correspond to last tabulated value)
Tabulated parameter values
and its public methods:
•
string disp()
Display information about the table parameter - return as a string.
•
void clear()
Clear contents of the table parameter
The class for model spectra:
class tableSpectrum{
public:
vector Flux;
vector ParameterValues;
vector> addFlux;
//
//
//
//
Model flux
Parameter values for this spectrum
Model fluxes for any additional
parameters
and its public methods:
•
void pushaddFlux(vector)
Push an additional parameter spectrum
•
vector getaddFlux(Integer Number)
Get an additional parameter spectrum
•
string disp()
Display information about the table spectrum - return as a string.
•
void clear()
Clear contents of the table spectrum
Finally, the class for the complete table:
class table{
public:
31
3.3. TABLE MODELS
vector Parameters;
vector Spectra;
string ModelName;
string ModelUnits;
int NumIntParams;
int NumAddParams;
bool isError;
bool isRedshift;
bool isAdditive;
vector Energies;
//
//
//
//
//
//
//
//
//
//
//
//
Parameter information
Tabulated model spectra
Name to use in xspec
Units (not used at present)
Dimension of interpolation grid
Number of additional parameters
If true then model errors included
If true include redshift
If true model is additive
Energy bins on which model is calculated
The size should be one larger than that
of the spectrum array
and its public methods:
•
void pushParameter(tableParameter paramObject)
Push a table parameter object
•
void pushSpectrum(tableSpectrum spectrumObject)
Push a table spectrum object
•
tableParameter getParameter(Integer Number)
Get a table parameter object
•
tableSpectrum getSpectrum(Integer Number)
Get a table spectrum object
•
string disp()
Display information about the table - return as a string.
•
void clear()
Clear contents of the table
•
string check()
Check completeness and consistency of information in table, if there is a problem then return
diagnostic in string.
•
write(string filename)
Write to a FITS file
32
CHAPTER 3. C++ CLASSES AND METHODS
3.4
Grouping
3.4.1
grouping class
class grouping{
public:
vector flag;
3.4.2
// Grouping flag: 1=start of bin,
//
0=continuation of bin
grouping class public methods
• grouping(vector flaginput)
Constructor from an integer array of flag values.
• string disp()
Display grouping information. - return as a string.
• void clear()
Clear grouping information.
• Integer read(string filename, const Integer Number,
const Integer First)
Read from an ascii file of grouping factors. Each line of the file should have three numbers,
the start bin, end bin, and grouping factor. The input bin numbers start at First and there
are Number in total.
• void load(const Integer BinFactor, const Integer Number)
Set the grouping flags for Number bins with a binning factor of BinFactor.
• Integer load(const vector& StartBin, const vector& EndBin,
const vector& BinFactor, const Integer Number,
const Integer First)
Set grouping flags from an array of binning information in the StartBin, EndBin and BinFactor
arrays. The input bin numbers start at First and there are Number in total.
• bool newBin(const Integer Bin)
Return whether Bin is the start of a group.
• Integer size()
Return number of bins in grouping object.
3.5. UTILITY ROUTINES
3.4.3
•
33
Other grouping routines
template void GroupBin(const vector& inArray,
const Integer mode, const grouping& GroupInfo, vector& outArray)
template void GroupBin(const valarray& inArray,
const Integer mode, const grouping& GroupInfo, valarray& outArray)
This routine applies GroupInfo to the input inArray to create the output outArray. The
behavior is determined by mode which can take five values: SumMode which adds the contents
of all bins in a group; SumQuadMode which adds the bins in quadrature; MeanMode which
returns the arithmetic mean of the all bins in a group; FirstEltMode which returns the value
of the first bin in each group; LastEltMode which returns the value of the last bin in each
group.
•
Integer readBinFactors(string filename, vector& StartBin,
vector& EndBin, vector& BinFactor)
Read a file containing grouping information and place into the arrays StartBin, EndBin and
BinFactor. Each line of the file should have three numbers, the start bin, end bin, and
grouping factor.
3.5
•
Utility routines
void SPreadColUnits(ExtHDU&, string, string&)
Read the units associated with a column.
•
void SPwriteColUnits(Table&, string, string)
Write the units associated with a column.
•
string SPstringTform(const vector& Data)
Returns the tform string for the longest string in the input vector.
•
Integer SPcopyHDUs(string infile, string outfile)
Copy from infile to outfile all HDUs which are not manipulated by this library.
•
Integer SPcopyKeys(string infile, string outfile, string HDUname,
Integer HDUnumber)
Copy non-critical keywords from infile to outfile for HDUname extension with EXTVER
HDUnumber.
34
CHAPTER 3. C++ CLASSES AND METHODS
Chapter 4
C interface
4.1
4.1.1
PHA files
PHA structure
struct PHA {
long NumberChannels;
long FirstChannel;
/* Number of spectrum channels */
/* First channel number */
float* Pha;/*NumberChannels*/
/* PHA data */
float* StatError;/*NumberChannels*/ /* Statistical error */
float* SysError;/*NumberChannels*/
/* Statistical error */
int*
int*
int*
Quality;/*NumberChannels*/
/* Data quality */
Grouping; /*NumberChannels*/ /* Data grouping */
Channel; /*NumberChannels*/
/* Channel number */
float* AreaScaling;/*NumberChannels*//* Area scaling factor */
float* BackScaling;/*NumberChannels*//* Background scaling factor */
float Exposure;
float CorrectionScaling;
int
DetChans;
/* Exposure time */
/* Correction file scale factor */
/* Content of DETCHANS keyword */
int Poisserr;
char Datatype[FLEN_KEYWORD];
/*
/*
/*
/*
char Spectrumtype[FLEN_KEYWORD];
35
If true, errors are Poisson */
"COUNT" for count data and */
"RATE" for count/sec */
"TOTAL", "NET", or "BKG" */
36
CHAPTER 4. C INTERFACE
char
char
char
char
ResponseFile[FLEN_FILENAME];
AncillaryFile[FLEN_FILENAME];
BackgroundFile[FLEN_FILENAME];
CorrectionFile[FLEN_FILENAME];
/*
/*
/*
/*
char
char
char
char
char
char
char
ChannelType[FLEN_KEYWORD];
PHAVersion[FLEN_KEYWORD];
Telescope[FLEN_KEYWORD];
Instrument[FLEN_KEYWORD];
Detector[FLEN_KEYWORD];
Filter[FLEN_KEYWORD];
Datamode[FLEN_KEYWORD];
/* Value of CHANTYPE keyword */
/* PHA extension format version */
char *XSPECFilter[100];
};
4.1.2
•
Response filename */
Ancillary filename */
Background filename */
Correction filename */
/* Filter keywords */
PHA routines
int ReadPHAtypeI(char *filename, long PHAnumber, struct PHA *phastruct)
Read the type I SPECTRUM extension from a FITS file - if there are multiple SPECTRUM
extensions then read the one with EXTVER=PHAnumber.
•
int ReadPHAtypeII(char *filename, long PHAnumber, long NumberSpectra,
long *SpectrumNumber, struct PHA **phastructs)
Read the type II SPECTRUM extension from a FITS file - if there are multiple SPECTRUM
extensions then read the one with EXTVER=PHAnumber. Within the SPECTRUM extension reads the spectra listed in the SpectrumNumber vector.
•
int WritePHAtypeI(char *filename, struct PHA *phastruct)
Write the spectrum to a type I SPECTRUM extension in a FITS file.
•
int WritePHAtypeII(char *filename, long NumberSpectra,
struct PHA **phastructs)
Write the multiple spectra to a type II SPECTRUM extension in a FITS file.
•
int ReturnPHAtype(char *filename, long PHAnumber)
Return the type of the SPECTRUM extension with EXTVER=PHAnumber.
•
void DisplayPHAtypeI(struct PHA *phastruct)
Write information about the spectrum to stdout.
•
void DisplayPHAtypeII(long NumberSpectra, struct PHA **phastructs)
Write information about multiple spectra to stdout.
37
4.2. RMF FILES
int RebinPHA(struct PHA *phastruct, struct BinFactors *bin)
•
Rebin spectrum.
int CheckPHAcounts(char *filename, long PHAnumber)
•
Return 0 if COUNTS column exists and is integer or COUNTS column does not exist.
long ReturnNumberofSpectra(char *filename, long PHAnumber)
•
Return the number of spectra in the type II SPECTRUM extension which has EXTVER
equal to PHAnumber.
4.2
4.2.1
RMF files
RMF structure
struct RMF {
long
long
long
long
long
long
NumberChannels;
NumberEnergyBins;
NumberTotalGroups;
NumberTotalElements;
FirstChannel;
isOrder;
long* NumberGroups;/*NumberEnergyBins*/
long* FirstGroup;/*NumberEnergyBins*/
/*Number of spectrum channels*/
/*Number of response energies*/
/*Total number of resp groups*/
/*Total number of resp elts*/
/*First channel number*/
/*If true grating order*/
/*information included*/
/*Number of resp groups for*/
/*this energy bin*/
/*First resp group for this*/
/*energy bin (counts from 0)*/
long* FirstChannelGroup;/*NumberTotalGroups*/ /*First channel number in*/
/*this group*/
long* NumberChannelGroups;/*NumberTotalGroups*//*Num of channels in this grp*/
long* FirstElement;/*NumberTotalGroups*/
/*First resp elt for this grp*/
/*(counts from 0)*/
long* OrderGroup;/*NumberTotalGroups*/
/*Grating order of this grp*/
float* LowEnergy;/*NumberEnergyBins*/
float* HighEnergy;/*NumberEnergyBins*/
/*Start energy of bin*/
/*End energy of bin*/
float* Matrix;/*NumberTotalElements*/
/*Matrix elements*/
float* ChannelLowEnergy;/*NumberChannels*/
float* ChannelHighEnergy;/*NumberChannels*/
/*Start energy of channel*/
/*End energy of channel*/
38
CHAPTER 4. C INTERFACE
float AreaScaling;
float ResponseThreshold;
/*Value of EFFAREA keyword*/
/*Minimum value in response*/
char EnergyUnits[FLEN_KEYWORD];
char RMFUnits[FLEN_KEYWORD];
/*Units for energies*/
/*Units for RMF*/
char
char
char
char
char
char
char
char
char
char
/*Value of CHANTYPE keyword*/
/*MATRIX format version*/
/*EBOUNDS format version*/
ChannelType[FLEN_KEYWORD];
RMFVersion[FLEN_KEYWORD];
EBDVersion[FLEN_KEYWORD];
Telescope[FLEN_KEYWORD];
Instrument[FLEN_KEYWORD];
Detector[FLEN_KEYWORD];
Filter[FLEN_KEYWORD];
RMFType[FLEN_KEYWORD];
RMFExtensionName[FLEN_VALUE];
EBDExtensionName[FLEN_VALUE];
/*HDUCLAS3 keyword in MATRIX*/
/*EXTNAME keyword in MATRIX*/
/*EXTNAME keyword in EBOUNDS*/
};
struct RMFchan {
long
long
long
long
long
long
NumberChannels;
NumberEnergyBins;
NumberTotalGroups;
NumberTotalElements;
FirstChannel;
isOrder;
long* NumberGroups;/*NumberChannels*/
long* FirstGroup;/*NumberChannels*/
/*Number of spectrum channels*/
/*Number of response energies*/
/*Total number of resp groups*/
/*Total number of resp elts*/
/*First channel number*/
/*If true grating order*/
/*information included*/
/*Number of resp groups for*/
/*this channel bin*/
/*First resp group for this*/
/*channel bin (counts from 0)*/
long* FirstEnergyGroup;/*NumberTotalGroups*/ /*First energy bin in this grp*/
long* NumberEnergyGroups;/*NumberTotalGroups*//*Number of energy bins in*/
/*this group */
long* FirstElement;/*NumberTotalGroups*/
/*First resp elt for this grp*/
/*(counts from 0)*/
long* OrderGroup;/*NumberTotalGroups*/
/*Grating order of this group*/
float* LowEnergy;/*NumberEnergyBins*/
float* HighEnergy;/*NumberEnergyBins*/
/*Start energy of bin*/
/*End energy of bin*/
39
4.2. RMF FILES
float* Matrix;/*NumberTotalElements*/
/*Matrix elements*/
float* ChannelLowEnergy;/*NumberChannels*/
float* ChannelHighEnergy;/*NumberChannels*/
/*Start energy of channel*/
/*End energy of channel*/
float AreaScaling;
float ResponseThreshold;
/*Value of EFFAREA keyword*/
/*Minimum value in response*/
char EnergyUnits[FLEN_KEYWORD];
char RMFUnits[FLEN_KEYWORD];
/*Units for energies*/
/*Units for RMF*/
char
char
char
char
char
char
char
char
char
char
/*Value of CHANTYPE keyword*/
/*MATRIX format version*/
/*EBOUNDS format version*/
ChannelType[FLEN_KEYWORD];
RMFVersion[FLEN_KEYWORD];
EBDVersion[FLEN_KEYWORD];
Telescope[FLEN_KEYWORD];
Instrument[FLEN_KEYWORD];
Detector[FLEN_KEYWORD];
Filter[FLEN_KEYWORD];
RMFType[FLEN_KEYWORD];
RMFExtensionName[FLEN_VALUE];
EBDExtensionName[FLEN_VALUE];
/*HDUCLAS3 keyword in MATRIX*/
/*EXTNAME keyword in MATRIX*/
/*EXTNAME keyword in EBOUNDS*/
};
4.2.2
•
RMF routines
int ReadRMFMatrix(char *filename, long RMFnumber, struct RMF *rmf)
Read the RMF matrix from a FITS file - if there are multiple RMF extensions then read the
one with EXTVER=RMFnumber.
•
int WriteRMFMatrix(char *filename, struct RMF *rmf)
Write the RMF matrix to a FITS file.
•
int ReadRMFEbounds(char *filename, long EBDnumber, struct RMF *rmf).
Read the RMF ebounds from a FITS file - if there are multiple EBOUNDS extensions then
read the one with EXTVER=EBDnumber.
•
int WriteRMFEbounds(char *filename, struct RMF *rmf)
Write the RMF ebounds to a FITS file.
•
void DisplayRMF(struct RMF *rmf)
Write information about RMF to stdout.
40
CHAPTER 4. C INTERFACE
void ReturnChannel(struct RMF *rmf, float energy, int NumberPhotons,
long *channel)
•
Return the channel for a photon of the given input energy - draws random numbers to return
NumberPhotons entries in the channel array.
void NormalizeRMF(struct RMF *rmf)
•
Normalize the response to unity in each energy.
void CompressRMF(struct RMF *rmf, float threshold)
•
Compress the response to remove all elements below the threshold value.
int RebinRMFChannel(struct RMF *rmf, struct BinFactors *bins)
•
Rebin the RMF in channel space.
int RebinRMFEnergy(struct RMF *rmf, struct BinFactors *bins)
•
Rebin the RMF in energy space.
void TransposeRMF(struct RMF *rmf, struct RMFchan *rmfchan)
•
Transpose the matrix.
float ReturnRMFElement(struct RMF *rmf, long channel, long energybin)
•
Return a single value from the matrix.
float ReturnRMFchanElement(struct RMFchan *rmfchan, long channel,
long energybin)
•
Return a single value from the transposed matrix.
int AddRMF(struct RMF *rmf1, struct RMF *rmf2)
•
Add rmf2 onto rmf1.
4.3
4.3.1
ARF files
ARF structure
struct ARF {
long NumberEnergyBins;
/* Number of response energies */
float* LowEnergy; /*NumberEnergyBins*/ /* Start energy of bin */
float* HighEnergy; /*NumberEnergyBins*/ /* End energy of bin */
float* EffArea;
/*NumberEnergyBins*/ /* Effective areas */
char EnergyUnits[FLEN_KEYWORD];
/* Units for energies */
41
4.4. BINNING AND UTILITY
char arfUnits[FLEN_KEYWORD];
/* Units for effective areas */
char
char
char
char
char
char
/* SPECRESP extension format version */
ARFVersion[FLEN_KEYWORD];
Telescope[FLEN_KEYWORD];
Instrument[FLEN_KEYWORD];
Detector[FLEN_KEYWORD];
Filter[FLEN_KEYWORD];
ARFExtensionName[FLEN_VALUE];
/* EXTNAME keyword in SPECRESP */
};
4.3.2
ARF routines
int ReadARF(char *filename, long ARFnumber, struct ARF *arf)
•
Read the effective areas from a FITS file - if there are multiple SPECRESP extensions then
read the one with EXTVER=ARFFnumber.
int WriteARF(char *filename, struct ARF *arf)
•
Write the ARF to a FITS file.
void DisplayARF(struct ARF *arf)
•
Write information about ARF to stdout.
int AddARF(struct ARF *arf1, struct ARF *arf2)
•
Add arf2 onto arf1.
long MergeARFRMF(struct ARF *arf, struct RMF *rmf)
•
Multiply the ARF into the RMF.
4.4
Binning and utility
4.4.1
BinFactors structure
struct BinFactors {
long NumberBinFactors;
long *StartBin;
long *EndBin;
long *Binning;
};
42
CHAPTER 4. C INTERFACE
4.4.2
•
Binning and utility routines
int SPReadBinningFile(char *filename, struct BinFactors *binning)
Read an ascii file with binning factors and load the binning array.
•
int SPSetGroupArray(int inputSize, struct BinFactors *binning,
int *groupArray)
Set up a grouping array using the BinFactors structure.
•
int SPBinArray(int inputSize, float *input, int *groupArray, int mode,
float *output)
Bin an array using the information in the grouping array.
•
void SPsetCCfitsVerbose(int mode)
Set the CCfits verbose mode.
•
int SPcopyExtensions(char *infile, char *outfile)
Copy all HDUs which are not manipulated by this library.
•
int SPcopyKeywords(char *infile, char *outfile, char *hduname,
int hdunumber)
Copy all non-critical keywords for the hdunumber instance of the extension hduname.
Appendix A
Ftools and Heasp
The following table lists ftools that operate on spectra or responses and the related HEASP routines.
The read and write routines apply in all cases so are not included in the table. In some, relatively
simple, cases the ftool equivalent could be performed by directly getting and setting class members.
43
44
Ftool
addarf
addrmf
cmppha
cmprmf
dmprmf
gcorpha
gcorrmf
marfrmf
rbnrmf
arf2arf1
ascii2pha
chkarf
chkpha
chkrmf
flx2xsp
grppha
grppha2
mathpha
rbnpha
rsp2rmfarf
sprbnarf
APPENDIX A. FTOOLS AND HEASP
corresponding HEASP C++ routines
arf::operator+=, arf::operator+
rmf::operator+=, rmf::operator+
phaII::get
rmf::compress
directly access rmf class members
none yet
none yet
rmf::operator*=, rmf::operator*
grouping::load, rmf::rebinChannels, rmf::rebinEnergies
arfII:get
directly set pha class members
arf::check, arfII::check
pha::check, phaII::check
rmf::check
directly set pha and rmf class members
grouping::load, pha::setGrouping
phaII::get, grouping::load
pha::setGrouping, phaII::push
none yet
grouping::load, pha::setGrouping, pha::rebinChannels
directly get and set rmf and arf class members
grouping::load, GroupBin
Appendix B
Error Codes
• 1 : NoSuchFile : Cannot find the file specified.
• 2 : NoData : A column read has no members.
• 3 : NoChannelData : The SPECTRUM has no Channel column and no channel data can be
constructed.
• 4 : NoStatError : The SPECTRUM has no statistical error column and POISSERR=F.
• 5 : CannotCreate : Cannot create a new file.
• 6 : NoEnergLo : The ENERG LO column in an ARF or RMF file has no data.
• 7 : NoEnergHi : The ENERG HI column in an ARF or RMF file has no data.
• 8 : NoSpecresp : The SPECRESP column in an ARF has no data.
• 9 : NoEboundsExt : There is no EBOUNDS extension in an RMF file.
• 10 : NoEmin : The E MIN column in an RMF file has no data.
• 11 : NoEmax : The E MAX column in an RMF file has no data.
• 12 : NoMatrixExt : There is no MATRIX extension in an RMF file.
• 13 : NoNgrp : The N GRP column in an RMF file has no data.
• 14 : NoFchan : The F CHAN column in an RMF file has no data.
• 15 : NoNchan : The N CHAN column in an RMF file has no data.
• 16 : NoMatrix : The MATRIX column in an RMF file has no data.
• 17 : CannotCreateMatrixExt : The output MATRIX extension cannot be created.
• 18 : CannotCreateEboundsExt : The output EBOUNDS extension cannot be created.
• 19 : InconsistentGrouping : The grouping information size is different from that of the array
to which it is being applied.
45
Source Exif Data:
File Type : PDF File Type Extension : pdf MIME Type : application/pdf PDF Version : 1.4 Linearized : No Page Count : 47 XMP Toolkit : XMP toolkit 2.9.1-13, framework 1.6 About : 9d40e499-9f0d-11ec-0000-22599734e563 Producer : GPL Ghostscript 8.61 Modify Date : 2012:03:05 13:28:55-05:00 Create Date : 2012:03:05 13:28:55-05:00 Creator Tool : dvips\(k\) 5.98 Copyright 2009 Radical Eye Software Document ID : 9d40e499-9f0d-11ec-0000-22599734e563 Format : application/pdf Title : heasp_guide.dvi Creator : dvips(k) 5.98 Copyright 2009 Radical Eye SoftwareEXIF Metadata provided by EXIF.tools