EnergyDispersion¶

class gammapy.irf.EnergyDispersion(e_true_lo, e_true_hi, e_reco_lo, e_reco_hi, data, interp_kwargs=None, meta=None)[source]¶

Bases: object

Energy dispersion matrix.

Data format specification: RMF

Parameters:	e_true_lo, e_true_hi : `Quantity` True energy axis binning e_reco_lo, e_reco_hi : `Quantity` Reconstruced energy axis binning data : array_like 2-dim energy dispersion matrix

See also

EnergyDispersion2D

Examples

Create a Gaussian energy dispersion matrix:

import numpy as np
import astropy.units as u
from gammapy.irf import EnergyDispersion
energy = np.logspace(0, 1, 101) * u.TeV
edisp = EnergyDispersion.from_gauss(
    e_true=energy, e_reco=energy,
    sigma=0.1, bias=0,
)

Have a quick look:

>>> print(edisp)
>>> edisp.peek()

Attributes Summary

`default_interp_kwargs`	Default Interpolation kwargs for `NDDataArray`.
`e_reco`	Reconstructed energy axis (`MapAxis`)
`e_true`	True energy axis (`MapAxis`)
`pdf_matrix`	Energy dispersion PDF matrix (`ndarray`).

Methods Summary

`apply`(self, data)	Apply energy dispersion.
`from_diagonal_response`(e_true[, e_reco])	Create energy dispersion from a diagonal response, i.e.
`from_gauss`(e_true, e_reco, sigma, bias[, …])	Create Gaussian energy dispersion matrix (`EnergyDispersion`).
`from_hdulist`(hdulist[, hdu1, hdu2])	Create `EnergyDispersion` object from `HDUList`.
`get_bias`(self, e_true)	Get reconstruction bias for a given true energy.
`get_bias_energy`(self, bias[, emin, emax])	Find energy corresponding to a given bias.
`get_mean`(self, e_true)	Get mean reconstructed energy for a given true energy.
`get_resolution`(self, e_true)	Get energy resolution for a given true energy.
`pdf_in_safe_range`(self, lo_threshold, …)	PDF matrix with bins outside threshold set to 0.
`peek`(self[, figsize])	Quick-look summary plot.
`plot_bias`(self[, ax])	Plot reconstruction bias.
`plot_matrix`(self[, ax, show_energy, add_cbar])	Plot PDF matrix.
`read`(filename[, hdu1, hdu2])	Read from file.
`to_hdulist`(self[, use_sherpa])	Convert RMF to FITS HDU list format.
`to_sherpa`(self, name)	Convert to `sherpa.astro.data.DataRMF`.
`to_table`(self)	Convert to `Table`.
`write`(self, filename[, use_sherpa])	Write to file.

Attributes Documentation

default_interp_kwargs = {'bounds_error': False, 'fill_value': 0, 'method': 'nearest'}¶: Default Interpolation kwargs for NDDataArray. Fill zeros and do not interpolate

e_reco¶: Reconstructed energy axis (MapAxis)

e_true¶: True energy axis (MapAxis)

pdf_matrix¶

Energy dispersion PDF matrix (ndarray).

Rows (first index): True Energy Columns (second index): Reco Energy

Methods Documentation

apply(self, data)[source]¶

Apply energy dispersion.

Computes the matrix product of data (which typically is model flux or counts in true energy bins) with the energy dispersion matrix.

Parameters:	data : array_like 1-dim data array.
Returns:	convolved_data : array 1-dim data array after multiplication with the energy dispersion matrix

classmethod from_diagonal_response(e_true, e_reco=None)[source]¶

Create energy dispersion from a diagonal response, i.e. perfect energy resolution

This creates the matrix corresponding to a perfect energy response. It contains ones where the e_true center is inside the e_reco bin. It is a square diagonal matrix if e_true = e_reco.

This is useful in cases where code always applies an edisp, but you don’t want it to do anything.

Parameters:	e_true, e_reco : `Quantity` Energy bounds for true and reconstructed energy axis

Examples

If e_true equals e_reco, you get a diagonal matrix:

e_true = [0.5, 1, 2, 4, 6] * u.TeV
edisp = EnergyDispersion.from_diagonal_response(e_true)
edisp.plot_matrix()

Example with different energy binnings:

