FluxMaps#

class gammapy.estimators.FluxMaps(data, reference_model, meta=None, gti=None, filter_success_nan=True)[source]#

Bases: object

A flux map / points container.

It contains a set of Map objects that store the estimated flux as a function of energy as well as associated quantities (typically errors, upper limits, delta TS and possibly raw quantities such counts, excesses etc). It also contains a reference model to convert the flux values in different formats. Usually, this should be the model used to produce the flux map.

The associated map geometry can use a RegionGeom to store the equivalent of flux points, or a WcsGeom/HpxGeom to store an energy dependent flux map.

The container relies internally on the ‘Likelihood’ SED type defined in SED and offers convenience properties to convert to other flux formats, namely: dnde, flux, eflux or e2dnde. The conversion is done according to the reference model spectral shape.

Parameters:

datadict of Map

The maps dictionary. Expected entries are the following:

norm : the norm factor.
norm_err : optional, the error on the norm factor.
norm_errn : optional, the negative error on the norm factor.
norm_errp : optional, the positive error on the norm factor.
norm_ul : optional, the upper limit on the norm factor.
norm_scan : optional, the norm values of the test statistic scan.
stat_scan : optional, the test statistic scan values.
ts : optional, the delta test statistic associated with the flux value.
sqrt_ts : optional, the square root of the test statistic, when relevant.
success : optional, a boolean tagging the validity of the estimation.
n_dof : optional, the number of degrees of freedom used in TS computation
alpha : optional, normalisation factor to accounts for differences between the test region and the background
acceptance_off : optional, acceptance from the off region
acceptance_on : optional, acceptance from the on region

reference_modelSkyModel, optional

The reference model to use for conversions. If None, a model consisting of a point source with a power law spectrum of index 2 is assumed.

metadict, optional

Dict of metadata.

gtiGTI, optional

Maps GTI information.

filter_success_nanboolean, optional

Set fitted norm and error to NaN when the fit has not succeeded.

Attributes Summary

`acceptance_off`	The acceptance in the off region.
`acceptance_on`	The acceptance in the on region.
`alpha`	The normalisation, alpha, for differences between the on and off regions.
`available_quantities`	Available quantities.
`counts`	Predicted counts null hypothesis.
`dnde`	Return differential flux (dnde) SED values.
`dnde_err`	Return differential flux (dnde) SED errors.
`dnde_errn`	Return differential flux (dnde) SED negative errors.
`dnde_errp`	Return differential flux (dnde) SED positive errors.
`dnde_ref`	Reference differential flux.
`dnde_scan_values`	Fit statistic norm scan values.
`dnde_ul`	Return differential flux (dnde) SED upper limit.
`e2dnde`	Return differential energy flux (e2dnde) SED values.
`e2dnde_err`	Return differential energy flux (e2dnde) SED errors.
`e2dnde_errn`	Return differential energy flux (e2dnde) SED negative errors.
`e2dnde_errp`	Return differential energy flux (e2dnde) SED positive errors.
`e2dnde_ref`	Reference differential flux * energy ** 2.
`e2dnde_ul`	Return differential energy flux (e2dnde) SED upper limit.
`eflux`	Return energy flux (eflux) SED values.
`eflux_err`	Return energy flux (eflux) SED errors.
`eflux_errn`	Return energy flux (eflux) SED negative errors.
`eflux_errp`	Return energy flux (eflux) SED positive errors.
`eflux_ref`	Reference energy flux.
`eflux_ul`	Return energy flux (eflux) SED upper limits.
`energy_axis`	Energy axis as a `MapAxis`.
`energy_max`	Energy maximum.
`energy_min`	Energy minimum.
`energy_ref`	Reference energy.
`filter_success_nan`
`flux`	Return integral flux (flux) SED values.
`flux_err`	Return integral flux (flux) SED values.
`flux_errn`	Return integral flux (flux) SED negative errors.
`flux_errp`	Return integral flux (flux) SED positive errors.
`flux_ref`	Reference integral flux.
`flux_sensitivity`	Sensitivity given as the flux for which the significance is `self.meta["n_sigma_sensitivity]`.
`flux_ul`	Return integral flux (flux) SED upper limits.
`geom`	Reference map geometry as a `Geom`.
`has_any_ts`	Whether the flux estimate has either sqrt(TS) or test statistic defined.
`has_stat_profiles`	Whether the flux estimate has test statistic profiles.
`has_success`	Whether the flux estimate has the fit status.
`has_ul`	Whether the flux estimate has norm_ul defined.
`is_convertible_to_flux_sed_type`	Check whether differential SED type is convertible to integral SED type.
`is_ul`	Whether data is an upper limit.
`n_dof`	Number of degrees of freedom of the fit per energy bin.
`n_sigma`	n sigma
`n_sigma_ul`	n sigma UL.
`niter`	Number of iterations of fit.
`norm`	Norm values.
`norm_err`	Norm error.
`norm_errn`	Negative norm error.
`norm_errp`	Positive norm error.
`norm_sensitivity`	Norm sensitivity.
`norm_ul`	Norm upper limit.
`npred`	Predicted counts from best fit hypothesis.
`npred_background`	Predicted background counts from best fit hypothesis.
`npred_excess`	Predicted excess count from best fit hypothesis.
`npred_excess_err`	Predicted excess counts error.
`npred_excess_errn`	Predicted excess counts negative error.
`npred_excess_errp`	Predicted excess counts positive error.
`npred_excess_ref`	Predicted excess reference counts.
`npred_excess_ul`	Predicted excess counts upper limits.
`reference_model`	Reference model as a `SkyModel`.
`reference_model_default`	Reference model default as a `SkyModel`.
`reference_spectral_model`	Reference spectral model as a `SpectralModel`.
`sed_type_init`	Initial SED type.
`sed_type_plot_default`	Initial SED type.
`sqrt_ts`	sqrt(TS) as defined by:
`sqrt_ts_threshold_ul`	sqrt(TS) threshold for upper limits.
`stat`	Fit statistic value.
`stat_null`	Fit statistic value for the null hypothesis.
`stat_scan`	Fit statistic scan value.
`success`	Fit success flag.
`ts`	Test statistic map as a `Map` object.
`ts_scan`	Test statistic scan as a `Map` object.

