Helpers for X-ray spectral modeling with the Sherpa packge (pwkit.sherpa)

This module contains helpers for modeling X-ray spectra with the Sherpa package.

This module includes a grab-bag of helpers in following broad topics:

Additional Spectral Models

The pwkit.sherpa module provides several tools for constructing models not provided in the standard Sherpa distribution.

class pwkit.sherpa.PowerLawApecDemModel(name, kt_array=None)[source]

A model with contributions from APEC plasmas at a range of temperatures, scaling with temperature.

Constructor arguments are:

name

The Sherpa name of the resulting model instance.

kt_array = None

An array of temperatures to use for the plasma models. If left at the default of None, a hard-coded default is used that spans temperatures of ~0.03 to 10 keV with logarithmic spacing.

The contribution at each temperature scales with kT as a power law. The model parameters are:

gfac

The power-law normalization parameter. The contribution at temperature kT is norm * kT**gfac.

Abundanc

The standard APEC abundance parameter.

redshift

The standard APEC redshift parameter.

norm

The standard overall normalization parameter.

This model is only efficient to compute if Abundanc and redshift are frozen.

pwkit.sherpa.make_fixed_temp_multi_apec(kTs, name_template='apec%d', norm=None)[source]

Create a model summing multiple APEC components at fixed temperatures.

kTs

An iterable of temperatures for the components, in keV.

name_template = ‘apec%d’

A template to use for the names of each component; it is string-formatted with the 0-based component number as an argument.

norm = None

An initial normalization to be used for every component, or None to use the Sherpa default.

Returns:

A tuple (total_model, sub_models), where total_model is a Sherpa model representing the sum of the APEC components and sub_models is a list of the individual models.

This function creates a vector of APEC model components and sums them. Their kT parameters are set and then frozen (using sherpa.astro.ui.freeze()), so that upon exit from this function, the amplitude of each component is the only free parameter.

Tools for Plotting with Sherpa Data Objects

get_source_qq_data([id])

Get data for a quantile-quantile plot of the source data and model.

get_bkg_qq_data([id, bkg_id])

Get data for a quantile-quantile plot of the background data and model.

make_qq_plot(kev, obs, mdl, unit, key_text)

Make a quantile-quantile plot comparing events and a model.

make_multi_qq_plots(arrays, key_text)

Make a quantile-quantile plot comparing multiple sets of events and models.

make_spectrum_plot(model_plot, data_plot, desc)

Make a plot of a spectral model and data.

make_multi_spectrum_plots(model_plot, ...[, ...])

Make a plot of multiple spectral models and data.
pwkit.sherpa.get_source_qq_data(id=None)[source]

Get data for a quantile-quantile plot of the source data and model.

id

The dataset id for which to get the data; defaults if unspecified.

Returns:

An ndarray of shape (3, npts). The first slice is the energy axis in keV; the second is the observed values in each bin (counts, or rate, or rate per keV, etc.); the third is the corresponding model value in each bin.

The inputs are implicit; the data are obtained from the current state of the Sherpa ui module.

pwkit.sherpa.get_bkg_qq_data(id=None, bkg_id=None)[source]

Get data for a quantile-quantile plot of the background data and model.

id

The dataset id for which to get the data; defaults if unspecified.

bkg_id

The identifier of the background; defaults if unspecified.

Returns:

An ndarray of shape (3, npts). The first slice is the energy axis in keV; the second is the observed values in each bin (counts, or rate, or rate per keV, etc.); the third is the corresponding model value in each bin.

The inputs are implicit; the data are obtained from the current state of the Sherpa ui module.

pwkit.sherpa.make_qq_plot(kev, obs, mdl, unit, key_text)[source]

Make a quantile-quantile plot comparing events and a model.

kev

A 1D, sorted array of event energy bins measured in keV.

obs

A 1D array giving the number or rate of events in each bin.

mdl

A 1D array giving the modeled number or rate of events in each bin.

unit

Text describing the unit in which obs and mdl are measured; will be shown on the plot axes.

key_text

Text describing the quantile-quantile comparison quantity; will be shown on the plot legend.

Returns:

An omega.RectPlot instance.

TODO: nothing about this is Sherpa-specific. Same goes for some of the plotting routines in pkwit.environments.casa.data; might be reasonable to add a submodule for generic X-ray-y plotting routines.

pwkit.sherpa.make_multi_qq_plots(arrays, key_text)[source]

Make a quantile-quantile plot comparing multiple sets of events and models.

arrays
key_text

Text describing the quantile-quantile comparison quantity; will be shown on the plot legend.

Returns:

An omega.RectPlot instance.

TODO: nothing about this is Sherpa-specific. Same goes for some of the plotting routines in pkwit.environments.casa.data; might be reasonable to add a submodule for generic X-ray-y plotting routines.

TODO: Some gross code duplication here.

