SpectrumDatasetOnOff¶

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

Bases: gammapy.spectrum.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:

model : SpectralModel: Fit model
counts : CountsSpectrum: ON Counts spectrum
counts_off : CountsSpectrum: OFF Counts spectrum
livetime : Quantity: Livetime
aeff : EffectiveAreaTable: Effective area
edisp : EnergyDispersion: Energy dispersion
mask_safe : array: Mask defining the safe data range.
mask_fit : array: Mask to apply to the likelihood for fitting.
acceptance : array or float: Relative background efficiency in the on region.
acceptance_off : array or float: Relative background efficiency in the off region.
name : str: Name of the dataset.
gti : GTI: 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
`excess`	Excess (counts - alpha * counts_off)
`likelihood_type`
`mask`	Combined fit and safe mask
`mask_safe`
`model`
`parameters`

Methods Summary

`copy`(self)	A deep copy.
`create`(e_reco[, e_true, reference_time])	Create empty SpectrumDatasetOnOff.
`fake`(self, background_model[, random_state])	Simulate fake counts for the current model and reduced irfs.
`from_ogip_files`(filename)	Read `SpectrumDatasetOnOff` from OGIP files.
`likelihood`(self)	Total likelihood given the current model parameters.
`likelihood_per_bin`(self)	Likelihood per bin given the current model parameters
`npred`(self)	Return npred map (model + background)
`npred_sig`(self)	Predicted counts from source model (`CountsSpectrum`).
`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.
`to_ogip_files`(self[, outdir, use_sherpa, …])	Write OGIP files.

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

excess¶: Excess (counts - alpha * counts_off)

likelihood_type = 'wstat'¶

mask¶: Combined fit and safe mask

mask_safe¶

model¶

parameters¶

Methods Documentation

copy(self)¶: A deep copy.

classmethod create(e_reco, e_true=None, reference_time='2000-01-01')[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_reco : `Quantity` edges of counts vector e_true : `Quantity` edges of effective area table. If not set use reco energy values. Default : None reference_time : `Time` 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_model : `CountsSpectrum` BackgroundModel. In the future will be part of the SpectrumDataset Class. For the moment, a CountSpectrum. random_state : {int, ‘random-seed’, ‘global-rng’, `RandomState`} Defines random number generator initialisation. Passed to `get_random_state`.

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.

Parameters:	filename : str OGIP PHA file to read

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

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

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

npred_sig(self)[source]¶: Predicted counts from source model (CountsSpectrum).

peek(self, figsize=(10, 10))[source]¶: Quick-look summary plots.

plot_counts(self, ax=None)¶

Plot predicted and detected counts.

Parameters:	ax : `Axes` Axes object.
Returns:	ax : `Axes` 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:	ax : `Axes` Axes object. method : {“diff”, “diff/model”, “diff/sqrt(model)”} Normalization used to compute the residuals, see `SpectrumDataset.residuals()` **kwargs : dict Keywords passed to `CountsSpectrum.plot()`
Returns:	ax : `Axes` 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:	filename : str 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:	residuals : `CountsSpectrum` 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:	other : `SpectrumDatasetOnOff` the dataset to stack to the current one

Examples

>>> from gammapy.spectrum 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

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

Parameters:	outdir : `pathlib.Path` output directory, default: pwd use_sherpa : bool, optional Write Sherpa compliant files, default: False overwrite : bool Overwrite existing files?