Description of all functions and classes

Description of all functions and classes#

Managers#

`manager.PyhfManager`()	Manager to unify the usage of pyhf through out the package
`interface.ModelNotDefined`	Undefined model exception
`interface.CombinationError`	Combination of the models are not possible
`simplify.ConversionError`	Conversion error class

Interface#

class spey_pyhf.interface.UncorrelatedBackground(signal_yields: List[float], background_yields: List[float], data: List[int], absolute_uncertainties: List[float])[source]#

Bases: PyhfInterface

This backend initiates pyhf.simplemodels.uncorrelated_background, forming an uncorrelated histogram structure with given inputs.

Parameters:

signal_yields (List[float]) – signal yields
background_yields (List[float]) – background yields
data (List[float]) – observations
absolute_uncertainties (List[float]) – absolute uncertainties on the background

asimov_negative_loglikelihood(poi_test: float = 1.0, expected: ExpectationType = ExpectationType.observed, test_statistics: str = 'qtilde', **kwargs) → Tuple[float, ndarray]#

Compute negative log-likelihood at fixed \(\mu\) for Asimov data.

Note

Interface first calls backend specific methods to compute likelihood. If they are not implemented, it optimizes objective function through spey interface. Either prescription to optimizing the likelihood or objective function must be available for a backend to be sucessfully integrated to the spey interface.

Parameters:

poi_test (float, default 1.0) – parameter of interest, \(\mu\).
expected (ExpectationType) –
Sets which values the fitting algorithm should focus and p-values to be computed.
- observed: Computes the p-values with via post-fit prescriotion which means that the experimental data will be assumed to be the truth (default).
- aposteriori: Computes the expected p-values with via post-fit prescriotion which means that the experimental data will be assumed to be the truth.
- apriori: Computes the expected p-values with via pre-fit prescription which means that the SM will be assumed to be the truth.
test_statistics (Text, default "qtilde") –
test statistics.
- 'qtilde': (default) performs the calculation using the alternative test statistic, \(\tilde{q}_{\mu}\), see eq. (62) of [arXiv:1007.1727] (qmu_tilde()).
  
  Warning
  
  Note that this assumes that \(\hat\mu\geq0\), hence allow_negative_signal assumed to be False. If this function has been executed by user, spey assumes that this is taken care of throughout the external code consistently. Whilst computing p-values or upper limit on \(\mu\) through spey this is taken care of automatically in the backend.
- 'q': performs the calculation using the test statistic \(q_{\mu}\), see eq. (54) of [arXiv:1007.1727] (qmu()).
- 'q0': performs the calculation using the discovery test statistic, see eq. (47) of [arXiv:1007.1727] \(q_{0}\) (q0()).
kwargs – keyword arguments for the optimiser.

Raises:

NotImplementedError – If the method is not available for the backend.

Returns:

value of negative log-likelihood at POI of interest and fit parameters (\(\mu\) and \(\theta\)).

Return type:

Tuple[float, np.ndarray]

author: str = 'SpeysideHEP'#: Author of the backend

combine(other, **kwargs)#

A routine to combine to statistical models.

Note

This function is only available if the backend has a specific routine for combination between same or other backends.

Parameters:: other (BackendBase) – Statistical model object to be combined.
Raises:: NotImplementedError – If the backend does not have a combination scheme.
Returns:: Create a new statistical model from combination of this and other one.
Return type:: BackendBase

config(allow_negative_signal: bool = True, poi_upper_bound: float = 10.0) → ModelConfig#

Model configuration.

Parameters:

allow_negative_signal (bool, default True) – If True \(\hat\mu\) value will be allowed to be negative.
poi_upper_bound (float, default 40.0) – upper bound for parameter of interest, \(\mu\).

Returns:

Model configuration. Information regarding the position of POI in parameter list, suggested input and bounds.

Return type:

ModelConfig

doi: List[str] = ['10.5281/zenodo.1169739', '10.21105/joss.02823']#: Citable DOI for the backend

expected_data(pars: List[float]) → List[float]#

Compute the expected value of the statistical model

Parameters:: pars (List[float]) – nuisance parameters, \(\theta\) and parameter of interest, \(\mu\).
Returns:: Expected data of the statistical model
Return type:: List[float]

