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.