e_true = [0.5, 1, 2, 4, 6] * u.TeV
e_reco = [2, 4, 6] * u.TeV
edisp = EnergyDispersion.from_diagonal_response(e_true, e_reco)
edisp.plot_matrix()

classmethod from_gauss(e_true, e_reco, sigma, bias, pdf_threshold=1e-06)[source]¶

Create Gaussian energy dispersion matrix (EnergyDispersion).

Calls gammapy.irf.EnergyDispersion2D.from_gauss()

Parameters:	e_true : `Quantity` Bin edges of true energy axis e_reco : `Quantity` Bin edges of reconstructed energy axis bias : float or `ndarray` Center of Gaussian energy dispersion, bias sigma : float or `ndarray` RMS width of Gaussian energy dispersion, resolution pdf_threshold : float, optional Zero suppression threshold

classmethod from_hdulist(hdulist, hdu1='MATRIX', hdu2='EBOUNDS')[source]¶

Create EnergyDispersion object from HDUList.

Parameters:	hdulist : `HDUList` HDU list with `MATRIX` and `EBOUNDS` extensions. hdu1 : str, optional HDU containing the energy dispersion matrix, default: MATRIX hdu2 : str, optional HDU containing the energy axis information, default, EBOUNDS

get_bias(self, e_true)[source]¶

Get reconstruction bias for a given true energy.

Bias is defined as

\[\frac{E_{reco}-E_{true}}{E_{true}}\]

Parameters:	e_true : `Quantity` True energy

get_bias_energy(self, bias, emin=None, emax=None)[source]¶

Find energy corresponding to a given bias.

In case the solution is not unique, provide the emin or emax arguments to limit the solution to the given range. By default the peak energy of the bias is chosen as emin.

Parameters:	bias : float Bias value. emin : `Quantity` Lower bracket value in case solution is not unique. emax : `Quantity` Upper bracket value in case solution is not unique.
Returns:	bias_energy : `Quantity` Reconstructed energy corresponding to the given bias.

get_mean(self, e_true)[source]¶: Get mean reconstructed energy for a given true energy.

get_resolution(self, e_true)[source]¶

Get energy resolution for a given true energy.

The resolution is given as a percentage of the true energy

Parameters:	e_true : `Quantity` True energy

pdf_in_safe_range(self, lo_threshold, hi_threshold)[source]¶

PDF matrix with bins outside threshold set to 0.

Parameters:	lo_threshold : `Quantity` Low reco energy threshold hi_threshold : `Quantity` High reco energy threshold

peek(self, figsize=(15, 5))[source]¶: Quick-look summary plot.

plot_bias(self, ax=None, **kwargs)[source]¶

Plot reconstruction bias.

See get_bias method.

Parameters:	ax : `Axes`, optional Axis

plot_matrix(self, ax=None, show_energy=None, add_cbar=False, **kwargs)[source]¶

Plot PDF matrix.

Parameters:	ax : `Axes`, optional Axis show_energy : `Quantity`, optional Show energy, e.g. threshold, as vertical line add_cbar : bool Add a colorbar to the plot.
Returns:	ax : `Axes` Axis

classmethod read(filename, hdu1='MATRIX', hdu2='EBOUNDS')[source]¶

Read from file.

Parameters:	filename : `pathlib.Path`, str File to read hdu1 : str, optional HDU containing the energy dispersion matrix, default: MATRIX hdu2 : str, optional HDU containing the energy axis information, default, EBOUNDS

to_hdulist(self, use_sherpa=False, **kwargs)[source]¶

Convert RMF to FITS HDU list format.

Parameters:	header : `Header` Header to be written in the fits file. energy_unit : str Unit in which the energy is written in the HDU list
Returns:	hdulist : `HDUList` RMF in HDU list format.

Notes

For more info on the RMF FITS file format see: https://heasarc.gsfc.nasa.gov/docs/heasarc/caldb/docs/summary/cal_gen_92_002_summary.html

to_sherpa(self, name)[source]¶

Convert to sherpa.astro.data.DataRMF.

Parameters:	name : str Instance name

to_table(self)[source]¶

Convert to Table.

The output table is in the OGIP RMF format. https://heasarc.gsfc.nasa.gov/docs/heasarc/caldb/docs/memos/cal_gen_92_002/cal_gen_92_002.html#Tab:1

write(self, filename, use_sherpa=False, **kwargs)[source]¶: Write to file.