MapDatasetOnOff

class gammapy.datasets.MapDatasetOnOff(models=None, counts=None, counts_off=None, acceptance=None, acceptance_off=None, exposure=None, mask_fit=None, psf=None, edisp=None, name=None, mask_safe=None, gti=None, meta_table=None)[source]

Bases: gammapy.datasets.MapDataset

Map dataset for on-off likelihood fitting.

Parameters
modelsModels

Source sky models.

countsWcsNDMap

Counts cube

counts_offWcsNDMap

Ring-convolved counts cube

acceptanceWcsNDMap

Acceptance from the IRFs

acceptance_offWcsNDMap

Acceptance off

exposureWcsNDMap

Exposure cube

mask_fitWcsNDMap

Mask to apply to the likelihood for fitting.

psfPSFKernel

PSF kernel

edispEDispKernel

Energy dispersion

mask_safeWcsNDMap

Mask defining the safe data range.

gtiGTI

GTI of the observation or union of GTI if it is a stacked observation

meta_tableTable

Table listing informations on observations used to create the dataset. One line per observation for stacked datasets.

namestr

Name of the dataset.

See also

MapDatasetOn, SpectrumDataset, FluxPointsDataset

Attributes Summary

alpha

Exposure ratio between signal and background regions

background

Predicted background in the on region.

background_model

counts

A lazy FITS data descriptor.

data_shape

Shape of the counts or background data (tuple)

edisp

A lazy FITS data descriptor.

evaluators

Model evaluators

excess

Excess (counts - alpha * counts_off)

exposure

A lazy FITS data descriptor.

mask

Combined fit and safe mask

mask_fit

A lazy FITS data descriptor.

mask_safe

A lazy FITS data descriptor.

models

Models (Models).

name

psf

A lazy FITS data descriptor.

stat_type

tag

Methods Summary

copy([name])

A deep copy.

create(geom[, energy_axis_true, migra_axis, …])

Create a MapDataset object with zero filled maps.

cutout(position, width[, mode, name])

Cutout map dataset.

downsample()

Downsample map dataset.

fake(background_model[, random_state])

Simulate fake counts (on and off) for the current model and reduced IRFs.

from_dict(data, models[, lazy, cache])

Create from dicts and models list generated from YAML serialization.

from_geoms(geom, geom_exposure, geom_psf, …)

Create a MapDatasetOnOff object with zero filled maps according to the specified geometries

from_hdulist(hdulist[, name])

Create map dataset from list of HDUs.

from_map_dataset(dataset, acceptance, …[, …])

Create spectrum dataseton off from another dataset.

info_dict([region])

Basic info dict with summary statistics

npred()

Predicted source and background counts (Map).

pad()

Pad the spatial dimensions of the dataset.

plot_residuals([method, smooth_kernel, …])

Plot spatial and spectral residuals.

read(filename[, name, lazy, cache])

Read map dataset from file.

reset_data_cache()

Reset data cache to free memory space

residuals([method])

Compute residuals map.

slice_by_idx(slices[, name])

Slice sub dataset.

stack(other)

Stack another dataset in place.

stat_array()

Likelihood per bin given the current model parameters

stat_sum()

Total likelihood given the current model parameters.

to_dict([filename])

Convert to dict for YAML serialization.

to_hdulist()

Convert map dataset to list of HDUs.

to_image([name])

Create images by summing over the energy axis.

to_spectrum_dataset(on_region[, …])

Return a ~gammapy.datasets.SpectrumDatasetOnOff from on_region.

write(filename[, overwrite])

Write map dataset to file.

Attributes Documentation

alpha

Exposure ratio between signal and background regions

background

Predicted background in the on region.

Notice that this definition is valid under the assumption of cash statistic.

background_model
counts

A lazy FITS data descriptor.

Parameters
cachebool

Whether to cache the data.

data_shape

Shape of the counts or background data (tuple)

edisp

A lazy FITS data descriptor.

Parameters
cachebool

Whether to cache the data.

evaluators

Model evaluators

excess

Excess (counts - alpha * counts_off)

exposure

A lazy FITS data descriptor.

Parameters
cachebool

Whether to cache the data.

mask

Combined fit and safe mask

mask_fit

A lazy FITS data descriptor.

Parameters
cachebool

Whether to cache the data.

mask_safe

A lazy FITS data descriptor.

Parameters
cachebool

