Skip to main content
pyhf logo

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

PyPI version Conda-forge version Supported Python versions DOI JOSS DOI Scikit-HEP

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 JAX in order to make use of features such as automatic differentiation and GPU acceleration.

User Guide

For an in depth walkthrough of usage of the latest release of pyhf visit the pyhf tutorial.

Hello World

This is how you use the pyhf Python API to build a statistical model and run basic inference:

>>> import pyhf
>>> pyhf.set_backend("numpy")
>>> model = pyhf.simplemodels.uncorrelated_background(
...     signal=[12.0, 11.0], bkg=[50.0, 52.0], bkg_uncertainty=[3.0, 7.0]
... )
>>> data = [51, 48] + model.config.auxdata
>>> test_mu = 1.0
>>> CLs_obs, CLs_exp = pyhf.infer.hypotest(
...     test_mu, data, model, test_stat="qtilde", return_expected=True
... )
>>> print(f"Observed: {CLs_obs:.8f}, Expected: {CLs_exp:.8f}")
Observed: 0.05251497, Expected: 0.06445319

Alternatively the statistical model and observational data can be read from its serialized JSON representation (see next section).

>>> import pyhf
>>> import requests
>>> pyhf.set_backend("numpy")
>>> url = "https://raw.githubusercontent.com/scikit-hep/pyhf/main/docs/examples/json/2-bin_1-channel.json"
>>> wspace = pyhf.Workspace(requests.get(url).json())
>>> model = wspace.model()
>>> data = wspace.data(model)
>>> test_mu = 1.0
>>> CLs_obs, CLs_exp = pyhf.infer.hypotest(
...     test_mu, data, model, test_stat="qtilde", return_expected=True
... )
>>> print(f"Observed: {CLs_obs:.8f}, Expected: {CLs_exp:.8f}")
Observed: 0.35998409, Expected: 0.35998409

Finally, you can also use the command line interface that pyhf provides

