MapDatasetOnOff

class gammapy.datasets.MapDatasetOnOff

Bases: MapDataset

Map dataset for on-off likelihood fitting.

It bundles together the binned on and off counts, the binned IRFs as well as the on and off acceptances.

A safe mask and a fit mask can be added to exclude bins during the analysis.

It uses the Wstat statistic (see wstat), therefore no background model is needed.

For more information see Datasets (DL4).

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 information on observations used to create the dataset. One line per observation for stacked datasets.

namestr

Name of the dataset.

metaMapDatasetMetaData

Associated meta data container

See also

MapDataset, SpectrumDataset, FluxPointsDataset.

Attributes Summary

alpha	Exposure ratio between signal and background regions.
background	Computed as alpha * n_off.
tag

Methods Summary

cutout(position, width[, mode, name])	Cutout map dataset.
downsample(factor[, axis_name, name])	Downsample map dataset.
fake(npred_background[, random_state])	Simulate fake counts (on and off) for the current model and reduced IRFs.
from_geoms(geom[, geom_exposure, geom_psf, ...])	Create an empty MapDatasetOnOff object according to the specified geometries.
from_hdulist(hdulist[, name, format])	Create map dataset from list of HDUs.
from_map_dataset(dataset, acceptance, ...[, ...])	Create on off dataset from a map dataset.
info_dict([in_safe_data_range])	Basic info dict with summary statistics.
npred_background()	Predicted background counts estimated from the marginalized likelihood estimate.
npred_off()	Predicted counts in the off region; mu_bkg/alpha.
pad()	Not implemented for MapDatasetOnOff.
resample_energy_axis(energy_axis[, name])	Resample MapDatasetOnOff over reconstructed energy edges.
slice_by_idx(slices[, name])	Slice sub dataset.
stack(other[, nan_to_num])	Stack another dataset in place.
to_hdulist()	Convert map dataset to list of HDUs.
to_map_dataset([name])	Convert a MapDatasetOnOff to a MapDataset.
to_spectrum_dataset(on_region[, ...])	Return a ~gammapy.datasets.SpectrumDatasetOnOff from on_region.

Attributes Documentation

alpha

Exposure ratio between signal and background regions.

See WStat : Poisson data with background measurement.

Returns:

alphaMap

Alpha map.

background

Computed as alpha * n_off.

See WStat : Poisson data with background measurement.

Returns:

backgroundMap

Background map.

tag = 'MapDatasetOnOff'

Methods Documentation

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

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. Default is “trim”.

namestr, optional

Name of the new dataset. Default is None.

Returns:

cutoutMapDatasetOnOff

Cutout map dataset.

downsample(factor, axis_name=None, name=None)

Downsample map dataset.

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

Parameters:

factorint

Downsampling factor.

axis_namestr, optional

Which non-spatial axis to downsample. By default, only spatial axes are downsampled. Default is None.

namestr, optional

Name of the downsampled dataset. Default is None.

Returns:

datasetMapDatasetOnOff

Downsampled map dataset.

fake(npred_background, random_state='random-seed')

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

This method overwrites the counts defined on the dataset object.

Parameters:

npred_backgroundMap

Expected number of background counts in the on region.

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

Defines random number generator initialisation. Passed to get_random_state. Default is “random-seed”.

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

Create an empty MapDatasetOnOff object according to the specified geometries.

Parameters:

geomgammapy.maps.WcsGeom

Geometry for the counts, counts_off, acceptance and acceptance_off maps.

geom_exposuregammapy.maps.WcsGeom, optional

Geometry for the exposure map. Default is None.

geom_psfgammapy.maps.WcsGeom, optional

Geometry for the PSF map. Default is None.

geom_edispgammapy.maps.WcsGeom, optional

Geometry for the energy dispersion kernel map. If geom_edisp has a migra axis, this will create an EDispMap instead. Default is None.

reference_timeTime

The reference time to use in GTI definition. Default is “2000-01-01”.

namestr, optional

Name of the returned dataset. Default is None.

**kwargsdict, optional

Keyword arguments to be passed.

Returns:

empty_mapsMapDatasetOnOff

A MapDatasetOnOff containing zero filled maps.

classmethod from_hdulist(hdulist, name=None, format='gadf')

Create map dataset from list of HDUs.

Parameters:

hdulistHDUList

List of HDUs.

namestr, optional

Name of the new dataset. Default is None.

format{“gadf”}

Format the hdulist is given in. Default is “gadf”.

Returns:

datasetMapDatasetOnOff

Map dataset.

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

Create on off dataset from a map 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, optional

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. Default is None.

namestr, optional

Name of the returned dataset. Default is None.

Returns:

datasetMapDatasetOnOff

Map dataset on off.

info_dict(in_safe_data_range=True)

Basic info dict with summary statistics.

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

Parameters:

in_safe_data_rangebool

Whether to sum only in the safe energy range. Default is True.

Returns:

info_dictdict

Dictionary with summary info.

npred_background()

Predicted background counts estimated from the marginalized likelihood estimate.

See WStat : Poisson data with background measurement.

Returns:

npred_backgroundMap

Predicted background counts.

npred_off()

Predicted counts in the off region; mu_bkg/alpha.

See WStat : Poisson data with background measurement.

Returns:

npred_offMap

Predicted off counts.

pad()

Not implemented for MapDatasetOnOff.

resample_energy_axis(energy_axis, name=None)

Resample MapDatasetOnOff over reconstructed energy edges.

Counts are summed taking into account safe mask.

Parameters:

energy_axisMapAxis

New reco energy axis.

namestr, optional

Name of the new dataset. Default is None.

Returns:

datasetSpectrumDataset

Resampled spectrum dataset.

slice_by_idx(slices, name=None)

Slice sub dataset.

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

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.

namestr, optional

Name of the sliced dataset. Default is None.

Returns:

map_outMap

Sliced map object.

stack(other, nan_to_num=True)

Stack another dataset in place.

Safe mask is applied to the other dataset to compute the stacked counts data, counts outside the safe mask are lost (as for stack).

The acceptance of the stacked dataset is obtained by stacking the acceptance weighted by the other mask_safe onto the current unweighted acceptance.

Note that the masking is not applied to the current dataset. If masking needs to be applied to it, use to_masked() first.

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}.\]

For details, see Stacking Multiple Datasets.

Parameters:

otherMapDatasetOnOff

Other dataset.

nan_to_numbool

Non-finite values are replaced by zero if True. Default is True.

to_hdulist()

Convert map dataset to list of HDUs.

Returns:

hdulistHDUList

Map dataset list of HDUs.

to_map_dataset(name=None)

Convert a MapDatasetOnOff to a MapDataset.

The background model template is taken as alpha * counts_off.

Parameters:

namestr, optional

Name of the new dataset. Default is None.

Returns:

datasetMapDataset

Map dataset with cash statistics.

to_spectrum_dataset(on_region, containment_correction=False, name=None)

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.

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

The models are not exported to the ~gammapy.dataset.SpectrumDatasetOnOff. 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. Default is False.

namestr, optional

Name of the new dataset. Default is None.

Returns:

datasetSpectrumDatasetOnOff

The resulting reduced dataset.

__init__(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, meta=None, stat_type='wstat')

classmethod __new__(*args, **kwargs)