pwkit.sherpa.make_spectrum_plot(model_plot, data_plot, desc, xmin_clamp=0.01, min_valid_x=None, max_valid_x=None)[source]

Make a plot of a spectral model and data.

model_plot

A model plot object returned by Sherpa from a call like ui.get_model_plot() or ui.get_bkg_model_plot().

data_plot

A data plot object returned by Sherpa from a call like ui.get_source_plot() or ui.get_bkg_plot().

desc

Text describing the origin of the data; will be shown in the plot legend (with “Model” and “Data” appended).

xmin_clamp

The smallest “x” (energy axis) value that will be plotted; default is 0.01. This is needed to allow the plot to be shown on a logarithmic scale if the energy axes of the model go all the way to 0.

min_valid_x

Either None, or the smallest “x” (energy axis) value in which the model and data are valid; this could correspond to a range specified in the “notice” command during analysis. If specified, a gray band will be added to the plot showing the invalidated regions.

max_valid_x

Like min_valid_x but for the largest “x” (energy axis) value in which the model and data are valid.

Returns:

A tuple (plot, xlow, xhigh), where plot an OmegaPlot RectPlot instance, xlow is the left edge of the plot bounds, and xhigh is the right edge of the plot bounds.

pwkit.sherpa.make_multi_spectrum_plots(model_plot, plotids, data_getter, desc, xmin_clamp=0.01, min_valid_x=None, max_valid_x=None)[source]

Make a plot of multiple spectral models and data.

model_plot

A model plot object returned by Sherpa from a call like ui.get_model_plot() or ui.get_bkg_model_plot().

data_plots

An iterable of data plot objects returned by Sherpa from calls like ui.get_source_plot(id) or ui.get_bkg_plot(id).

desc

Text describing the origin of the data; will be shown in the plot legend (with “Model” and “Data #<number>” appended).

xmin_clamp

The smallest “x” (energy axis) value that will be plotted; default is 0.01. This is needed to allow the plot to be shown on a logarithmic scale if the energy axes of the model go all the way to 0.

min_valid_x

Either None, or the smallest “x” (energy axis) value in which the model and data are valid; this could correspond to a range specified in the “notice” command during analysis. If specified, a gray band will be added to the plot showing the invalidated regions.

max_valid_x

Like min_valid_x but for the largest “x” (energy axis) value in which the model and data are valid.

Returns:

A tuple (plot, xlow, xhigh), where plot an OmegaPlot RectPlot instance, xlow is the left edge of the plot bounds, and xhigh is the right edge of the plot bounds.

TODO: not happy about the code duplication with make_spectrum_plot() but here we are.

Data Structure Utilities

expand_rmf_matrix(rmf)

Expand an RMF matrix stored in compressed form.

derive_identity_arf(name, arf)

Create an "identity" ARF that has uniform sensitivity.

derive_identity_rmf(name, rmf)

Create an "identity" RMF that does not mix energies.
pwkit.sherpa.expand_rmf_matrix(rmf)[source]

Expand an RMF matrix stored in compressed form.

rmf

An RMF object as might be returned by sherpa.astro.ui.get_rmf().

Returns:

A non-sparse RMF matrix.

The Response Matrix Function (RMF) of an X-ray telescope like Chandra can be stored in a sparse format as defined in OGIP Calibration Memo CAL/GEN/92-002. For visualization and analysis purposes, it can be useful to de-sparsify the matrices stored in this way. This function does that, returning a two-dimensional Numpy array.

pwkit.sherpa.derive_identity_arf(name, arf)[source]

Create an “identity” ARF that has uniform sensitivity.

name

The name of the ARF object to be created; passed to Sherpa.

arf

An existing ARF object on which to base this one.

Returns:

A new ARF1D object that has a uniform spectral response vector.

In many X-ray observations, the relevant background signal does not behave like an astrophysical source that is filtered through the telescope’s response functions. However, I have been unable to get current Sherpa (version 4.9) to behave how I want when working with backround models that are not filtered through these response functions. This function constructs an “identity” ARF response function that has uniform sensitivity as a function of detector channel.

pwkit.sherpa.derive_identity_rmf(name, rmf)[source]

Create an “identity” RMF that does not mix energies.

name

The name of the RMF object to be created; passed to Sherpa.

rmf

An existing RMF object on which to base this one.

Returns:

A new RMF1D object that has a response matrix that is as close to diagonal as we can get in energy space, and that has a constant sensitivity as a function of detector channel.

In many X-ray observations, the relevant background signal does not behave like an astrophysical source that is filtered through the telescope’s response functions. However, I have been unable to get current Sherpa (version 4.9) to behave how I want when working with backround models that are not filtered through these response functions. This function constructs an “identity” RMF response matrix that provides the best possible approximation of a passthrough “instrumental response”: it mixes energies as little as possible and has a uniform sensitivity as a function of detector channel.