EDispKernel

class gammapy.irf.EDispKernel(energy_axis_true, energy_axis, data, interp_kwargs=None, meta=None)

Bases: object

Energy dispersion matrix.

Data format specification: RMF

Parameters

energy_axis_trueMapAxis

True energy axis. Its name must be “energy_true”

energy_axisMapAxis

Reconstructed energy axis. Its name must be “energy”

dataarray_like

2-dim energy dispersion matrix

Examples

Create a Gaussian energy dispersion matrix:

from gammapy.maps import MapAxis
from gammapy.irf import EDispKernel
energy = MapAxis.from_energy_bounds(0.1,10,10, unit='TeV')
energy_true = MapAxis.from_energy_bounds(0.1,10,10, unit='TeV', name='energy_true')
edisp = EDispKernel.from_gauss(
    energy_true=energy, energy=energy,
    sigma=0.1, bias=0,
)

Have a quick look:

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

Attributes Summary

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

Methods Summary

from_diagonal_response(energy_true[, energy])	Create energy dispersion from a diagonal response, i.e.
from_gauss(energy_true, energy, sigma, bias)	Create Gaussian energy dispersion matrix (EnergyDispersion).
from_hdulist(hdulist[, hdu1, hdu2])	Create EnergyDispersion object from HDUList.
get_bias(energy_true)	Get reconstruction bias for a given true energy.
get_bias_energy(bias[, energy_min, energy_max])	Find energy corresponding to a given bias.
get_mean(energy_true)	Get mean reconstructed energy for a given true energy.
get_resolution(energy_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([use_sherpa])	Convert RMF to FITS HDU list format.
to_image([lo_threshold, hi_threshold])	Return a 2D edisp by summing the pdf matrix over the ereco axis.
to_table()	Convert to Table.
write(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

energy_axis

Reconstructed energy axis (MapAxis)

energy_axis_true

True energy axis (MapAxis)

pdf_matrix

Energy dispersion PDF matrix (ndarray).

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

Methods Documentation

classmethod from_diagonal_response(energy_true, energy=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 energy_true center is inside the e_reco bin. It is a square diagonal matrix if energy_true = e_reco.

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

Parameters

energy_true, energyQuantity

Energy edges for true and reconstructed energy axis

Examples

If energy_true equals energy, you get a diagonal matrix:

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

Example with different energy binnings:

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

classmethod from_gauss(energy_true, energy, sigma, bias, pdf_threshold=1e-06)

Create Gaussian energy dispersion matrix (EnergyDispersion).

Calls gammapy.irf.EnergyDispersion2D.from_gauss()

Parameters

energy_trueQuantity

Bin edges of true energy axis

energyQuantity

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

Get reconstruction bias for a given true energy.

Bias is defined as

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

Parameters

energy_trueQuantity

True energy

get_bias_energy(bias, energy_min=None, energy_max=None)

Find energy corresponding to a given bias.

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

Parameters

biasfloat

Bias value.

energy_minQuantity

Lower bracket value in case solution is not unique.

energy_maxQuantity

Upper bracket value in case solution is not unique.

Returns

bias_energyQuantity

Reconstructed energy corresponding to the given bias.

get_mean(energy_true)

Get mean reconstructed energy for a given true energy.

get_resolution(energy_true)

Get energy resolution for a given true energy.

The resolution is given as a percentage of the true energy

Parameters

energy_trueQuantity

True energy

pdf_in_safe_range(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(figsize=(15, 5))

Quick-look summary plot.

plot_bias(ax=None, **kwargs)

Plot reconstruction bias.

See get_bias method.

Parameters

axAxes, optional

Axis

plot_matrix(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(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_image(lo_threshold=None, hi_threshold=None)

Return a 2D edisp by summing the pdf matrix over the ereco axis.

Parameters

lo_threshold :`~astropy.units.Quantity`, optional

Low reco energy threshold

hi_thresholdQuantity, optional

High reco energy threshold

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, use_sherpa=False, **kwargs)

Write to file.