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_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 (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_bias_energy(bias[, emin, emax])	Find energy corresponding to a given bias.
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)

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)

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)

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')

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)

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(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:

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(e_true)

Get mean reconstructed energy for a given true energy.

get_resolution(e_true)

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)

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

Quick-look summary plot.

plot_bias(ax=None, **kwargs)

Plot reconstruction bias.

See get_bias method.

Parameters:

ax : Axes, optional

Axis

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

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')

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(**kwargs)

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)

Convert to sherpa.astro.data.DataRMF.

Parameters:

name : str

Instance name

to_table()

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)

Write to file.