Whether to cache the data.

models

Models (Models).

name
psf

A lazy FITS data descriptor.

Parameters
cachebool

Whether to cache the data.

stat_type = 'wstat'
tag = 'MapDatasetOnOff'

Methods Documentation

copy(name=None)

A deep copy.

classmethod create(geom, energy_axis_true=None, migra_axis=None, rad_axis=None, binsz_irf=None, reference_time='2000-01-01', name=None, meta_table=None, **kwargs)

Create a MapDataset object with zero filled maps.

Parameters
geomWcsGeom

Reference target geometry in reco energy, used for counts and background maps

energy_axis_trueMapAxis

True energy axis used for IRF maps

migra_axisMapAxis

If set, this provides the migration axis for the energy dispersion map. If not set, an EDispKernelMap is produced instead. Default is None

rad_axisMapAxis

Rad axis for the psf map

binsz_irffloat

IRF Map pixel size in degrees.

reference_timeTime

the reference time to use in GTI definition

namestr

Name of the returned dataset.

meta_tableTable

Table listing informations on observations used to create the dataset. One line per observation for stacked datasets.

Returns
empty_mapsMapDataset

A MapDataset containing zero filled maps

cutout(position, width, mode='trim', name=None)[source]

Cutout map dataset.

Parameters
positionSkyCoord

Center position of the cutout region.

widthtuple of Angle

Angular sizes of the region in (lon, lat) in that specific order. If only one value is passed, a square region is extracted.

mode{‘trim’, ‘partial’, ‘strict’}

Mode option for Cutout2D, for details see Cutout2D.

namestr

Name of the new dataset.

Returns
cutoutMapDatasetOnOff

Cutout map dataset.

downsample()[source]

Downsample map dataset.

The PSFMap and EDispKernelMap are not downsampled, except if a corresponding axis is given.

Parameters
factorint

Downsampling factor.

axisstr

Which axis to downsample. By default only spatial axes are downsampled.

namestr

Name of the downsampled dataset.

Returns
datasetMapDataset

Downsampled map dataset.

fake(background_model, random_state='random-seed')[source]

Simulate fake counts (on and off) for the current model and reduced IRFs.

This method overwrites the counts defined on the dataset object.

Parameters
random_state{int, ‘random-seed’, ‘global-rng’, RandomState}

Defines random number generator initialisation. Passed to get_random_state.

classmethod from_dict(data, models, lazy=False, cache=True)

Create from dicts and models list generated from YAML serialization.

classmethod from_geoms(geom, geom_exposure, geom_psf, geom_edisp, reference_time='2000-01-01', name=None, **kwargs)[source]

Create a MapDatasetOnOff object with zero filled maps according to the specified geometries

Parameters
geomgammapy.maps.WcsGeom

geometry for the counts, counts_off, acceptance and acceptance_off maps

geom_exposuregammapy.maps.WcsGeom

geometry for the exposure map

geom_psfgammapy.maps.WcsGeom

geometry for the psf map

geom_edispgammapy.maps.WcsGeom

geometry for the energy dispersion kernel map. If geom_edisp has a migra axis, this wil create an EDispMap instead.

reference_timeTime

the reference time to use in GTI definition

namestr

Name of the returned dataset.

Returns
empty_mapsMapDatasetOnOff

A MapDatasetOnOff containing zero filled maps

classmethod from_hdulist(hdulist, name=None)[source]

Create map dataset from list of HDUs.

Parameters
hdulistHDUList

List of HDUs.

namestr

Name of the new dataset.

Returns
datasetMapDataset

Map dataset.

classmethod from_map_dataset(dataset, acceptance, acceptance_off, counts_off=None, name=None)[source]

Create spectrum dataseton off from another dataset.

Parameters
datasetMapDataset

Spectrum dataset defining counts, edisp, aeff, livetime etc.

acceptanceMap

Relative background efficiency in the on region.

acceptance_offMap

Relative background efficiency in the off region.

counts_offMap

Off counts map . If the dataset provides a background model, and no off counts are defined. The off counts are deferred from counts_off / alpha.

namestr

Name of the returned dataset.

Returns
datasetMapDatasetOnOff

Map dataset on off.

info_dict(region=None)[source]

Basic info dict with summary statistics

If a region is passed, then a spectrum dataset is extracted, and the corresponding info returned.

Parameters
regionSkyRegion, optional