Methods Summary

`all_quantities`(sed_type)	All quantities allowed for a given SED type.
`copy`([reference_model])	Deep copy.
`from_hdulist`(hdulist[, hdu_bands, sed_type, ...])	Create flux map dataset from list of HDUs.
`from_maps`(maps[, sed_type, reference_model, ...])	Create FluxMaps from a dictionary of maps.
`from_stack`(maps, axis[, meta])	Create flux points by stacking list of flux points.
`get_flux_points`([position])	Extract flux point at a given position.
`iter_by_axis`(axis_name)	Create a set of FluxMaps by splitting along an axis.
`read`(filename[, checksum])	Read map dataset from file.
`slice_by_coord`(slices)	Slice flux maps by coordinate values.
`slice_by_energy`(energy_min, energy_max)	Slice flux maps by coordinate values along the energy axis.
`slice_by_idx`(slices)	Slice flux maps by index.
`slice_by_time`(time_min, time_max)	Slice flux maps by coordinate values along the time axis.
`to_hdulist`([sed_type, hdu_bands])	Convert flux map to list of HDUs.
`to_maps`([sed_type])	Return maps in a given SED type.
`write`(filename[, filename_model, overwrite, ...])	Write flux map to file.

Attributes Documentation

acceptance_off#: The acceptance in the off region.

acceptance_on#: The acceptance in the on region.

alpha#: The normalisation, alpha, for differences between the on and off regions.

available_quantities#: Available quantities.

counts#: Predicted counts null hypothesis.

dnde#: Return differential flux (dnde) SED values.

dnde_err#: Return differential flux (dnde) SED errors.

dnde_errn#: Return differential flux (dnde) SED negative errors.

dnde_errp#: Return differential flux (dnde) SED positive errors.

dnde_ref#: Reference differential flux.

dnde_scan_values#: Fit statistic norm scan values.

dnde_ul#: Return differential flux (dnde) SED upper limit.

e2dnde#: Return differential energy flux (e2dnde) SED values.

e2dnde_err#: Return differential energy flux (e2dnde) SED errors.

e2dnde_errn#: Return differential energy flux (e2dnde) SED negative errors.

e2dnde_errp#: Return differential energy flux (e2dnde) SED positive errors.

e2dnde_ref#: Reference differential flux * energy ** 2.

e2dnde_ul#: Return differential energy flux (e2dnde) SED upper limit.

eflux#: Return energy flux (eflux) SED values.

eflux_err#: Return energy flux (eflux) SED errors.

eflux_errn#: Return energy flux (eflux) SED negative errors.

eflux_errp#: Return energy flux (eflux) SED positive errors.

eflux_ref#: Reference energy flux.

eflux_ul#: Return energy flux (eflux) SED upper limits.

energy_axis#: Energy axis as a MapAxis.

energy_max#

Energy maximum.

Returns:

energy_maxQuantity: Upper bound of energy bin.

energy_min#

Energy minimum.

Returns:

energy_minQuantity: Lower bound of energy bin.

energy_ref#

Reference energy.

Defined by energy_ref column in FluxPoints.table or computed as log center, if energy_min and energy_max columns are present in FluxEstimate.data.

Returns:

energy_refQuantity: Reference energy.

filter_success_nan#

flux#: Return integral flux (flux) SED values.

flux_err#: Return integral flux (flux) SED values.