get_hessian_logpdf_func(expected: ExpectationType = ExpectationType.observed, data: List[float] | ndarray | None = None) → Callable[[ndarray], float]#

Currently Hessian of \(\log\mathcal{L}(\mu, \theta)\) is only used to compute variance on \(\mu\). This method returns a callable function which takes fit parameters (\(\mu\) and \(\theta\)) and returns Hessian.

Parameters:

expected (ExpectationType) –
Sets which values the fitting algorithm should focus and p-values to be computed.
- observed: Computes the p-values with via post-fit prescriotion which means that the experimental data will be assumed to be the truth (default).
- aposteriori: Computes the expected p-values with via post-fit prescriotion which means that the experimental data will be assumed to be the truth.
- apriori: Computes the expected p-values with via pre-fit prescription which means that the SM will be assumed to be the truth.
data (Union[List[float], np.ndarray], default None) – input data that to fit

Returns:

Function that takes fit parameters (\(\mu\) and \(\theta\)) and returns Hessian of \(\log\mathcal{L}(\mu, \theta)\).

Return type:

Callable[[np.ndarray], float]

get_logpdf_func(expected: ExpectationType = ExpectationType.observed, data: List[float] | ndarray | None = None) → Callable[[ndarray], float]#

Generate function to compute \(\log\mathcal{L}(\mu, \theta)\) where \(\mu\) is the parameter of interest and \(\theta\) are nuisance parameters.

Parameters:

expected (ExpectationType) –
Sets which values the fitting algorithm should focus and p-values to be computed.
- observed: Computes the p-values with via post-fit prescriotion which means that the experimental data will be assumed to be the truth (default).
- aposteriori: Computes the expected p-values with via post-fit prescriotion which means that the experimental data will be assumed to be the truth.
- apriori: Computes the expected p-values with via pre-fit prescription which means that the SM will be assumed to be the truth.
data (Union[List[float], np.ndarray], default None) – input data that to fit

Returns:

Function that takes fit parameters (\(\mu\) and \(\theta\)) and computes \(\log\mathcal{L}(\mu, \theta)\).

Return type:

Callable[[np.ndarray], float]

get_objective_function(expected: ExpectationType = ExpectationType.observed, data: List[float] | ndarray | None = None, do_grad: bool = True) → Callable[[ndarray], float | Tuple[float, ndarray]]#

Objective function is the function to perform the optimisation on. This function is expected to be twice negative log-likelihood, \(-2\log\mathcal{L}(\mu, \theta)\). Additionally, if available it canbe bundled with the gradient of twice negative log-likelihood.

Parameters:

expected (ExpectationType) –
Sets which values the fitting algorithm should focus and p-values to be computed.
- observed: Computes the p-values with via post-fit prescriotion which means that the experimental data will be assumed to be the truth (default).
- aposteriori: Computes the expected p-values with via post-fit prescriotion which means that the experimental data will be assumed to be the truth.
- apriori: Computes the expected p-values with via pre-fit prescription which means that the SM will be assumed to be the truth.
data (Union[List[float], np.ndarray], default None) – input data that to fit
do_grad (bool, default True) – If True return objective and its gradient as tuple (subject to availablility) if False only returns objective function.

Returns:

Function which takes fit parameters (\(\mu\) and \(\theta\)) and returns either objective or objective and its gradient.

Return type:

Callable[[np.ndarray], Union[float, Tuple[float, np.ndarray]]]

get_sampler(pars: ndarray) → Callable[[int], ndarray]#

Retreives the function to sample from.

Parameters:: pars (np.ndarray) – fit parameters (\(\mu\) and \(\theta\))
Returns:: Function that takes number_of_samples as input and draws as many samples from the statistical model.
Return type:: Callable[[int], np.ndarray]

property is_alive: bool#: Returns True if at least one bin has non-zero signal yield.

manager#: pyhf Manager to handle the interface with pyhf

minimize_asimov_negative_loglikelihood(expected: ExpectationType = ExpectationType.observed, test_statistics: str = 'qtilde', **kwargs) → Tuple[float, ndarray]#

A backend specific method to minimize negative log-likelihood for Asimov data.

Note

Parameters:

expected (ExpectationType) –
Sets which values the fitting algorithm should focus and p-values to be computed.
- observed: Computes the p-values with via post-fit prescriotion which means that the experimental data will be assumed to be the truth (default).
- aposteriori: Computes the expected p-values with via post-fit prescriotion which means that the experimental data will be assumed to be the truth.
- apriori: Computes the expected p-values with via pre-fit prescription which means that the SM will be assumed to be the truth.
test_statistics (Text, default "qtilde") –
test statistics.
- 'qtilde': (default) performs the calculation using the alternative test statistic, \(\tilde{q}_{\mu}\), see eq. (62) of [arXiv:1007.1727] (qmu_tilde()).
  
  Warning
  
  Note that this assumes that \(\hat\mu\geq0\), hence allow_negative_signal assumed to be False. If this function has been executed by user, spey assumes that this is taken care of throughout the external code consistently. Whilst computing p-values or upper limit on \(\mu\) through spey this is taken care of automatically in the backend.
- 'q': performs the calculation using the test statistic \(q_{\mu}\), see eq. (54) of [arXiv:1007.1727] (qmu()).
- 'q0': performs the calculation using the discovery test statistic, see eq. (47) of [arXiv:1007.1727] \(q_{0}\) (q0()).
kwargs – keyword arguments for the optimiser.

Raises:

NotImplementedError – If the method is not available for the backend.

Returns:

value of negative log-likelihood and fit parameters (\(\mu\) and \(\theta\)).

Return type:

Tuple[float, np.ndarray]

minimize_negative_loglikelihood(expected: ExpectationType = ExpectationType.observed, allow_negative_signal: bool = True, **kwargs) → Tuple[float, ndarray]#

A backend specific method to minimize negative log-likelihood.

Note

Parameters:

expected (ExpectationType) –
Sets which values the fitting algorithm should focus and p-values to be computed.
- observed: Computes the p-values with via post-fit prescriotion which means that the experimental data will be assumed to be the truth (default).
- aposteriori: Computes the expected p-values with via post-fit prescriotion which means that the experimental data will be assumed to be the truth.
- apriori: Computes the expected p-values with via pre-fit prescription which means that the SM will be assumed to be the truth.
allow_negative_signal (bool, default True) – If True \(\hat\mu\) value will be allowed to be negative.
kwargs – keyword arguments for the optimiser.

Raises:

NotImplementedError – If the method is not available for the backend.

Returns:

value of negative log-likelihood and fit parameters (\(\mu\) and \(\theta\)).

Return type:

Tuple[float, np.ndarray]

property model: Base#: Retreive statistical model container

name: str = 'pyhf.uncorrelated_background'#: Name of the backend

negative_loglikelihood(poi_test: float = 1.0, expected: ExpectationType = ExpectationType.observed, **kwargs) → Tuple[float, ndarray]#

Backend specific method to compute negative log-likelihood for a parameter of interest \(\mu\).

Note

Parameters:

poi_test (float, default 1.0) – parameter of interest, \(\mu\).
expected (ExpectationType) –
Sets which values the fitting algorithm should focus and p-values to be computed.
- observed: Computes the p-values with via post-fit prescriotion which means that the experimental data will be assumed to be the truth (default).
- aposteriori: Computes the expected p-values with via post-fit prescriotion which means that the experimental data will be assumed to be the truth.
- apriori: Computes the expected p-values with via pre-fit prescription which means that the SM will be assumed to be the truth.
kwargs – keyword arguments for the optimiser.

Raises:

NotImplementedError – If the method is not available for the backend.

Returns:

value of negative log-likelihood at POI of interest and fit parameters (\(\mu\) and \(\theta\)).

Return type:

Tuple[float, np.ndarray]

spey_requires: str = '>=0.1.0'#: Spey version required for the backend

version: str = '0.1.3'#: Version of the backend

class spey_pyhf.interface.FullStatisticalModel(signal_patch: Dict, background_only_model: str | Dict)[source]#

Bases: PyhfInterface

pyhf Interface. For details on input structure please see this link

Parameters:

signal_patch (List[Dict]) –
Patch data for signal model. please see this link for details on the structure of the input.
background_only_model (Dict or Text) – This input expects background only data that describes the full statistical model for the background. It also accepts str input which indicates the full path to the background only JSON file.

Example:

>>> import spey

