ExcessMapEstimator#

class gammapy.estimators.ExcessMapEstimator(correlation_radius='0.1 deg', n_sigma=1, n_sigma_ul=2, selection_optional=None, energy_edges=None, correlate_off=True, spectral_model=None, n_sigma_sensitivity=5, gamma_min_sensitivity=10, bkg_syst_fraction_sensitivity=0.05, apply_threshold_sensitivity=False, sum_over_energy_groups=False)[source]#

Bases: Estimator

Computes correlated excess, significance and error maps from a map dataset.

If a model is set on the dataset the excess map estimator will compute the excess taking into account the predicted counts of the model.

Note

By default, the excess estimator correlates the off counts as well to avoid artifacts at the edges of the FoV for stacked on-off datasets. However, when the on-off dataset has been derived from a ring background estimate, this leads to the off counts being correlated twice. To avoid artifacts and the double correlation, the ExcessMapEstimator has to be applied per dataset and the resulting maps need to be stacked, taking the FoV cut into account.

Parameters:
correlation_radiusAngle

Correlation radius to use.

n_sigmafloat

Confidence level for the asymmetric errors expressed in number of sigma.

n_sigma_ulfloat

Confidence level for the upper limits expressed in number of sigma.

n_sigma_sensitivityfloat

Confidence level for the sensitivity expressed in number of sigma.

gamma_min_sensitivityfloat, optional

Minimum number of gamma-rays. Default is 10.

bkg_syst_fraction_sensitivityfloat, optional

Fraction of background counts that are above the gamma-ray counts. Default is 0.05.

apply_threshold_sensitivitybool

If True, use bkg_syst_fraction_sensitivity and gamma_min_sensitivity in the sensitivity computation. Default is False which is the same setting as the HGPS catalog.

selection_optionallist of str, optional

Which additional maps to estimate besides delta TS, significance and symmetric error. Available options are:

  • “all”: all the optional steps are executed.

  • “errn-errp”: estimate asymmetric errors.

  • “ul”: estimate upper limits.

  • “sensitivity”: estimate sensitivity for a given significance.

  • “alpha”: normalisation factor to accounts for differences between the on and off regions.

  • “acceptance_on”: acceptance from the on region.

  • “acceptance_off”: acceptange from the off region.

Default is None so the optional steps are not executed. Note: “alpha”, “acceptance_on” and “acceptance_off” can only be selected if the dataset is a MapDatasetOnOff.

energy_edgeslist of Quantity, optional

Edges of the target maps energy bins. The resulting bin edges won’t be exactly equal to the input ones, but rather the closest values to the energy axis edges of the parent dataset. Default is None: apply the estimator in each energy bin of the parent dataset. For further explanation see Estimators (DL4 to DL5, and DL6).

correlate_offbool

Correlate OFF events. Default is True.

spectral_modelSpectralModel

Spectral model used for the computation of the flux map. If None, a PowerLawSpectralModel of index 2 is assumed (default).

sum_over_energy_groupsbool

Only used if energy_edges is None. If False, apply the estimator in each energy bin of the parent dataset. If True, apply the estimator in only one bin defined by the energy edges of the parent dataset. Default is False.

Examples

>>> from gammapy.datasets import MapDataset
>>> from gammapy.estimators import ExcessMapEstimator
>>> dataset = MapDataset.read("$GAMMAPY_DATA/cta-1dc-gc/cta-1dc-gc.fits.gz")
>>> estimator = ExcessMapEstimator(correlation_radius="0.1 deg")
>>> result = estimator.run(dataset)
>>> print(result)
FluxMaps
--------

  geom                   : WcsGeom
  axes                   : ['lon', 'lat', 'energy']
  shape                  : (np.int64(320), np.int64(240), 1)
  quantities             : ['npred', 'npred_excess', 'counts', 'ts', 'sqrt_ts', 'norm', 'norm_err']
  ref. model             : pl
  n_sigma                : 1
  n_sigma_ul             : 2
  sqrt_ts_threshold_ul   : 2
  sed type init          : likelihood

Attributes Summary

Methods Summary

copy()

Copy estimator.

estimate_excess_map(dataset, reco_exposure)

Estimate excess and test statistic maps for a single dataset.

estimate_exposure_reco_energy(dataset, ...)

Estimate exposure map in reconstructed energy for a single dataset assuming the given spectral_model shape.

estimate_kernel(dataset)

Get the convolution kernel for the input dataset.

estimate_mask_default(dataset)

Get mask used by the estimator.

run(dataset)

Compute correlated excess, Li & Ma significance and flux maps.

Attributes Documentation

config_parameters#

Configuration parameters.

correlation_radius#
selection_optional#
tag = 'ExcessMapEstimator'#

Methods Documentation

copy()#

Copy estimator.

estimate_excess_map(dataset, reco_exposure)[source]#

Estimate excess and test statistic maps for a single dataset.

If exposure is defined, a flux map is also computed.

Parameters:
datasetMapDataset

Map dataset.

estimate_exposure_reco_energy(dataset, kernel, mask, reco_exposure)[source]#

Estimate exposure map in reconstructed energy for a single dataset assuming the given spectral_model shape.

Parameters:
datasetMapDataset

Map dataset.

kernelTophat2DKernel

Kernel.

maskMap

Mask map.

Returns:
reco_exposureMap

Reconstructed exposure map.

estimate_kernel(dataset)[source]#

Get the convolution kernel for the input dataset.

Parameters:
datasetMapDataset

Input dataset.

Returns:
kernelTophat2DKernel

Kernel.

static estimate_mask_default(dataset)[source]#

Get mask used by the estimator.

Parameters:
datasetMapDataset

Input dataset.

Returns:
maskMap

Mask map.

run(dataset)[source]#

Compute correlated excess, Li & Ma significance and flux maps.

If a model is set on the dataset the excess map estimator will compute the excess taking into account the predicted counts of the model.

Parameters:
datasetMapDataset or MapDatasetOnOff

Map dataset.

Returns:
mapsFluxMaps

Flux maps.