EnergyDispersion

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

Bases: object

Energy dispersion matrix.

Data format specification: RMF

Parameters

e_true_lo, e_true_hiQuantity

True energy axis binning

e_reco_lo, e_reco_hiQuantity

Reconstruced energy axis binning

dataarray_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_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)

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

dataarray_like

1-dim data array.

Returns

convolved_dataarray

1-dim data array after multiplication with the energy dispersion matrix

classmethod from_diagonal_response(e_true, e_reco=None)

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_recoQuantity

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)

Create Gaussian energy dispersion matrix (EnergyDispersion).

Calls gammapy.irf.EnergyDispersion2D.from_gauss()

Parameters

e_trueQuantity

Bin edges of true energy axis

e_recoQuantity

Bin edges of reconstructed energy axis

biasfloat or ndarray

Center of Gaussian energy dispersion, bias

sigmafloat or ndarray

RMS width of Gaussian energy dispersion, resolution

pdf_thresholdfloat, optional

Zero suppression threshold

classmethod from_hdulist(hdulist, hdu1='MATRIX', hdu2='EBOUNDS')

Create EnergyDispersion object from HDUList.

Parameters

hdulistHDUList

HDU list with MATRIX and EBOUNDS extensions.

hdu1str, optional

HDU containing the energy dispersion matrix, default: MATRIX

hdu2str, optional

HDU containing the energy axis information, default, EBOUNDS

get_bias(self, e_true)

Get reconstruction bias for a given true energy.

Bias is defined as

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

Parameters

e_trueQuantity

True energy

get_bias_energy(self, bias, emin=None, emax=None)

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

biasfloat

Bias value.

eminQuantity

Lower bracket value in case solution is not unique.

emaxQuantity

Upper bracket value in case solution is not unique.

Returns

bias_energyQuantity

Reconstructed energy corresponding to the 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.

The resolution is given as a percentage of the true energy

Parameters

e_trueQuantity

True energy

pdf_in_safe_range(self, lo_threshold, hi_threshold)

PDF matrix with bins outside threshold set to 0.

Parameters

lo_thresholdQuantity

Low reco energy threshold

hi_thresholdQuantity

High reco energy threshold

peek(self, figsize=(15, 5))

Quick-look summary plot.

plot_bias(self, ax=None, **kwargs)

Plot reconstruction bias.

See get_bias method.

Parameters

axAxes, optional

Axis

plot_matrix(self, ax=None, show_energy=None, add_cbar=False, **kwargs)

Plot PDF matrix.

Parameters

axAxes, optional

Axis

show_energyQuantity, optional

Show energy, e.g. threshold, as vertical line

add_cbarbool

Add a colorbar to the plot.

Returns

axAxes

Axis

classmethod read(filename, hdu1='MATRIX', hdu2='EBOUNDS')

Read from file.

Parameters

filenamepathlib.Path, str

File to read

hdu1str, optional

HDU containing the energy dispersion matrix, default: MATRIX

hdu2str, optional

HDU containing the energy axis information, default, EBOUNDS

to_hdulist(self, use_sherpa=False, **kwargs)

Convert RMF to FITS HDU list format.

Parameters

headerHeader

Header to be written in the fits file.

energy_unitstr

Unit in which the energy is written in the HDU list

Returns

hdulistHDUList

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_table(self)

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)

Write to file.