>>> background_only = {
...     "channels": [
...         {
...             "name": "singlechannel",
...             "samples": [
...                 {
...                     "name": "background",
...                     "data": [50.0, 52.0],
...                     "modifiers": [
...                         {
...                             "name": "uncorr_bkguncrt",
...                             "type": "shapesys",
...                             "data": [3.0, 7.0],
...                         }
...                     ],
...                 }
...             ],
...         }
...     ],
...     "observations": [{"name": "singlechannel", "data": [51.0, 48.0]}],
...     "measurements": [{"name": "Measurement", "config": {"poi": "mu", "parameters": []}}],
...     "version": "1.0.0",
... }
>>> signal = [
...     {
...         "op": "add",
...         "path": "/channels/0/samples/1",
...         "value": {
...             "name": "signal",
...             "data": [12.0, 11.0],
...             "modifiers": [{"name": "mu", "type": "normfactor", "data": None}],
...         },
...     }
... ]
>>> stat_wrapper = spey.get_backend("pyhf")
>>> statistical_model = stat_wrapper(
...     analysis="simple_pyhf",
...     background_only_model=background_only,
...     signal_patch=signal,
... )
>>> statistical_model.exclusion_confidence_level() # [0.9474850259721279]

asimov_negative_loglikelihood(poi_test: float = 1.0, expected: ExpectationType = ExpectationType.observed, test_statistics: str = 'qtilde', **kwargs) → Tuple[float, ndarray]#

Compute negative log-likelihood at fixed \(\mu\) for Asimov data.

Note

Parameters:

poi_test (float, default 1.0) – parameter of interest, \(\mu\).
expected (ExpectationType) –
Sets which values the fitting algorithm should focus and p-values to be computed.
- observed: Computes the p-values with via post-fit prescriotion which means that the experimental data will be assumed to be the truth (default).
- aposteriori: Computes the expected p-values with via post-fit prescriotion which means that the experimental data will be assumed to be the truth.
- apriori: Computes the expected p-values with via pre-fit prescription which means that the SM will be assumed to be the truth.
test_statistics (Text, default "qtilde") –
test statistics.
- 'qtilde': (default) performs the calculation using the alternative test statistic, \(\tilde{q}_{\mu}\), see eq. (62) of [arXiv:1007.1727] (qmu_tilde()).
  
  Warning
  
  Note that this assumes that \(\hat\mu\geq0\), hence allow_negative_signal assumed to be False. If this function has been executed by user, spey assumes that this is taken care of throughout the external code consistently. Whilst computing p-values or upper limit on \(\mu\) through spey this is taken care of automatically in the backend.
- 'q': performs the calculation using the test statistic \(q_{\mu}\), see eq. (54) of [arXiv:1007.1727] (qmu()).
- 'q0': performs the calculation using the discovery test statistic, see eq. (47) of [arXiv:1007.1727] \(q_{0}\) (q0()).
kwargs – keyword arguments for the optimiser.

Raises:

NotImplementedError – If the method is not available for the backend.

Returns:

value of negative log-likelihood at POI of interest and fit parameters (\(\mu\) and \(\theta\)).

Return type:

Tuple[float, np.ndarray]

author: str = 'SpeysideHEP'#: Author of the backend

combine(other, **kwargs)[source]#

Combine full statistical models generated by pyhf interface

Parameters:

other (FullStatisticalModel) – other statistical model to be combined with this model
kwargs –
pyhf specific inputs:
- join (str, default None): How to join the two workspaces. Pick from "none", "outer", "left outer" or “right outer”.
- merge_channels (bool): Whether or not to merge channels when performing the combine. This is only done with "outer", "left outer", and "right outer" options.
non-pyhf specific inputs:
- update_measurements (bool, default True): In case the measurement name of two statistical models are the same, other statistical model’s measurement name will be updated. If set to False measurements will remain as is.
Note

This model is "left" and other model is considered to be "right".

Raises:

CombinationError – Raised if its not possible to combine statistical models.

Returns:

Combined statistical model.

Return type:

FullStatisticalModel

config(allow_negative_signal: bool = True, poi_upper_bound: float = 10.0) → ModelConfig#

Model configuration.

Parameters:

allow_negative_signal (bool, default True) – If True \(\hat\mu\) value will be allowed to be negative.
poi_upper_bound (float, default 40.0) – upper bound for parameter of interest, \(\mu\).

