pyhf Tutorial

Welcome!¶

Welcome to the pyhf tutorial! We’ll first point you towards our documentation website (pyhf.readthedocs.io/) and recommend that you visit it for much more detailed explanations and examples. Let’s dive right in.

We won’t review the full pedagogy of HistFactory, so instead we’ll point you to the pyhf talk at SciPy 2020.

Instead, let’s move to looking at the pyhf API right away.

Installation¶

Make a Virtual Environment¶

$ pixi init
$ pixi shell

$ python3 -m venv pyhf-tutorial
$ source pyhf-tutorial/bin/activate
(pyhf-tutorial) $ python -m pip install --upgrade pip

$ conda create --name pyhf-tutorial --yes 'python=3.12'
$ conda activate pyhf-tutorial

$ export ATLAS_LOCAL_ROOT_BASE=/cvmfs/atlas.cern.ch/repo/ATLASLocalRootBase
$ . $ATLAS_LOCAL_ROOT_BASE/user/atlasLocalSetup.sh
$ lsetup "views LCG_106 x86_64-el9-gcc13-opt"

$ mkdir -p ~/.local/bin
$ export PATH=~/.local/bin:"${PATH}"
$ curl -sL https://raw.githubusercontent.com/matthewfeickert/cvmfs-venv/main/cvmfs-venv.sh -o ~/.local/bin/cvmfs-venv
$ chmod +x ~/.local/bin/cvmfs-venv

$ cvmfs-venv pyhf-tutorial
$ . pyhf-tutorial/bin/activate
(pyhf-tutorial) $ uv pip install --upgrade pip

Once you have a virtual environment set up, you can use source pyhf-tutorial/bin/activate to get back into it again (or pixi shell for pixi). Note the prefix (pyhf-tutorial) $ on your command line, which indicates that you’re inside a virtual environment named ‘pyhf-tutorial’.

Getting pyhf¶

If you haven’t already, make a new Python 3 virtual environment and then install pyhf

$ pixi add pyhf

(pyhf-tutorial) $ python -m pip install pyhf

(pyhf-tutorial) $ conda install --channel conda-forge pyhf

Installation Extras¶

If you’re installing from PyPI, you can also install with some of the “extras” that will be useful for doing typical HEP analysis workflows with pyhf.

(pyhf-tutorial) $ python -m pip install 'pyhf[xmlio]'

(pyhf-tutorial) $ python -m pip install 'pyhf[torch,jax]'

(pyhf-tutorial) $ python -m pip install 'pyhf[minuit]'

See our installation docs for more information about installation options.

Dependencies for this tutorial¶

To get all the dependencies needed for this tutorial first clone the repository locally

(pyhf-tutorial) $ git clone https://github.com/pyhf/pyhf-tutorial.git
(pyhf-tutorial) $ cd pyhf-tutorial

Using pixi¶

then simply run

pixi install --environment lab

or to also start running the example notebooks run

pixi run --environment lab lab

Using pip¶

then install from the included requirements.txt in the top level book/ directory of the source repository

(pyhf-tutorial) $ python -m pip install --upgrade --requirement book/requirements.txt

Citation¶

pyhf v0.6.0 and later makes it very easy to get the proper citation for the version of the library that you’re using! Simply ask the CLI API to get the properly formatted BibTeX references.

(pyhf-tutorial) $ pyhf --citation
@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}
}

Alternatively, check the website.

Statistics References¶

For more information about some of the theoretical topics covered with pyhf, see Kyle Cranmer’s Statistics and Data Science book.

Questions and Further Information on pyhf¶

For more information on pyhf please check the documentation website. Additionally, if you have a question about the use of pyhf not covered in the documentation, please ask a question the pyhf 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 (through Google Groups).