The sherpa.astro.io.xstable module

Create XSPEC table models.

This module supports creating and writing out XSPEC table models, which can then be read in by the sherpa.astro.xspec.read_xstable_model and sherpa.astro.ui.load_xstable_model routines.

These routines should be considered experimental, as it is not obvious that the interface is as usable as it could be.

Example

The following example creates an additive table model that represents a gaussian model where the only parameters are the line position and the normalization.

>>> import numpy as np
>>> from sherpa.astro.io import xstable
>>> from sherpa.astro.xspec import XSgaussian

We shall use the XSPEC gaussian model sherpa.astro.xspec.XSgaussian to create the template models.

>>> mdl = XSgaussian()
>>> print(mdl)
gaussian
   Param        Type          Value          Min          Max      Units
   -----        ----          -----          ---          ---      -----
   gaussian.LineE thawed          6.5            0        1e+06        keV
   gaussian.Sigma thawed          0.1            0           20        keV
   gaussian.norm thawed            1            0        1e+24

The models will be evaluated over the 0.1 to 2 keV range, with a bin spacing of 0.01 keV (note that the last bin ends at 1.99 and not 2.0 keV thanks to the behavior of numpy.arange).

>>> egrid = np.arange(0.1, 2, 0.01)
>>> elo = egrid[:-1]
>>> ehi = egrid[1:]
>>> emid = (elo + ehi) / 2

The table model will interpolate over the line position over the range of 0 to 2.4 inclusive, with a spacing of 0.1 keV:

>>> linepos = np.arange(0, 2.5, 0.1)
>>> minval = linepos[0]
>>> maxval = linepos[-1]

The model is evaluated over the grid defined by elo and ehi for each element of linepos, which is used to set the sherpa.astro.xspec.XSgaussian.LineE parameter:

>>> models = []
>>> for lp in linepos:
...     mdl.linee = lp
...     ymodel = mdl(elo, ehi)
...     models.append(ymodel)
...

This model has a single interpolated parameter which we call "pos". Note that the delta parameter - here set to 0.01 - is only used by Sherpa to decide if the parameter is frozen (value is negative) or not, but is used by the optimiser in XSPEC. The values field is set to those used to generate the spectral models.

>>> param = xstable.Param("pos", 1, 0.01, minval, maxval,
...                       values=linepos)

With this we can create the necessary information to create the table model (make_xstable_model) and then write it out as a FITS file (write_xstable_model):

>>> hdus = xstable.make_xstable_model("gaussy", elo, ehi, params=[param],
...                                   spectra=models)
>>> xstable.write_xstable_model("example.mod", hdus, clobber=True)

This file can then be used in Sherpa with either sherpa.astro.ui.load_xstable_model or sherpa.astro.xspec.read_xstable_model. For example:

>>> from sherpa.astro import ui
>>> ui.load_xstable_model("mygauss", "example.mod")
>>> print(mygauss)
xstablemodel.mygauss
   Param        Type          Value          Min          Max      Units
   -----        ----          -----          ---          ---      -----
   mygauss.pos  thawed            1            0          2.4
   mygauss.norm thawed            1            0        1e+24

Notes

XSPEC models can be created without XSPEC support in Sherpa, but XSPEC support is needed to read the files in.

For additive models it is assumed that the model values - that is, each bin - have units of photon/cm^2/s. This is easy to accidentally change - e.g. in the example above if mdl.norm were changed to a value other than 1 everything would work but Sherpa and XSPEC would infer incorrect fluxes or luminosities.

Classes

BaseParam(name, initial, delta, hardmin, hardmax)	Represent a parameter.
Param(name, initial, delta, hardmin, ...)	Represent an interpolated parameter.

Functions

make_xstable_model(name, egrid_lo, egrid_hi, ...)	Create the blocks for a XSPEC table model.
write_xstable_model(filename, hdus[, clobber])	Write a XSPEC table model to disk.

Class Inheritance Diagram