Returns:

Model configuration. Information regarding the position of POI in parameter list, suggested input and bounds.

Return type:

ModelConfig

doi: List[str] = ['10.5281/zenodo.1169739', '10.21105/joss.02823']#: Citable DOI for the backend

expected_data(pars: List[float]) → List[float]#

Compute the expected value of the statistical model

Parameters:: pars (List[float]) – nuisance parameters, \(\theta\) and parameter of interest, \(\mu\).
Returns:: Expected data of the statistical model
Return type:: List[float]

get_hessian_logpdf_func(expected: ExpectationType = ExpectationType.observed, data: List[float] | ndarray | None = None) → Callable[[ndarray], float]#

Parameters:

expected (ExpectationType) –
Sets which values the fitting algorithm should focus and p-values to be computed.
- observed: Computes the p-values with via post-fit prescriotion which means that the experimental data will be assumed to be the truth (default).
- aposteriori: Computes the expected p-values with via post-fit prescriotion which means that the experimental data will be assumed to be the truth.
- apriori: Computes the expected p-values with via pre-fit prescription which means that the SM will be assumed to be the truth.
data (Union[List[float], np.ndarray], default None) – input data that to fit

Returns:

Function that takes fit parameters (\(\mu\) and \(\theta\)) and returns Hessian of \(\log\mathcal{L}(\mu, \theta)\).

Return type:

Callable[[np.ndarray], float]

get_logpdf_func(expected: ExpectationType = ExpectationType.observed, data: List[float] | ndarray | None = None) → Callable[[ndarray], float]#

Generate function to compute \(\log\mathcal{L}(\mu, \theta)\) where \(\mu\) is the parameter of interest and \(\theta\) are nuisance parameters.

Parameters:

expected (ExpectationType) –
Sets which values the fitting algorithm should focus and p-values to be computed.
- observed: Computes the p-values with via post-fit prescriotion which means that the experimental data will be assumed to be the truth (default).
- aposteriori: Computes the expected p-values with via post-fit prescriotion which means that the experimental data will be assumed to be the truth.
- apriori: Computes the expected p-values with via pre-fit prescription which means that the SM will be assumed to be the truth.
data (Union[List[float], np.ndarray], default None) – input data that to fit

Returns:

Function that takes fit parameters (\(\mu\) and \(\theta\)) and computes \(\log\mathcal{L}(\mu, \theta)\).

Return type:

Callable[[np.ndarray], float]

Parameters:

expected (ExpectationType) –
Sets which values the fitting algorithm should focus and p-values to be computed.
- observed: Computes the p-values with via post-fit prescriotion which means that the experimental data will be assumed to be the truth (default).
- aposteriori: Computes the expected p-values with via post-fit prescriotion which means that the experimental data will be assumed to be the truth.
- apriori: Computes the expected p-values with via pre-fit prescription which means that the SM will be assumed to be the truth.
data (Union[List[float], np.ndarray], default None) – input data that to fit
do_grad (bool, default True) – If True return objective and its gradient as tuple (subject to availablility) if False only returns objective function.

Returns:

Function which takes fit parameters (\(\mu\) and \(\theta\)) and returns either objective or objective and its gradient.

Return type:

Callable[[np.ndarray], Union[float, Tuple[float, np.ndarray]]]

get_sampler(pars: ndarray) → Callable[[int], ndarray]#

Retreives the function to sample from.

Parameters:: pars (np.ndarray) – fit parameters (\(\mu\) and \(\theta\))
Returns:: Function that takes number_of_samples as input and draws as many samples from the statistical model.
Return type:: Callable[[int], np.ndarray]

property is_alive: bool#: Returns True if at least one bin has non-zero signal yield.

manager#: pyhf Manager to handle the interface with pyhf

minimize_asimov_negative_loglikelihood(expected: ExpectationType = ExpectationType.observed, test_statistics: str = 'qtilde', **kwargs) → Tuple[float, ndarray]#

A backend specific method to minimize negative log-likelihood for Asimov data.

Note

Parameters:

expected (ExpectationType) –
Sets which values the fitting algorithm should focus and p-values to be computed.
- observed: Computes the p-values with via post-fit prescriotion which means that the experimental data will be assumed to be the truth (default).
- aposteriori: Computes the expected p-values with via post-fit prescriotion which means that the experimental data will be assumed to be the truth.
- apriori: Computes the expected p-values with via pre-fit prescription which means that the SM will be assumed to be the truth.
test_statistics (Text, default "qtilde") –
test statistics.
- 'qtilde': (default) performs the calculation using the alternative test statistic, \(\tilde{q}_{\mu}\), see eq. (62) of [arXiv:1007.1727] (qmu_tilde()).
  
  Warning
  
  Note that this assumes that \(\hat\mu\geq0\), hence allow_negative_signal assumed to be False. If this function has been executed by user, spey assumes that this is taken care of throughout the external code consistently. Whilst computing p-values or upper limit on \(\mu\) through spey this is taken care of automatically in the backend.
- 'q': performs the calculation using the test statistic \(q_{\mu}\), see eq. (54) of [arXiv:1007.1727] (qmu()).
- 'q0': performs the calculation using the discovery test statistic, see eq. (47) of [arXiv:1007.1727] \(q_{0}\) (q0()).
kwargs – keyword arguments for the optimiser.

Raises:

NotImplementedError – If the method is not available for the backend.

Returns:

value of negative log-likelihood and fit parameters (\(\mu\) and \(\theta\)).

Return type:

Tuple[float, np.ndarray]

minimize_negative_loglikelihood(expected: ExpectationType = ExpectationType.observed, allow_negative_signal: bool = True, **kwargs) → Tuple[float, ndarray]#

A backend specific method to minimize negative log-likelihood.

Note

Parameters:

expected (ExpectationType) –
Sets which values the fitting algorithm should focus and p-values to be computed.
- observed: Computes the p-values with via post-fit prescriotion which means that the experimental data will be assumed to be the truth (default).
- aposteriori: Computes the expected p-values with via post-fit prescriotion which means that the experimental data will be assumed to be the truth.
- apriori: Computes the expected p-values with via pre-fit prescription which means that the SM will be assumed to be the truth.
allow_negative_signal (bool, default True) – If True \(\hat\mu\) value will be allowed to be negative.
kwargs – keyword arguments for the optimiser.

Raises:

NotImplementedError – If the method is not available for the backend.

Returns:

value of negative log-likelihood and fit parameters (\(\mu\) and \(\theta\)).

Return type:

Tuple[float, np.ndarray]

property model: Base#: Retreive statistical model container

name: str = 'pyhf'#: Name of the backend

negative_loglikelihood(poi_test: float = 1.0, expected: ExpectationType = ExpectationType.observed, **kwargs) → Tuple[float, ndarray]#

Backend specific method to compute negative log-likelihood for a parameter of interest \(\mu\).

Note

Parameters:

poi_test (float, default 1.0) – parameter of interest, \(\mu\).
expected (ExpectationType) –
Sets which values the fitting algorithm should focus and p-values to be computed.
- observed: Computes the p-values with via post-fit prescriotion which means that the experimental data will be assumed to be the truth (default).
- aposteriori: Computes the expected p-values with via post-fit prescriotion which means that the experimental data will be assumed to be the truth.
- apriori: Computes the expected p-values with via pre-fit prescription which means that the SM will be assumed to be the truth.
kwargs – keyword arguments for the optimiser.

Raises:

NotImplementedError – If the method is not available for the backend.

Returns:

value of negative log-likelihood at POI of interest and fit parameters (\(\mu\) and \(\theta\)).

Return type:

Tuple[float, np.ndarray]

spey_requires: str = '>=0.1.0'#: Spey version required for the backend

version: str = '0.1.3'#: Version of the backend

class spey_pyhf.simplify.Simplify[source]#

An interface to convert pyhf full statistical model prescription into simplified likelihood framework as either correlated background or third moment expansion model. For details on simplified likelihood framework please see default plug-ins page.

Details on methodology can be found in the online documentation.

Parameters:

statistical_model (StatisticalModel) – constructed full statistical model
fittype (Text, default "postfit") – what type of fitting should be performed "postfit" or "prefit".
convert_to (Text, default "default_pdf.correlated_background") – conversion type. Should be either "default_pdf.correlated_background" or "default_pdf.third_moment_expansion".
number_of_samples (int, default 1000) – number of samples to be generated in order to estimate contract the uncertainties into a single value.
control_region_indices (List[int] or List[Text], default None) – indices or names of the control and validation regions inside the background only dictionary. For most of the cases interface will be able to guess the names of these regions but in case the region names are not obvious, reconstruction may fail thus these indices will indicate the location of the VRs and CRs within the channel list.
include_modifiers_in_control_model (bool, default False) – This flag enables the extraction of the signal modifiers to be used in the control model. The control model yields will still be zero and \(\mu=0\) but the contribution of the signal modifiers to the nuisance covariance matrix will be taken into account. By default, modifiers are excluded from the control model.
save_model (Text, default None) –
Full path to save the model details. Model will be saved as compressed NumPy file (.npz), file name should be given as /PATH/TO/DIR/MODELNAME.npz.

Reading the saved model:

One can read the saved model using NumPy’s load() function
```
>>> import numpy as np
>>> saved_model = np.load("/PATH/TO/DIR/MODELNAME.npz")
>>> data = saved_model["data"]
```
This model has several containers which includes the following keywords:
- "covariance_matrix": includes covariance matrix per bin
- "background_yields": includes background yields per bin
- "third_moments": (if convert_to="default_pdf.third_moment_expansion") includes third moments per bin
- "data": includes observed values per bin
- "channel_order": includes information regarding the channel order to convert a signal patch to be used in the simplified framework.

Raises:

ConversionError – If the requirements are not satisfied.
AssertionError – If input statistical model does not have pyhf backend or pyhf manager does not use jax backend.

Example:

As an example, lets use the JSON files provided for ATLAS-SUSY-2019-08 analysis which can be found in HEPData. Once these are downloaded one can read them as and construct a model as follows;

>>> import json, spey
>>> with open("1Lbb-likelihoods-hepdata/BkgOnly.json", "r") as f:
>>>         background_only = json.load(f)
>>> with open("1Lbb-likelihoods-hepdata/patchset.json", "r") as f:
>>>     signal = json.load(f)["patches"][0]["patch"]

>>> pdf_wrapper = spey.get_backend("pyhf")
>>> full_statistical_model = pdf_wrapper(
...     background_only_model=background_only, signal_patch=signal
... )
>>> full_statistical_model.backend.manager.backend = "jax"

Note that patchset.json includes more than one patch set, thats why we used only one of them. The last line enables the usage of jax backend in pyhf interface which in turn enables one to compute Hessian of the statistical model which is needed for simplification procedure.

Now we ca call "pyhf.simplify" model to map our full likelihood to simplified likelihood framework

>>> converter = spey.get_backend("pyhf.simplify")
>>> simplified_model = converter(
...     statistical_model=full_statistical_model,
...     convert_to="default_pdf.correlated_background",
...     control_region_indices=[
...             'WREM_cuts', 'STCREM_cuts', 'TRHMEM_cuts', 'TRMMEM_cuts', 'TRLMEM_cuts'
...         ]
... )
>>> print(simplified_model.backend_type)
>>> # "default_pdf.correlated_background"

author: str = 'SpeysideHEP'#: Author of the backend

name: str = 'pyhf.simplify'#: Name of the backend

spey_requires: str = '>=0.1.1'#: Spey version required for the backend

version: str = '0.1.3'#: Version of the backend

Data classes#

class spey_pyhf.data.Base[source]#

Base class for pyhf data input

abstract config(allow_negative_signal: bool = True, poi_upper_bound: float | None = None) → ModelConfig[source]#

Model configuration.

Parameters:

allow_negative_signal (bool, default True) – If True \(\hat\mu\) value will be allowed to be negative.
poi_upper_bound (float, default 40.0) – upper bound for parameter of interest, \(\mu\).

Returns:

Model configuration. Information regarding the position of POI in parameter list, suggested input and bounds.

Return type:

ModelConfig

abstract property isAlive: bool#: Returns True if at least one bin has non-zero signal yield.

class spey_pyhf.data.FullStatisticalModelData(signal_patch: List[Dict], background_only_model: Dict | str)[source]#

Bases: Base

Data container for the full statistical model.

Parameters:

signal_patch (List[Dict]) –
Patch data for signal model. please see this link for details on the structure of the input.
background_only_model (Dict or Text) – This input expects background only data that describes the full statistical model for the background. It also accepts str input which indicates the full path to the background only JSON file.

