SpectrumDatasetOnOff¶

class gammapy.datasets.SpectrumDatasetOnOff(models=None, counts=None, counts_off=None, livetime=None, aeff=None, edisp=None, mask_safe=None, mask_fit=None, acceptance=None, acceptance_off=None, name=None, gti=None)[source]¶

Bases: gammapy.datasets.SpectrumDataset

Spectrum dataset for on-off likelihood fitting.

The on-off spectrum dataset bundles reduced counts data, off counts data, with a spectral model, relative background efficiency and instrument response functions to compute the fit-statistic given the current model and data.

Parameters

modelsModels: Fit model
countsRegionNDMap: ON Counts spectrum
counts_offRegionNDMap: OFF Counts spectrum
livetimeQuantity: Livetime
aeffEffectiveAreaTable: Effective area
edispEDispKernel: Energy dispersion
mask_safeRegionNDMap: Mask defining the safe data range.
mask_fitRegionNDMap: Mask to apply to the likelihood for fitting.
acceptanceRegionNDMap or float: Relative background efficiency in the on region.
acceptance_offRegionNDMap or float: Relative background efficiency in the off region.
namestr: Name of the dataset.
gtiGTI: GTI of the observation or union of GTI if it is a stacked observation

See also

SpectrumDataset, FluxPointsDataset, MapDataset

Attributes Summary

`alpha`	Exposure ratio between signal and background regions
`background`
`data_shape`	Shape of the counts data
`energy_range`	Energy range defined by the safe mask
`evaluators`	Model evaluators
`excess`	Excess (counts - alpha * counts_off)
`exposure`	Excess (aeff * livetime)
`mask`	Combined fit and safe mask
`mask_safe`
`models`	Models (`gammapy.modeling.models.Models`).
`name`
`stat_type`
`tag`

Methods Summary

`copy`(self[, name])	A deep copy.
`create`(e_reco[, e_true, region, …])	Create empty SpectrumDatasetOnOff.
`fake`(self, background_model[, random_state])	Simulate fake counts for the current model and reduced irfs.
`from_dict`(data, models)	Create flux point dataset from dict.
`from_ogip_files`(filename)	Read `SpectrumDatasetOnOff` from OGIP files.
`from_spectrum_dataset`(dataset, acceptance, …)	Create spectrum dataseton off from another dataset.
`info_dict`(self[, in_safe_energy_range])	Info dict with summary statistics, summed over energy
`npred`(self)	Return npred map (model + background)
`npred_sig`(self)	Predicted counts from source model (`RegionNDMap`).
`peek`(self[, figsize])	Quick-look summary plots.
`plot_counts`(self[, ax])	Plot predicted and detected counts.
`plot_fit`(self)	Plot counts and residuals in two panels.
`plot_residuals`(self[, method, ax])	Plot residuals.
`read`(filename)	Read from file
`residuals`(self[, method])	Compute the spectral residuals.
`stack`(self, other)	Stack this dataset with another one.
`stat_array`(self)	Likelihood per bin given the current model parameters
`stat_sum`(self)	Total statistic given the current model parameters.
`to_dict`(self, filename, \args, \\*kwargs)	Convert to dict for YAML serialization.
`to_ogip_files`(self[, outdir, use_sherpa, …])	Write OGIP files.
`write`(self, filename, overwrite)	Write spectrum dataset on off to file.

Attributes Documentation

alpha¶: Exposure ratio between signal and background regions

background¶

data_shape¶: Shape of the counts data

energy_range¶: Energy range defined by the safe mask

evaluators¶: Model evaluators

excess¶: Excess (counts - alpha * counts_off)

exposure¶: Excess (aeff * livetime)

mask¶: Combined fit and safe mask

mask_safe¶

models¶: Models (gammapy.modeling.models.Models).

name¶

stat_type = 'wstat'¶

tag = 'SpectrumDatasetOnOff'¶

Methods Documentation

copy(self, name=None)¶: A deep copy.

classmethod create(e_reco, e_true=None, region=None, reference_time='2000-01-01', name=None)[source]¶

Create empty SpectrumDatasetOnOff.

Empty containers are created with the correct geometry. counts, counts_off and aeff are zero and edisp is diagonal.

The safe_mask is set to False in every bin.

Parameters

e_recoQuantity: edges of counts vector
e_trueQuantity: edges of effective area table. If not set use reco energy values. Default : None
regionSkyRegion: Region to define the dataset for.
reference_timeTime: reference time of the dataset, Default is “2000-01-01”

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

Simulate fake counts for the current model and reduced irfs.

This method overwrites the counts and off counts defined on the dataset object.

Parameters

background_modelRegionNDMap: Background model.
random_state{int, ‘random-seed’, ‘global-rng’, RandomState}: Defines random number generator initialisation. Passed to get_random_state.

classmethod from_dict(data, models)[source]¶

Create flux point dataset from dict.

Parameters

datadict: Dict containing data to create dataset from.
modelslist of SkyModel: List of model components.

Returns

datasetSpectrumDatasetOnOff: Spectrum dataset on off.

classmethod from_ogip_files(filename)[source]¶

Read SpectrumDatasetOnOff from OGIP files.

BKG file, ARF, and RMF must be set in the PHA header and be present in the same folder.

The naming scheme is fixed to the following scheme:

PHA file is named pha_obs{name}.fits
BKG file is named bkg_obs{name}.fits
ARF file is named arf_obs{name}.fits
RMF file is named rmf_obs{name}.fits with {name} the dataset name.

Parameters

filenamestr: OGIP PHA file to read

classmethod from_spectrum_dataset(dataset, acceptance, acceptance_off, counts_off=None)[source]¶

Create spectrum dataseton off from another dataset.

Parameters