flux_errn#: Return integral flux (flux) SED negative errors.

flux_errp#: Return integral flux (flux) SED positive errors.

flux_ref#: Reference integral flux.

flux_sensitivity#: Sensitivity given as the flux for which the significance is self.meta["n_sigma_sensitivity].

flux_ul#: Return integral flux (flux) SED upper limits.

geom#: Reference map geometry as a Geom.

has_any_ts#: Whether the flux estimate has either sqrt(TS) or test statistic defined.

has_stat_profiles#: Whether the flux estimate has test statistic profiles.

has_success#: Whether the flux estimate has the fit status.

has_ul#: Whether the flux estimate has norm_ul defined.

is_convertible_to_flux_sed_type#: Check whether differential SED type is convertible to integral SED type.

is_ul#: Whether data is an upper limit.

n_dof#: Number of degrees of freedom of the fit per energy bin.

n_sigma#: n sigma

n_sigma_ul#: n sigma UL.

niter#: Number of iterations of fit.

norm#: Norm values.

norm_err#: Norm error.

norm_errn#: Negative norm error.

norm_errp#: Positive norm error.

norm_sensitivity#: Norm sensitivity.

norm_ul#: Norm upper limit.

npred#: Predicted counts from best fit hypothesis.

npred_background#: Predicted background counts from best fit hypothesis.

npred_excess#: Predicted excess count from best fit hypothesis.

npred_excess_err#: Predicted excess counts error.

npred_excess_errn#: Predicted excess counts negative error.

npred_excess_errp#: Predicted excess counts positive error.

npred_excess_ref#: Predicted excess reference counts.

npred_excess_ul#: Predicted excess counts upper limits.

reference_model#: Reference model as a SkyModel.

reference_model_default#: Reference model default as a SkyModel.

reference_spectral_model#: Reference spectral model as a SpectralModel.

sed_type_init#: Initial SED type.

sed_type_plot_default#: Initial SED type.

sqrt_ts#

sqrt(TS) as defined by:

\[\begin{split}\sqrt{TS} = \left \{ \begin{array}{ll} -\sqrt{TS} & : \text{if} \ norm < 0 \\ \sqrt{TS} & : \text{else} \end{array} \right.\end{split}\]

Returns:

sqrt_tsMap: sqrt(TS) map.

sqrt_ts_threshold_ul#: sqrt(TS) threshold for upper limits.

stat#: Fit statistic value.

stat_null#: Fit statistic value for the null hypothesis.

stat_scan#: Fit statistic scan value.

success#: Fit success flag.

ts#: Test statistic map as a Map object.

ts_scan#: Test statistic scan as a Map object.

Methods Documentation

static all_quantities(sed_type)[source]#

All quantities allowed for a given SED type.

Parameters:

sed_type{“likelihood”, “dnde”, “e2dnde”, “flux”, “eflux”}: SED type.

Returns:

listlist of str: All allowed quantities for a given SED type.

copy(reference_model=None)[source]#

Deep copy.

Parameters:

reference_modelSkyModel, optional: The reference model to use for conversions. If None, the original model is copied. Flux maps have been obtained for a specific reference model. Changing it will change the fluxes. Handle with care.

Returns:

flux_mapsFluxMaps: Copied flux maps object.

classmethod from_hdulist(hdulist, hdu_bands=None, sed_type=None, checksum=False)[source]#

Create flux map dataset from list of HDUs.

Parameters:

hdulistHDUList: List of HDUs.
hdu_bandsstr, optional: Name of the HDU with the BANDS table. Default is ‘BANDS’ If set to None, each map should have its own hdu_band. Default is None.
sed_type{“dnde”, “flux”, “e2dnde”, “eflux”, “likelihood”}, optional: Sed type. Default is None.

Returns:

flux_mapsFluxMaps: Flux maps object.

classmethod from_maps(maps, sed_type=None, reference_model=None, gti=None, meta=None)[source]#

Create FluxMaps from a dictionary of maps.

Parameters:

mapsMaps: Maps object containing the input maps.
sed_typestr, optional: SED type of the input maps. If None, set to “likelihood”. Default is None.
reference_modelSkyModel, optional: Reference model to use for conversions. If None, a model consisting of a point source with a power law spectrum of index 2 is assumed. Default is None.
gtiGTI, optional: Maps GTI information. Default is None.
metadict: Meta dictionary.

Returns:

flux_mapsFluxMaps: Flux maps object.

classmethod from_stack(maps, axis, meta=None)[source]#

Create flux points by stacking list of flux points.

The first FluxPoints object in the list is taken as a reference to infer column names and units for the stacked object.

Parameters:

mapslist of FluxMaps: List of maps to stack.
axisMapAxis: New axis to create.
metadict, optional: Metadata of the resulting flux points. Default is None.

Returns:

flux_mapsFluxMaps: Stacked flux maps along axis.

get_flux_points(position=None)[source]#

Extract flux point at a given position.

Parameters:

positionSkyCoord: Position where the flux points are extracted.

Returns:

flux_pointsFluxPoints: Flux points object.

iter_by_axis(axis_name)[source]#

Create a set of FluxMaps by splitting along an axis.

Parameters:

axis_namestr: Name of the axis to split on.

Returns:

flux_mapsFluxMap: FluxMap iteration.

classmethod read(filename, checksum=False)[source]#

Read map dataset from file.

Parameters:

filenamestr: Filename to read from.
checksumbool: If True checks both DATASUM and CHECKSUM cards in the file headers. Default is False.

Returns:

flux_mapsFluxMaps: Flux maps object.

slice_by_coord(slices)[source]#

Slice flux maps by coordinate values.

Parameters:

slicesdict: Dictionary of axes names and astropy.Quantity or astropy.Time or slice object pairs. Contains one element for each non-spatial dimension. For integer indexing the corresponding axes is dropped from the map. Axes not specified in the dict are kept unchanged.

Returns:

flux_mapsFluxMaps: Sliced flux maps object.

Examples

>>> from gammapy.estimators import FluxPoints
>>> import astropy.units as u
>>> lc_1d = FluxPoints.read("$GAMMAPY_DATA/estimators/pks2155_hess_lc/pks2155_hess_lc.fits")
>>> slices = {"time": slice(2035.93*u.day, 2036.05*u.day)}
>>> sliced = lc_1d.slice_by_coord(slices)

slice_by_energy(energy_min, energy_max)[source]#

Slice flux maps by coordinate values along the energy axis.

Parameters:

energy_min, energy_maxQuantity: Energy bounds used to slice the flux map.

Returns:

flux_mapsFluxMaps: Sliced flux maps object.

Examples

>>> from gammapy.estimators import FluxPoints
>>> import astropy.units as u
>>> fp = FluxPoints.read("$GAMMAPY_DATA/estimators/crab_hess_fp/crab_hess_fp.fits")
>>> sliced = fp.slice_by_energy(energy_min=2*u.TeV, energy_max=10*u.TeV)

slice_by_idx(slices)[source]#

Slice flux maps by index.

Parameters:

slicesdict: Dictionary of axes names and integers or slice object pairs. Contains one element for each non-spatial dimension. For integer indexing the corresponding axes is dropped from the map. Axes not specified in the dict are kept unchanged.

Returns:

flux_mapsFluxMaps: Sliced flux maps object.

Examples

>>> from gammapy.estimators import FluxPoints
>>> import astropy.units as u
>>> fp = FluxPoints.read("$GAMMAPY_DATA/estimators/crab_hess_fp/crab_hess_fp.fits")
>>> slices = {"energy": slice(0, 2)}
>>> sliced = fp.slice_by_idx(slices)

slice_by_time(time_min, time_max)[source]#

Slice flux maps by coordinate values along the time axis.

Parameters:

time_min, time_maxTime: Time bounds used to slice the flux map.

Returns:

flux_mapsFluxMaps: Sliced flux maps object.

Examples

>>> from gammapy.estimators import FluxPoints
>>> import astropy.units as u
>>> lc_1d = FluxPoints.read("$GAMMAPY_DATA/estimators/pks2155_hess_lc/pks2155_hess_lc.fits")
>>> sliced = lc_1d.slice_by_time(time_min=2035.93*u.day, time_max=2036.05*u.day)

to_hdulist(sed_type=None, hdu_bands=None)[source]#

Convert flux map to list of HDUs.

For now, one cannot export the reference model.

Parameters:

sed_typestr, optional: SED type to convert to. If None, set to “likelihood”. Default is None.
hdu_bandsstr, optional: Name of the HDU with the BANDS table. Default is ‘BANDS’ If set to None, each map will have its own hdu_band. Default is None.

Returns:

hdulistHDUList: Map dataset list of HDUs.

to_maps(sed_type=None)[source]#

Return maps in a given SED type.

Parameters:

sed_type{“likelihood”, “dnde”, “e2dnde”, “flux”, “eflux”}, optional: SED type to convert to. If None, set to Likelihood. Default is None.

Returns:

mapsMaps: Maps object containing the requested maps.

write(filename, filename_model=None, overwrite=False, sed_type=None, checksum=False)[source]#

Write flux map to file.

Parameters:

filenamestr: Filename to write to.
filename_modelstr: Filename of the model (yaml format). If None, keep string before ‘.’ and add ‘_model.yaml’ suffix.
overwritebool, optional: Overwrite existing file. Default is False.
sed_typestr, optional: Sed type to convert to. If None, set to “likelihood”. Default is None.
checksumbool, optional: When True adds both DATASUM and CHECKSUM cards to the headers written to the file. Default is False.