EDispKernel#

class gammapy.irf.EDispKernel(axes, data=0, unit='', is_pointlike=False, fov_alignment=FoVAlignment.RADEC, meta=None, interp_kwargs=None)[source]#

Bases: gammapy.irf.core.IRF

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_axis_true=energy_true, energy_axis=energy, sigma=0.1, bias=0
>>> )

Have a quick look:

>>> print(edisp)
EDispKernel
-----------

  axes  : ['energy_true', 'energy']
  shape : (10, 10)
  ndim  : 2
  unit  :
  dtype : float64

>>> edisp.peek()

Attributes Summary

axes

MapAxes

data

default_interp_kwargs

Default Interpolation kwargs for IRF.

fov_alignment

Alignment of the field of view coordinate axes, see FoVAlignment

has_offset_axis

Whether the IRF explicitly depends on offset

is_pointlike

Whether the IRF is pointlike of full containment.

pdf_matrix

Energy dispersion PDF matrix (ndarray).

quantity

Quantity

required_axes

tag

unit

Map unit (Unit)

Methods Summary

cumsum(axis_name)

Compute cumsum along a given axis

evaluate([method])

Evaluate IRF

from_diagonal_response(energy_axis_true[, ...])

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

from_gauss(energy_axis_true, energy_axis, ...)

Create Gaussian energy dispersion matrix (EnergyDispersion).

from_hdulist(hdulist[, hdu1, hdu2])

Create EnergyDispersion object from HDUList.

from_table(table[, format])

Read from Table.

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.

integral(axis_name, **kwargs)

Compute integral along a given axis

integrate_log_log(axis_name, **kwargs)

Integrate along a given axis.

interp_missing_data(axis_name)

Interpolate missing data along a given axis

is_allclose(other[, rtol_axes, atol_axes])

Compare two data IRFs for equivalency

normalize(axis_name)

Normalise data in place along a given axis.

pad(pad_width, axis_name, **kwargs)

Pad irf along a given axis.

pdf_in_safe_range(lo_threshold, hi_threshold)

PDF matrix with bins outside threshold set to 0.

peek([figsize])

Quick-look summary plots.

plot_bias([ax])

Plot reconstruction bias.

plot_matrix([ax, add_cbar])

Plot PDF matrix.

read(filename[, hdu1, hdu2])

Read from file.

slice_by_idx(slices)

Slice sub IRF from IRF object.

to_hdulist([format])

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([format])

Convert to Table.

to_table_hdu([format])

Convert to BinTableHDU.

to_unit(unit)

Convert irf to different unit

write(filename[, format])

Write to file.

Attributes Documentation

axes#

MapAxes

data#
default_interp_kwargs = {'bounds_error': False, 'fill_value': 0, 'method': 'nearest'}#

Default Interpolation kwargs for IRF. Fill zeros and do not interpolate

fov_alignment#

Alignment of the field of view coordinate axes, see FoVAlignment

has_offset_axis#

Whether the IRF explicitly depends on offset

is_pointlike#

Whether the IRF is pointlike of full containment.

pdf_matrix#

Energy dispersion PDF matrix (ndarray).

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

quantity#

Quantity

required_axes = ['energy_true', 'energy']#
tag = 'edisp_kernel'#
unit#

Map unit (Unit)

Methods Documentation

cumsum(axis_name)#

Compute cumsum along a given axis

Parameters
axis_namestr

Along which axis to integrate.

Returns
irfIRF

Cumsum IRF

evaluate(method=None, **kwargs)#

Evaluate IRF

Parameters
**kwargsdict

Coordinates at which to evaluate the IRF

methodstr {‘linear’, ‘nearest’}, optional

Interpolation method

Returns
arrayQuantity

Interpolated values

