Skip to main content

pure-Python HistFactory implementation with tensors and autodiff

Project description

pyhf logo

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

GitHub Project DOI JOSS DOI Scikit-HEP NSF Award Number IRIS-HEP v1 NSF Award Number IRIS-HEP v2 NumFOCUS Affiliated Project

Docs from latest Docs from main Jupyter Book tutorial Binder

PyPI version Conda-forge version Supported Python versions Docker Hub pyhf Docker Hub pyhf CUDA

Code Coverage CodeFactor pre-commit.ci status Code style: black

GitHub Actions Status: CI GitHub Actions Status: Docs GitHub Actions Status: Publish GitHub Actions Status: Docker

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.

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

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

  • ☑ PyTorch

  • ☑ TensorFlow

  • ☑ 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

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

Documentation

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

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.7.6}",
  version = {0.7.6},
  doi = {10.5281/zenodo.1169739},
  url = {https://doi.org/10.5281/zenodo.1169739},
  note = {https://github.com/scikit-hep/pyhf/releases/tag/v0.7.6}
}

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

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pyhf-0.7.6.tar.gz (114.0 kB view details)

Uploaded Source

Built Distribution

pyhf-0.7.6-py3-none-any.whl (160.2 kB view details)

Uploaded Python 3

File details

Details for the file pyhf-0.7.6.tar.gz.

File metadata

  • Download URL: pyhf-0.7.6.tar.gz
  • Upload date:
  • Size: 114.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/4.0.2 CPython/3.11.7

File hashes

Hashes for pyhf-0.7.6.tar.gz
Algorithm Hash digest
SHA256 d41d9cdce5555863a77a37efd0784ad81d84b817295aa07ebc1cfa5ec50cc78c
MD5 ee8f16499251c1f1d5a9927103823d55
BLAKE2b-256 c821a8367a614de74037338dca328a1ce4ee7f2557983899db6e7eed6afc8c99

See more details on using hashes here.

File details

Details for the file pyhf-0.7.6-py3-none-any.whl.

File metadata

  • Download URL: pyhf-0.7.6-py3-none-any.whl
  • Upload date:
  • Size: 160.2 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/4.0.2 CPython/3.11.7

File hashes

Hashes for pyhf-0.7.6-py3-none-any.whl
Algorithm Hash digest
SHA256 01b2401b9fdc53d94fa28256128c4898c380c64f71446f1695580fb18fba349d
MD5 804a01ef292efa7e632e70f8bfccb4af
BLAKE2b-256 de4391d24c1b64f576f59b5aa5cbd8e732815bfeb8cf87fcc6fb65027c132e7f

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page