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#
$ python3 -m venv pyhf-tutorial
$ source pyhf-tutorial/bin/activate
(pyhf-tutorial) $ python -m pip install --upgrade pip setuptools wheel
First we need to set up the ‘views’ with the right paths to ensure we use the correct pip
$ export ATLAS_LOCAL_ROOT_BASE=/cvmfs/atlas.cern.ch/repo/ATLASLocalRootBase
$ source $ATLAS_LOCAL_ROOT_BASE/user/atlasLocalSetup.sh
$ lsetup "views LCG_98python3 x86_64-centos7-gcc8-opt"
$ export PYTHONPATH=/cvmfs/sft.cern.ch/lcg/views/LCG_98python3/x86_64-centos7-gcc8-opt/python:/cvmfs/sft.cern.ch/lcg/views/LCG_98python3/x86_64-centos7-gcc8-opt/lib
Then we can go ahead and create the virtual environment
$ python3 -m venv pyhf-tutorial
$ source pyhf-tutorial/bin/activate
(pyhf-tutorial) $ python -m pip install --upgrade pip setuptools wheel
First we need to set up the ‘views’ with the right paths to ensure we use the correct pip
$ export ATLAS_LOCAL_ROOT_BASE=/cvmfs/atlas.cern.ch/repo/ATLASLocalRootBase
$ source $ATLAS_LOCAL_ROOT_BASE/user/atlasLocalSetup.sh
$ lsetup "views LCG_98python3 x86_64-slc6-gcc8-opt"
$ export PYTHONPATH=/cvmfs/sft.cern.ch/lcg/views/LCG_98python3/x86_64-slc6-gcc8-opt/python:/cvmfs/sft.cern.ch/lcg/views/LCG_98python3/x86_64-slc6-gcc8-opt/lib
Then we can go ahead and create the virtual environment
$ python3 -m venv pyhf-tutorial
$ source pyhf-tutorial/bin/activate
(pyhf-tutorial) $ python -m pip install --upgrade pip setuptools wheel
As pyhf
is pure Python it is possible to install and run a version of it directly in your browser using Pyodide.
You can try out the live WebAssembly version of the user guide in JupyterLite now by visiting the live view of the website.
Not all parts of this user guide are able to run in Pyodide, but the pure Python parts will work.
Once you have a virtual environment set up, you can use source pyhf-tutorial/bin/activate
to get back into it again. 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
from either PyPI with pip
(pyhf-tutorial) $ python -m pip install pyhf
or Conda-forge
(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]'
The ‘xmlio’ extra additionally installs uproot
to read ROOT
files.
(pyhf-tutorial) $ python -m pip install 'pyhf[torch,tensorflow]'
The ‘torch’ extra installs pytorch
and the ‘tensorflow’ extra installs tensorflow
.
(pyhf-tutorial) $ python -m pip install 'pyhf[minuit]'
The ‘minuit’ extra installs iminuit
.
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
then you can just install from the included requirements.txt
in the top level binder/
directory of the source repository
(pyhf-tutorial) $ python -m pip install --upgrade --requirement binder/requirements.txt
If you want to also get the dependencies to build and explore the Jupyter Book form of the tutorial you can install them with
(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.5}",
version = {0.7.5},
doi = {10.5281/zenodo.1169739},
url = {https://doi.org/10.5281/zenodo.1169739},
note = {https://github.com/scikit-hep/pyhf/releases/tag/v0.7.5}
}
@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).