$ cat << EOF  | tee likelihood.json | pyhf cls
{
    "channels": [
        { "name": "singlechannel",
          "samples": [
            { "name": "signal",
              "data": [12.0, 11.0],
              "modifiers": [ { "name": "mu", "type": "normfactor", "data": null} ]
            },
            { "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"
}
EOF

which should produce the following JSON output:

{
   "CLs_exp": [
      0.0026062609501074576,
      0.01382005356161206,
      0.06445320535890459,
      0.23525643861460702,
      0.573036205919389
   ],
   "CLs_obs": 0.05251497423736956
}

What does it support

Implemented variations:
  • ☑ HistoSys

  • ☑ OverallSys

  • ☑ ShapeSys

  • ☑ NormFactor

  • ☑ Multiple Channels

  • ☑ Import from XML + ROOT via uproot

  • ☑ ShapeFactor

  • ☑ StatError

  • ☑ Lumi Uncertainty

  • ☑ Non-asymptotic calculators

Computational Backends:
  • ☑ NumPy

  • ☑ JAX

Optimizers:
  • ☑ 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.

Todo

  • ☐ StatConfig

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

A one bin example

import pyhf
import numpy as np
import matplotlib.pyplot as plt
from pyhf.contrib.viz import brazil

pyhf.set_backend("numpy")
model = pyhf.simplemodels.uncorrelated_background(
    signal=[10.0], bkg=[50.0], bkg_uncertainty=[7.0]
)
data = [55.0] + model.config.auxdata

poi_vals = np.linspace(0, 5, 41)
results = [
    pyhf.infer.hypotest(
        test_poi, data, model, test_stat="qtilde", return_expected_set=True
    )
    for test_poi in poi_vals
]

fig, ax = plt.subplots()
fig.set_size_inches(7, 5)
brazil.plot_results(poi_vals, results, ax=ax)
fig.show()

pyhf

manual

ROOT

manual

A two bin example

import pyhf
import numpy as np
import matplotlib.pyplot as plt
from pyhf.contrib.viz import brazil

pyhf.set_backend("numpy")
model = pyhf.simplemodels.uncorrelated_background(
    signal=[30.0, 45.0], bkg=[100.0, 150.0], bkg_uncertainty=[15.0, 20.0]
)
data = [100.0, 145.0] + model.config.auxdata

poi_vals = np.linspace(0, 5, 41)
results = [
    pyhf.infer.hypotest(
        test_poi, data, model, test_stat="qtilde", return_expected_set=True
    )
    for test_poi in poi_vals
]

fig, ax = plt.subplots()
fig.set_size_inches(7, 5)
brazil.plot_results(poi_vals, results, ax=ax)
fig.show()

pyhf

manual

ROOT

manual

Installation

pyhf is distributed on both PyPI and conda-forge.

PyPI

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

conda-forge

To add pyhf from conda-forge with the NumPy backend to a Pixi project run

pixi add pyhf

or to install it with conda run

conda install --channel conda-forge pyhf

The conda-forge package does not provide the additional backends as extras, so install the backend packages (e.g. jax) from conda-forge alongside pyhf as needed.

Docker

Docker images with pyhf preinstalled are also published to Docker Hub: Docker Hub pyhf

Documentation

For model specification, API reference, examples, and answers to FAQs visit the pyhf documentation.

Docs from latest Docs from main Jupyter Book tutorial Binder

Questions

If you have a question about the use of pyhf not covered in the documentation, please ask a question on the GitHub Discussions.

If you believe you have found a bug in pyhf, please report it in the GitHub Issues. If you’re interested in getting updates from the pyhf dev team and release announcements you can join the pyhf-announcements mailing list.

Citation

As noted in Use and Citations, the preferred BibTeX entry for citation of pyhf includes both the Zenodo archive and the JOSS paper:

@software{pyhf,
  author = {Lukas Heinrich and Matthew Feickert and Giordon Stark},
  title = "{pyhf: v0.8.0}",
  version = {0.8.0},
  doi = {10.5281/zenodo.1169739},
  url = {https://doi.org/10.5281/zenodo.1169739},
  note = {https://github.com/scikit-hep/pyhf/releases/tag/v0.8.0}
}

@article{pyhf_joss,
  doi = {10.21105/joss.02823},
  url = {https://doi.org/10.21105/joss.02823},
  year = {2021},
  publisher = {The Open Journal},
  volume = {6},
  number = {58},
  pages = {2823},
  author = {Lukas Heinrich and Matthew Feickert and Giordon Stark and Kyle Cranmer},
  title = {pyhf: pure-Python implementation of HistFactory statistical models},
  journal = {Journal of Open Source Software}
}

Authors

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

Please check the contribution statistics for a list of contributors.

Milestones

  • 2022-09-12: 2000 GitHub issues and pull requests. (See PR #2000)

  • 2021-12-09: 1000 commits to the project. (See PR #1710)

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

Acknowledgements

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

pyhf is a NumFOCUS Affiliated Project.

NSF Award Number IRIS-HEP v1 NSF Award Number IRIS-HEP v2 NumFOCUS Affiliated Project

Metadata

Release files for pyhf 0.8.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pyhf 0.8.0
File Size Uploaded Provenance Actions
pyhf-0.8.0.tar.gz 114.4 kB With provenance Details for pyhf-0.8.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for pyhf 0.8.0
File Interpreter ABI Platform Actions
pyhf-0.8.0-py3-none-any.whl Python 3 none any Details for pyhf-0.8.0-py3-none-any.whl

Total release size: 267.4 kB

Release files / pyhf-0.8.0.tar.gz

Download URL pyhf-0.8.0.tar.gz
Size 114.4 kB
Tags Source
SHA-256 checksum
How to use checksums
db5eac7cd636fca3e5ccb4c286236c9e5f111825248c9e20b994710143464752
BLAKE2b-256 checksum
How to use checksums
4cdd6db203a06187d606c9de4a80e53e0f95f8afbd15cbc9898a6ab0f36ae5ba
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

Release files / pyhf-0.8.0-py3-none-any.whl

Download URL pyhf-0.8.0-py3-none-any.whl
Size 152.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
84787e9afbadf4c82342745e77e530cfaf5468c7142f5720555906ee9ee36ddf
BLAKE2b-256 checksum
How to use checksums
df0638d74dff7bfc74decc66fd7a42755c81e4bf49ad02b02164a066640ae369
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

Security for pyhf 0.8.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for pyhf-0.8.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.8.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page