background_only_model: Dict | str#

property channel_properties: Iterator[Tuple[int, str, int]]#: Returns an iterator for channel index, name and number of bins

property channels: Iterator[str]#: Return channel names

config(allow_negative_signal: bool = True, poi_upper_bound: float | None = None) → ModelConfig[source]#

Model configuration.

Parameters:

allow_negative_signal (bool, default True) – If True \(\hat\mu\) value will be allowed to be negative.
poi_upper_bound (float, default 40.0) – upper bound for parameter of interest, \(\mu\).

Returns:

Model configuration. Information regarding the position of POI in parameter list, suggested input and bounds.

Return type:

ModelConfig

property isAlive: bool#: Returns True if at least one bin has non-zero signal yield.

signal_patch: List[Dict]#

class spey_pyhf.data.SimpleModelData(signal_yields: List[float], background_yields: List[float], data: List[float], absolute_uncertainties: List[float])[source]#

Bases: Base

Dataclass for simple statistical model

Parameters:

signal_yields (List[float]) – signal yields
background_yields (List[float]) – background yields
data (List[float]) – observations
absolute_uncertainties (List[float]) – absolute uncertainties on the background

absolute_uncertainties: List[float]#

background_yields: List[float]#

config(allow_negative_signal: bool = True, poi_upper_bound: float | None = None) → ModelConfig[source]#

Model configuration.

Parameters:

allow_negative_signal (bool, default True) – If True \(\hat\mu\) value will be allowed to be negative.
poi_upper_bound (float, default 40.0) – upper bound for parameter of interest, \(\mu\).

Returns:

Model configuration. Information regarding the position of POI in parameter list, suggested input and bounds.

Return type:

ModelConfig

data: List[float]#

property isAlive: bool#: Returns True if at least one bin has non-zero signal yield.

signal_yields: List[float]#

Helper functions#

class spey_pyhf.WorkspaceInterpreter(background_only_model: Dict)[source]#

A pyhf workspace interpreter to handle book keeping for the background only models and convert signal yields into JSONPatch compatible for pyhf.

Parameters:: background_only_model (Dict) – descrioption for the background only statistical model

add_patch(signal_patch: List[Dict]) → None[source]#: Inject signal patch

background_only_model#: Background only statistical model description

property bin_map: Dict[str, int]#: Get number of bins per channel

property channels: Iterator[List[str]]#: Retreive channel names as iterator

property expected_background_yields: Dict[str, List[float]]#: Retreive expected background yields with respect to signal injection

get_channels(channel_index: List[int] | List[str]) → List[str][source]#

Retreive channel names with respect to their index

Parameters:: channel_index (List[int]) – Indices of the channels
Returns:: Names of the channels corresponding to the given indices
Return type:: List[Text]

guess_CRVR() → List[str][source]#: Retreive control and validation channel names by guess

guess_channel_type(channel_name: str) → str[source]#: Guess the type of the channel as CR VR or SR

inject_signal(channel: str, data: List[float], modifiers: List[Dict] | None = None) → None[source]#

Inject signal to the model

Parameters:

channel (Text) – channel name
data (List[float]) – signal yields

Raises:

ValueError – If channel does not exist or number of yields does not match with the bin size of the channel

make_patch() → List[Dict][source]#

Make a JSONPatch for the background only model

Parameters:: measurement_index (int, default 0) – in case of multiple measurements which one to be used. Detauls is always the first measurement
Raises:: ValueError – if there is no signal.
Returns:: JSONPatch file for the background only model.
Return type:: List[Dict]

patch_to_map(signal_patch: List[Dict]) → Dict[str, Dict][source]#

Convert JSONPatch into signal map

>>> signal_map = {channel_name: {"data" : signal_yields, "modifiers": signal_modifiers}}

Parameters:: signal_patch (List[Dict]) – JSONPatch for the signal
Returns:: signal map including the data and modifiers
Return type:: Dict[Text, Dict]

property poi_name: Dict[str, str]#: Retreive poi name per measurement

reset_signal() → None[source]#: Clear the signal map

property signal_per_channel: Dict[str, List[float]]#: Return signal yields in each channel

Description of all functions and classes

Contents

Description of all functions and classes#

Managers#

Interface#

Data classes#

Helper functions#