Package: pyhf
pure-python fitting/limit-setting/interval estimation HistFactory-styleThe 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 GuideFor an in depth walkthrough of usage of the latest release ofpyhfvisit thepyhftutorial.Hello WorldThis is how you use thepyhfPython API to build a statistical model and run basic inference:>>>importpyhf>>>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.06445321Alternatively the statistical model and observational data can be read from its serialized JSON representation (see next section).>>>importpyhf>>>importrequests>>>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.35998409Finally, you can also use the command line interface thatpyhfprovides$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"
}
EOFwhich 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 supportImplemented variations:☑ HistoSys☑ OverallSys☑ ShapeSys☑ NormFactor☑ Multiple Channels☑ Import from XML + ROOT viauproot☑ ShapeFactor☑ StatError☑ Lumi Uncertainty☑ Non-asymptotic calculatorsComputational Backends:☑ NumPy☑ PyTorch☑ TensorFlow☑ JAXOptimizers:☑ 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☐ StatConfigresults obtained from this package are validated against output computed
from HistFactory workspacesA one bin exampleimportpyhfimportnumpyasnpimportmatplotlib.pyplotaspltfrompyhf.contrib.vizimportbrazilpyhf.set_backend("numpy")model=pyhf.simplemodels.uncorrelated_background(signal=[10.0],bkg=[50.0],bkg_uncertainty=[7.0])data=[55.0]+model.config.auxdatapoi_vals=np.linspace(0,5,41)results=[pyhf.infer.hypotest(test_poi,data,model,test_stat="qtilde",return_expected_set=True)fortest_poiinpoi_vals]fig,ax=plt.subplots()fig.set_size_inches(7,5)brazil.plot_results(poi_vals,results,ax=ax)fig.show()pyhfROOTA two bin exampleimportpyhfimportnumpyasnpimportmatplotlib.pyplotaspltfrompyhf.contrib.vizimportbrazilpyhf.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.auxdatapoi_vals=np.linspace(0,5,41)results=[pyhf.infer.hypotest(test_poi,data,model,test_stat="qtilde",return_expected_set=True)fortest_poiinpoi_vals]fig,ax=plt.subplots()fig.set_size_inches(7,5)brazil.plot_results(poi_vals,results,ax=ax)fig.show()pyhfROOTInstallationTo installpyhffrom PyPI with the NumPy backend runpython-mpipinstallpyhfand to installpyhfwith all additional backends runpython-mpipinstallpyhf[backends]or a subset of the options.To uninstall runpython-mpipuninstallpyhfDocumentationFor model specification, API reference, examples, and answers to FAQs visit thepyhfdocumentation.QuestionsIf you have a question about the use ofpyhfnot covered inthe
documentation, please ask a question
on theGitHub Discussions.If you believe you have found a bug inpyhf, please report it in theGitHub
Issues.
If you’re interested in getting updates from thepyhfdev team and release
announcements you can join thepyhf-announcementsmailing list.CitationAs noted inUse and Citations,
the preferred BibTeX entry for citation ofpyhfincludes both theZenodoarchive and theJOSSpaper:@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}}Authorspyhfis openly developed by Lukas Heinrich, Matthew Feickert, and Giordon Stark.Please check thecontribution statistics for a list of
contributors.Milestones2022-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)AcknowledgementsMatthew Feickert has received support to work onpyhfprovided by NSF
cooperative agreementsOAC-1836650andPHY-2323298(IRIS-HEP)
and grantOAC-1450377(DIANA/HEP).pyhfis aNumFOCUS Affiliated Project.