Fork me on GitHubpyhf logo

pure-python fitting/limit-setting/interval estimation HistFactory-style

GitHub Project DOI Scikit-HEP

GitHub Actions Status: CI GitHub Actions Status: Publish Docker Automated Code Coverage Language grade: Python CodeFactor Code style: black

Docs Binder

PyPI version Conda-forge version Supported Python versions Docker Stars Docker Pulls

The HistFactory p.d.f. template [CERN-OPEN-2012-016] is per-se independent of its implementation in ROOT and sometimes, it’s useful to be able to run statistical analysis outside of ROOT, RooFit, RooStats framework.

This repo is a pure-python implementation of that statistical model for multi-bin histogram-based analysis and its interval estimation is based on the asymptotic formulas of “Asymptotic formulae for likelihood-based tests of new physics” [arXiv:1007.1727]. The aim is also to support modern computational graph libraries such as PyTorch and TensorFlow in order to make use of features such as autodifferentiation and GPU acceleration.

Hello World

>>> import pyhf
>>> pdf = pyhf.simplemodels.hepdata_like(signal_data=[12.0, 11.0], bkg_data=[50.0, 52.0], bkg_uncerts=[3.0, 7.0])
>>> CLs_obs, CLs_exp = pyhf.infer.hypotest(1.0, [51, 48] + pdf.config.auxdata, pdf, return_expected=True)
>>> print('Observed: {}, Expected: {}'.format(CLs_obs, CLs_exp))
Observed: [0.05290116], Expected: [0.06445521]

What does it support

Implemented variations:
  • ☑ HistoSys

  • ☑ OverallSys

  • ☑ ShapeSys

  • ☑ NormFactor

  • ☑ Multiple Channels

  • ☑ Import from XML + ROOT via uproot

  • ☑ ShapeFactor

  • ☑ StatError

  • ☑ Lumi Uncertainty

Computational Backends:
  • ☑ NumPy

  • ☑ PyTorch

  • ☑ TensorFlow

  • ☑ JAX

  • ☑ SciPy (scipy.optimize)

  • ☑ MINUIT (iminuit)

All backends can be used in combination with all optimizers. Custom user backends and optimizers can be used as well.


  • ☐ StatConfig

  • ☐ Non-asymptotic calculators

results obtained from this package are validated against output computed from HistFactory workspaces

A one bin example

nobs = 55, b = 50, db = 7, nom_sig = 10.
manual manual

A two bin example

bin 1: nobs = 100, b = 100, db = 15., nom_sig = 30.
bin 2: nobs = 145, b = 150, db = 20., nom_sig = 45.
manual manual


To install pyhf from PyPI with the NumPy backend run

python -m pip install pyhf

and to install pyhf with all additional backends run

python -m pip install pyhf[backends]

or a subset of the options.

To uninstall run

python -m pip uninstall pyhf


If you have a question about the use of pyhf not covered in the documentation, please ask a question on Stack Overflow with the [pyhf] tag, which the pyhf dev team watches.

Stack Overflow pyhf tag

If you believe you have found a bug in pyhf, please report it in the GitHub Issues.


As noted in Use and Citations, the preferred BibTeX entry for citation of pyhf is

  author = "{Heinrich, Lukas and Feickert, Matthew and Stark, Giordon}",
  title = "{pyhf: v0.5.1}",
  version = {0.5.1},
  doi = {10.5281/zenodo.1169739},
  url = {},


pyhf is openly developed by Lukas Heinrich, Matthew Feickert, and Giordon Stark.

Please check the contribution statistics for a list of contributors.


  • 2020-07-28: 1000 GitHub issues and pull requests. (See PR #1000)


Matthew Feickert has received support to work on pyhf provided by NSF cooperative agreement OAC-1836650 (IRIS-HEP) and grant OAC-1450377 (DIANA/HEP).

Indices and tables