classmethod from_diagonal_response(energy_axis_true, energy_axis=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 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_axis_true, energy_axisMapAxis

True and reconstructed energy axis

Examples

If energy_true equals energy, you get a diagonal matrix:

from gammapy.irf import EDispKernel
from gammapy.maps import MapAxis

energy_true_axis = MapAxis.from_energy_edges(
        [0.5, 1, 2, 4, 6] * u.TeV, name="energy_true"
    )
edisp = EDispKernel.from_diagonal_response(energy_true_axis)
edisp.plot_matrix()

Example with different energy binnings:

energy_true_axis = MapAxis.from_energy_edges(
        [0.5, 1, 2, 4, 6] * u.TeV, name="energy_true"
    )
energy_axis = MapAxis.from_energy_edges([2, 4, 6] * u.TeV)
edisp = EDispKernel.from_diagonal_response(energy_true_axis, energy_axis)
edisp.plot_matrix()
classmethod from_gauss(energy_axis_true, energy_axis, sigma, bias, pdf_threshold=1e-06)[source]#

Create Gaussian energy dispersion matrix (EnergyDispersion).

Calls gammapy.irf.EnergyDispersion2D.from_gauss()

Parameters
energy_axis_trueQuantity

Bin edges of true energy axis

energy_axisQuantity

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

Returns
edispEDispKernel

Edisp kernel.

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

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

classmethod from_table(table, format='gadf-dl3')#

Read from Table.

Parameters
tableTable

Table with irf data

format{“gadf-dl3”}

Format specification

Returns
irfIRF

IRF class.

get_bias(energy_true)[source]#

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)[source]#

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)[source]#

Get mean reconstructed energy for a given true energy.

get_resolution(energy_true)[source]#

Get energy resolution for a given true energy.

The resolution is given as a percentage of the true energy

Parameters
energy_trueQuantity

True energy

integral(axis_name, **kwargs)#

Compute integral along a given axis

This method uses interpolation of the cumulative sum.

Parameters
axis_namestr

Along which axis to integrate.

**kwargsdict

Coordinates at which to evaluate the IRF

Returns
arrayQuantity

Returns 2D array with axes offset

integrate_log_log(axis_name, **kwargs)#

Integrate along a given axis.

This method uses log-log trapezoidal integration.

Parameters
axis_namestr

Along which axis to integrate.

**kwargsdict

Coordinates at which to evaluate the IRF

Returns
arrayQuantity

Returns 2D array with axes offset

interp_missing_data(axis_name)#

Interpolate missing data along a given axis

is_allclose(other, rtol_axes=0.001, atol_axes=1e-06, **kwargs)#

Compare two data IRFs for equivalency

Parameters
othergammapy.irfs.IRF

The irf to compare against

rtol_axesfloat

Relative tolerance for the axes comparison.

atol_axesfloat

Relative tolerance for the axes comparison.

**kwargsdict

keywords passed to numpy.allclose

Returns
is_allclosebool

Whether the IRF is all close.

normalize(axis_name)#

Normalise data in place along a given axis.

Parameters
axis_namestr

Along which axis to normalize.

pad(pad_width, axis_name, **kwargs)#

Pad irf along a given axis.

Parameters
pad_width{sequence, array_like, int}

Number of pixels padded to the edges of each axis.

axis_namestr

Which axis to downsample. By default spatial axes are padded.

**kwargsdict

Keyword argument forwarded to pad

Returns
irfIRF

Padded irf

pdf_in_safe_range(lo_threshold, hi_threshold)[source]#

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))[source]#

Quick-look summary plots.

Parameters
figsizetuple

Size of the figure.

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

Plot reconstruction bias.

See get_bias method.

Parameters
axAxes, optional

Plot axis

**kwargsdict

Kwyrow

Returns
axAxes, optional

Plot axis

plot_matrix(ax=None, add_cbar=False, **kwargs)[source]#

Plot PDF matrix.

Parameters
axAxes, optional

Axis

add_cbarbool

Add a colorbar to the plot.

Returns
axAxes

Axis

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

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

slice_by_idx(slices)#

Slice sub IRF from IRF object.

Parameters
slicesdict

Dict of axes names and slice object pairs. Contains one element for each non-spatial dimension. Axes not specified in the dict are kept unchanged.

Returns
slicedIRF

Sliced IRF object.

to_hdulist(format='ogip', **kwargs)[source]#

Convert RMF to FITS HDU list format.

Parameters
format{“ogip”, “ogip-sherpa”}

Format to use.

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)[source]#

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

Parameters
lo_thresholdQuantity, optional

Low reco energy threshold

hi_thresholdQuantity, optional

High reco energy threshold

to_table(format='ogip')[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 # noqa: E501

Parameters
format{“ogip”, “ogip-sherpa”}

Format to use.

Returns
tableTable

Matrix table

to_table_hdu(format='gadf-dl3')#

Convert to BinTableHDU.

Parameters
format{“gadf-dl3”}

Format specification

Returns
hduBinTableHDU

IRF data table hdu

to_unit(unit)#

Convert irf to different unit

Parameters
unitUnit or str

New unit

Returns
irfIRF

IRF with new unit and converted data

write(filename, format='ogip', **kwargs)[source]#

Write to file.

Parameters
filenamestr

Filename

format{“ogip”, “ogip-sherpa”}

Format to use.