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

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 (BinnedDataAxis)
e_true True energy axis (BinnedDataAxis)
pdf_matrix Energy dispersion PDF matrix (ndarray).

Methods Summary

apply(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(e_true) Get reconstruction bias for a given true energy.
get_mean(e_true) Get mean reconstructed energy for a given true energy.
get_resolution(e_true) Get energy resolution for a given true energy.
pdf_in_safe_range(lo_threshold, hi_threshold) PDF matrix with bins outside threshold set to 0.
peek([figsize]) Quick-look summary plot.
plot_bias([ax]) Plot reconstruction bias.
plot_matrix([ax, show_energy, add_cbar]) Plot PDF matrix.
read(filename[, hdu1, hdu2]) Read from file.
to_hdulist(**kwargs) Convert RMF to FITS HDU list format.
to_sherpa(name) Convert to sherpa.astro.data.DataRMF.
to_table() Convert to Table.
write(filename, **kwargs) 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 (BinnedDataAxis)

e_true

True energy axis (BinnedDataAxis)

pdf_matrix

Energy dispersion PDF matrix (ndarray).

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

Methods Documentation

apply(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, BinnedDataAxis

Bin edges of true energy axis

e_reco : Quantity, BinnedDataAxis

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(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_mean(e_true)[source]

Get mean reconstructed energy for a given true energy.

get_resolution(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(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(figsize=(15, 5))[source]

Quick-look summary plot.

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

Plot reconstruction bias.

See get_bias method.

Parameters:
ax : Axes, optional

Axis

plot_matrix(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 : 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(**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(name)[source]

Convert to sherpa.astro.data.DataRMF.

Parameters:
name : str

Instance name

to_table()[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(filename, **kwargs)[source]

Write to file.