the input ON region on which to extract the spectrum

Returns
info_dictdict

Dictionary with summary info.

npred()

Predicted source and background counts (Map).

pad()[source]

Pad the spatial dimensions of the dataset.

The padding only applies to counts, masks, background and exposure.

Counts, background and masks are padded with zeros, exposure is padded with edge value.

Parameters
pad_width{sequence, array_like, int}

Number of pixels padded to the edges of each axis.

namestr

Name of the padded dataset.

Returns
mapMap

Padded map.

plot_residuals(method='diff', smooth_kernel='gauss', smooth_radius='0.1 deg', region=None, figsize=(12, 4), **kwargs)

Plot spatial and spectral residuals.

The spectral residuals are extracted from the provided region, and the normalization used for the residuals computation can be controlled using the method parameter. If no region is passed, only the spatial residuals are shown.

Parameters
method{“diff”, “diff/model”, “diff/sqrt(model)”}

Method used to compute the residuals, see MapDataset.residuals()

smooth_kernel{‘gauss’, ‘box’}

Kernel shape.

smooth_radius: `~astropy.units.Quantity`, str or float

Smoothing width given as quantity or float. If a float is given it is interpreted as smoothing width in pixels.

region: `~regions.Region`

Region (pixel or sky regions accepted)

figsizetuple

Figure size used for the plotting.

**kwargsdict

Keyword arguments passed to imshow.

Returns
ax_image, ax_specAxes,

Image and spectrum axes.

classmethod read(filename, name=None, lazy=False, cache=True)

Read map dataset from file.

Parameters
filenamestr

Filename to read from.

namestr

Name of the new dataset.

lazybool

Whether to lazy load data into memory

cachebool

Whether to cache the data after loading.

Returns
datasetMapDataset

Map dataset.

reset_data_cache()

Reset data cache to free memory space

residuals(method='diff')

Compute residuals map.

Parameters
method: {“diff”, “diff/model”, “diff/sqrt(model)”}
Method used to compute the residuals. Available options are:
  • “diff” (default): data - model

  • “diff/model”: (data - model) / model

  • “diff/sqrt(model)”: (data - model) / sqrt(model)

Returns
residualsgammapy.maps.WcsNDMap

Residual map.

slice_by_idx(slices, name=None)[source]

Slice sub dataset.

The slicing only applies to the maps that define the corresponding axes.

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.

namestr

Name of the sliced dataset.

Returns
map_outMap

Sliced map object.

stack(other)[source]

Stack another dataset in place.

The acceptance of the stacked dataset is normalized to 1, and the stacked acceptance_off is scaled so that:

\[\alpha_\text{stacked} = \frac{1}{a_\text{off}} = \frac{\alpha_1\text{OFF}_1 + \alpha_2\text{OFF}_2}{\text{OFF}_1 + OFF_2}\]
Parameters
otherMapDatasetOnOff

Other dataset

stat_array()[source]

Likelihood per bin given the current model parameters

stat_sum()[source]

Total likelihood given the current model parameters.

to_dict(filename='')

Convert to dict for YAML serialization.

to_hdulist()[source]

Convert map dataset to list of HDUs.

Returns
hdulistHDUList

Map dataset list of HDUs.

to_image(name=None)[source]

Create images by summing over the energy axis.

name : str

Returns
datasetMapDatasetOnOff

Map dataset containing images.

to_spectrum_dataset(on_region, containment_correction=False, name=None)[source]

Return a ~gammapy.datasets.SpectrumDatasetOnOff from on_region.

Counts and OFF counts are summed in the on_region.

Acceptance is the average of all acceptances while acceptance OFF is taken such that number of excess is preserved in the on_region.

Effective area is taken from the average exposure divided by the livetime. Here we assume it is the sum of the GTIs.

The energy dispersion kernel is obtained at the on_region center. Only regions with centers are supported.

The model is not exported to the ~gammapy.dataset.SpectrumDataset. It must be set after the dataset extraction.

Parameters
on_regionSkyRegion

the input ON region on which to extract the spectrum

containment_correctionbool

Apply containment correction for point sources and circular on regions

namestr

Name of the new dataset.

Returns
datasetSpectrumDatasetOnOff

the resulting reduced dataset

write(filename, overwrite=False)

Write map dataset to file.

Parameters
filenamestr

Filename to write to.

overwritebool

Overwrite file if it exists.