Python API

Top-Level

tensorlib

NumPy backend for pyhf

optimizer

Optimizer that uses scipy.optimize.minimize().

get_backend

Get the current backend and the associated optimizer

set_backend

Set the backend and the associated optimizer

readxml

writexml

compat

Compatibility functions for translating between ROOT and pyhf

schema

See Schema for documentation.

Probability Distribution Functions (PDFs)

Normal

The Normal distribution with mean loc and standard deviation scale.

Poisson

The Poisson distribution with rate parameter rate.

Independent

A probability density corresponding to the joint distribution of a batch of identically distributed random variables.

Simultaneous

A probability density corresponding to the joint distribution of multiple non-identical component distributions

Making Models from PDFs

Model

The main pyhf model class.

_ModelConfig

Configuration for the Model.

_MainModel

Factory class to create pdfs for the main measurement.

_ConstraintModel

Factory class to create pdfs for the constraint terms.

_ChannelSummaryMixin

A mixin that provides summary data of the provided channels.

Workspace

A JSON-serializable object that is built from an object that follows the workspace.json schema.

PatchSet

A way to store a collection of patches (Patch).

Patch

A way to store a patch definition as part of a patchset (PatchSet).

simplemodels.uncorrelated_background

Construct a simple single channel Model with a shapesys modifier representing an uncorrelated background uncertainty.

simplemodels.correlated_background

Construct a simple single channel Model with a histosys modifier representing a background with a fully correlated bin-by-bin uncertainty.

Backends

The computational backends that pyhf provides interfacing for the vector-based calculations.

numpy_backend.numpy_backend

NumPy backend for pyhf

pytorch_backend.pytorch_backend

PyTorch backend for pyhf

tensorflow_backend.tensorflow_backend

TensorFlow backend for pyhf

jax_backend.jax_backend

JAX backend for pyhf

Optimizers

mixins.OptimizerMixin

Mixin Class to build optimizers.

opt_scipy.scipy_optimizer

Optimizer that uses scipy.optimize.minimize().

opt_minuit.minuit_optimizer

Optimizer that minimizes via iminuit.Minuit.migrad().

Modifiers

histosys

normfactor

normsys

shapefactor

shapesys

staterror

Interpolators

code0

The piecewise-linear interpolation strategy.

code1

The piecewise-exponential interpolation strategy.

code2

The quadratic interpolation and linear extrapolation strategy.

code4

The polynomial interpolation and exponential extrapolation strategy.

code4p

The piecewise-linear interpolation strategy, with polynomial at \(\left|a\right| < 1\).

Inference

Test Statistics

test_statistics.q0

The test statistic, \(q_{0}\), for discovery of a positive signal as defined in Equation (12) in [1007.1727], for \(\mu=0\).

test_statistics.qmu

The test statistic, \(q_{\mu}\), for establishing an upper limit on the strength parameter, \(\mu\), as defined in Equation (14) in [1007.1727]

test_statistics.qmu_tilde

The "alternative" test statistic, \(\tilde{q}_{\mu}\), for establishing an upper limit on the strength parameter, \(\mu\), for models with bounded POI, as defined in Equation (16) in [1007.1727]

test_statistics.tmu

The test statistic, \(t_{\mu}\), for establishing a two-sided interval on the strength parameter, \(\mu\), as defined in Equation (8) in [1007.1727]

test_statistics.tmu_tilde

The test statistic, \(\tilde{t}_{\mu}\), for establishing a two-sided interval on the strength parameter, \(\mu\), for models with bounded POI, as defined in Equation (11) in [1007.1727]

utils.get_test_stat

Get the test statistic function by name.

Calculators

calculators.generate_asimov_data

Compute Asimov Dataset (expected yields at best-fit values) for a given POI value.

calculators.HypoTestFitResults

Fitted model parameters of the fits in AsymptoticCalculator.teststatistic

calculators.AsymptoticTestStatDistribution

The distribution the test statistic in the asymptotic case.

calculators.EmpiricalDistribution

The empirical distribution of the test statistic.

calculators.AsymptoticCalculator

The Asymptotic Calculator.

calculators.ToyCalculator

The Toy-based Calculator.

utils.create_calculator

Creates a calculator object of the specified calctype.

Fits and Tests

mle.twice_nll

Two times the negative log-likelihood of the model parameters, \(\left(\mu, \boldsymbol{\theta}\right)\), given the observed data.

mle.fit

Run a maximum likelihood fit.

mle.fixed_poi_fit

Run a maximum likelihood fit with the POI value fixed.

hypotest

Compute \(p\)-values and test statistics for a single value of the parameter of interest.

utils.all_pois_floating

Check whether all POI(s) are floating (i.e. not within the fixed set).

Confidence Intervals

intervals.upper_limits.upper_limit

Calculate an upper limit interval (0, poi_up) for a single Parameter of Interest (POI) using root-finding or a linear scan through POI-space.

intervals.upper_limits.toms748_scan

Calculate an upper limit interval (0, poi_up) for a single Parameter of Interest (POI) using an automatic scan through POI-space, using the toms748() algorithm.

intervals.upper_limits.linear_grid_scan

Calculate an upper limit interval (0, poi_up) for a single Parameter of Interest (POI) using a linear scan through POI-space.

intervals.upperlimit

Deprecated since version 0.7.0.

Schema

Schema

A module-level wrapper around pyhf.schema which will provide additional functionality for interacting with schemas.

load_schema

Get a schema by relative path from cache, or load it into the cache and return.

validate

Validate the provided instance, spec, against the schema associated with schema_name.

Exceptions

Various exceptions, apart from standard python exceptions, that are raised from using the pyhf API.

InvalidMeasurement

InvalidMeasurement is raised when a specified measurement is invalid given the specification.

InvalidNameReuse

InvalidSpecification

InvalidSpecification is raised when a specification does not validate against the given schema.

InvalidPatchSet

InvalidPatchSet is raised when a given patchset object does not have the right configuration, even though it validates correctly against the schema.

InvalidPatchLookup

InvalidPatchLookup is raised when the patch lookup from a patchset object has failed

PatchSetVerificationError

PatchSetVerificationError is raised when the workspace digest does not match the patchset digests as part of the verification procedure

InvalidWorkspaceOperation

InvalidWorkspaceOperation is raised when an operation on a workspace fails.

InvalidModel

InvalidModel is raised when a given model does not have the right configuration, even though it validates correctly against the schema.

InvalidModifier

InvalidModifier is raised when an invalid modifier is requested.

InvalidInterpCode

InvalidInterpCode is raised when an invalid/unimplemented interpolation code is requested.

ImportBackendError

MissingLibraries is raised when something is imported by sustained an import error due to missing additional, non-default libraries.

InvalidBackend

InvalidBackend is raised when trying to set a backend that does not exist.

InvalidOptimizer

InvalidOptimizer is raised when trying to set an optimizer that does not exist.

InvalidPdfParameters

InvalidPdfParameters is raised when trying to evaluate a pdf with invalid parameters.

InvalidPdfData

InvalidPdfData is raised when trying to evaluate a pdf with invalid data.

Utilities

options_from_eqdelimstring

digest

Get the digest for the provided object.

citation

Get the bibtex citation for pyhf

Contrib

viz.brazil

Brazil Band Plots.

utils.download

Download the patchset archive from the remote URL and extract it in a directory at the path given.