datasetSpectrumDataset: Spectrum dataset defining counts, edisp, aeff, livetime etc.
acceptancearray or float: Relative background efficiency in the on region.
acceptance_offarray or float: Relative background efficiency in the off region.
counts_offRegionNDMap: Off counts spectrum . If the dataset provides a background model, and no off counts are defined. The off counts are deferred from counts_off / alpha.

Returns

datasetSpectrumDatasetOnOff: Spectrum dataset on off.

info_dict(self, in_safe_energy_range=True)[source]¶

Info dict with summary statistics, summed over energy

Parameters

in_safe_energy_rangebool: Whether to sum only in the safe energy range

Returns

info_dictdict: Dictionary with summary info.

npred(self)¶: Return npred map (model + background)

npred_sig(self)¶: Predicted counts from source model (RegionNDMap).

peek(self, figsize=(16, 4))¶: Quick-look summary plots.

plot_counts(self, ax=None)¶

Plot predicted and detected counts.

Parameters

axAxes: Axes object.

Returns

axAxes: Axes object.

plot_fit(self)¶

Plot counts and residuals in two panels.

Calls plot_counts and plot_residuals.

plot_residuals(self, method='diff', ax=None, **kwargs)¶

Plot residuals.

Parameters

axAxes: Axes object.
method{“diff”, “diff/model”, “diff/sqrt(model)”}: Normalization used to compute the residuals, see SpectrumDataset.residuals()
**kwargsdict: Keywords passed to RegionNDMap.plot()

Returns

axAxes: Axes object.

classmethod read(filename)[source]¶

Read from file

For now, filename is assumed to the name of a PHA file where BKG file, ARF, and RMF names must be set in the PHA header and be present in the same folder

Parameters

filenamestr: OGIP PHA file to read

residuals(self, method='diff')¶

Compute the spectral residuals.

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

residualsRegionNDMap: Residual spectrum

stack(self, other)[source]¶

Stack this dataset with another one.

Safe mask is applied to compute the stacked counts vector. Counts outside each dataset safe mask are lost.

Stacking is performed in-place.

The stacking of 2 datasets is implemented as follows. Here, \(k\) denotes a bin in reconstructed energy and \(j = {1,2}\) is the dataset number

The mask_safe of each dataset is defined as:

\[\begin{split}\epsilon_{jk} =\left\{\begin{array}{cl} 1, & \mbox{if k is inside the energy thresholds}\\ 0, & \mbox{otherwise} \end{array}\right.\end{split}\]

Then the total counts and counts_off are computed according to:

\[ \begin{align}\begin{aligned}\overline{\mathrm{n_{on}}}_k = \mathrm{n_{on}}_{1k} \cdot \epsilon_{1k} + \mathrm{n_{on}}_{2k} \cdot \epsilon_{2k}\\\overline{\mathrm{n_{off}}}_k = \mathrm{n_{off}}_{1k} \cdot \epsilon_{1k} + \mathrm{n_{off}}_{2k} \cdot \epsilon_{2k}\end{aligned}\end{align} \]

The stacked safe_mask is then:

\[\overline{\epsilon_k} = \epsilon_{1k} OR \epsilon_{2k}\]

In each energy bin \(k\), the count excess is computed taking into account the ON acceptance, \(a_{on}_k\) and the OFF one: acceptance_off, \(a_{off}_k\). They define the \(\alpha_k=a_{on}_k/a_{off}_k\) factors such that \(n_{ex}_k = n_{on}_k - \alpha_k n_{off}_k\). We define the stacked value of \(\overline{{a}_{on}}_k = 1\) so that:

\[\overline{{a}_{off}}_k = \frac{\overline{\mathrm {n_{off}}}}{\alpha_{1k} \cdot \mathrm{n_{off}}_{1k} \cdot \epsilon_{1k} + \alpha_{2k} \cdot \mathrm{n_{off}}_{2k} \cdot \epsilon_{2k}}\]

Please refer to the IRFStacker for the description of how the IRFs are stacked.

Parameters

otherSpectrumDatasetOnOff: the dataset to stack to the current one

Examples

>>> from gammapy.datasets import SpectrumDatasetOnOff
>>> obs_ids = [23523, 23526, 23559, 23592]
>>> datasets = []
>>> for obs in obs_ids:
>>>     filename = "$GAMMAPY_DATA/joint-crab/spectra/hess/pha_obs{}.fits"
>>>     ds = SpectrumDatasetOnOff.from_ogip_files(filename.format(obs))
>>>     datasets.append(ds)
>>> stacked = datasets[0]
>>> for ds in datasets[1:]:
>>>     stacked.stack(ds)
>>> print(stacked.livetime)
6313.8116406202325 s

stat_array(self)[source]¶: Likelihood per bin given the current model parameters

stat_sum(self)¶: Total statistic given the current model parameters.

to_dict(self, filename, *args, **kwargs)[source]¶: Convert to dict for YAML serialization.

to_ogip_files(self, outdir=None, use_sherpa=False, overwrite=False)[source]¶

Write OGIP files.

If you want to use the written files with Sherpa you have to set the use_sherpa flag. Then all files will be written in units ‘keV’ and ‘cm2’.

The naming scheme is fixed, with {name} the dataset name:

PHA file is named pha_obs{name}.fits
BKG file is named bkg_obs{name}.fits
ARF file is named arf_obs{name}.fits
RMF file is named rmf_obs{name}.fits

Parameters

outdirpathlib.Path: output directory, default: pwd
use_sherpabool, optional: Write Sherpa compliant files, default: False
overwritebool: Overwrite existing files?

write(self, filename, overwrite)[source]¶

Write spectrum dataset on off to file.

Currently only the OGIP format is supported

Parameters

filenamestr: Filename to write to.
overwritebool: Overwrite existing file.