FluxMaps

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

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

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

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_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.
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

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_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)

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.

classmethod from_hdulist(hdulist, hdu_bands=None, sed_type=None, checksum=False)

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)

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)

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)

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)

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)

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)

Slice flux maps by coordinate values

Parameters

slicesdict

Dict 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.

slice_by_energy(energy_min, energy_max)

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.

slice_by_idx(slices)

Slice flux maps by index.

Parameters

slicesdict

Dict 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.

slice_by_time(time_min, time_max)

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.

to_hdulist(sed_type=None, hdu_bands=None)

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)

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)

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.