Release Notes

v0.6.0

This is a minor release from v0.5.4 → v0.6.0.

Important Notes

  • Please note this release has API breaking changes and carefully read these notes while updating your code to the v0.6.0 API. Perhaps most relevant is the changes to the pyhf.infer.hypotest() API, which now uses a calctype argument to differentiate between using an asymptotic calculator or a toy calculator, and a test_stat kwarg to specify which test statistic the calculator should use, with 'qtilde', coresponding to pyhf.infer.test_statistics.qmu_tilde(), now the default option. It also relies more heavily on using kwargs to pass options through to the optimizer.

  • Support for the discovery test statistic, \(q_{0}\), has now been added through the pyhf.infer.test_statistics.q0() API.

  • Support for pseudoexperiments (toys) has been added through the pyhf.infer.calculators.ToyCalculator() API. Please see the corresponding example notebook for more detailed exploration of the API.

  • The minuit extra, python -m pip install pyhf[minuit], now uses and requries the iminuit v2.X release series and API. Note that iminuit v2.X can result in slight differences in minimization results from iminuit v1.X.

  • The documentation will now be versioned with releases on ReadTheDocs. Please use pyhf.readthedocs.io to access the documentation for the latest stable realease of pyhf.

  • pyhf is transtioning away from Stack Overflow to GitHub Discussions for resolving user questions not covered in the documentation. Please check the GitHub Discussions page to search for discussions addressing your questions and to open up a new discussion if your question is not covered.

  • pyhf has published a paper in the Journal of Open Source Software. JOSS DOI Please make sure to include the paper reference in all citations of pyhf, as documented in the Use and Citations section of the documentation.

Fixes

  • Fix bug where all extras triggered warning for installation of the contrib extra.

  • float-like values are used in division for pyhf.writexml().

  • Model.spec now supports building new models from existing models.

  • \(p\)-values are now reported based on their quantiles, instead of interpolating test statistics and converting to \(p\)-values.

  • Namespace collisions between uproot3 and uproot/uproot4 have been fixed for the xmlio extra.

  • The normsys modifier now uses the pyhf.interpolators.code4 interpolation method by default.

  • The histosys modifier now uses the pyhf.interpolators.code4p interpolation method by default.

Features

Python API

  • The tensorlib API now supports a tensorlib.to_numpy and tensorlib.ravel API.

  • The pyhf.infer.calculators.ToyCalculator() API has been added to support pseudoexperiments (toys).

  • The emperical test statistic distribution API has been added to help support the ToyCalculator API.

  • Add a tolerance kwarg to the optimizer API to set a float value as a tolerance for termination of the fit.

  • The pyhf.optimize.opt_minuit.minuit_optimizer() optimizer now can return correlations of the fitted parameters through use of the return_correlation Boolean kwarg.

  • Add the pyhf.utils.citation API to get a str of the preferred BibTeX entry for citation of the version of pyhf installed. See the example for the CLI API for more information.

  • The pyhf.infer.hypotest() API now uses a calctype argument to differentiate between using an asymptotic calculator or a toy calculator, and a test_stat kwarg to specify which test statistic to use. It also relies more heavily on using kwargs to pass options through to the optimizer.

  • The default test_stat kwarg for pyhf.infer.hypotest() and the calculator APIs is 'qtilde', which corresponds to the alternative test statistic pyhf.infer.test_statistics.qmu_tilde().

  • The return type of \(p\)-value like functions is now a 0-dimensional tensor (with shape ()) instead of a float. This is required to support end-to-end automatic differenation in future releases.

CLI API

  • The CLI API now suppoerts a --citation or --cite option to print the preferred BibTeX entry for citation of the version of pyhf installed.

$ pyhf --citation
@software{pyhf,
  author = "{Heinrich, Lukas and Feickert, Matthew and Stark, Giordon}",
  title = "{pyhf: v0.6.0}",
  version = {0.6.0},
  doi = {10.5281/zenodo.1169739},
  url = {https://github.com/scikit-hep/pyhf},
}

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

Contributors

v0.6.0 benefited from contributions from:

  • Alexander Held

  • Marco Gorelli

  • Pradyumna Rahul K

  • Eric Schanet

  • Henry Schreiner

v0.5.4

This is a patch release from v0.5.3 → v0.5.4.

Fixes

  • Require uproot3 instead of uproot v3.X releases to avoid conflicts when uproot4 is installed in an environment with uproot v3.X installed and namespace conflicts with uproot-methods. Adoption of uproot3 in v0.5.4 will ensure v0.5.4 works far into the future if XML and ROOT I/O through uproot is required.

Example:

Without the v0.5.4 patch release there is a regression in using uproot v3.X and uproot4 in the same environment (which was swiftly identified and patched by the fantastic uproot team)

$ python -m pip install "pyhf[xmlio]<0.5.4"
$ python -m pip list | grep "pyhf\|uproot"
pyhf           0.5.3
uproot         3.13.1
uproot-methods 0.8.0
$ python -m pip install uproot4
$ python -m pip list | grep "pyhf\|uproot"
pyhf           0.5.3
uproot         4.0.0
uproot-methods 0.8.0
uproot4        4.0.0

this is resolved in v0.5.4 with the requirement of uproot3

$ python -m pip install "pyhf[xmlio]>=0.5.4"
$ python -m pip list | grep "pyhf\|uproot"
pyhf            0.5.4
uproot3         3.14.1
uproot3-methods 0.10.0
$ python -m pip install uproot4 # or uproot
$ python -m pip list | grep "pyhf\|uproot"
pyhf            0.5.4
uproot          4.0.0
uproot3         3.14.1
uproot3-methods 0.10.0
uproot4         4.0.0

v0.5.3

This is a patch release from v0.5.2 → v0.5.3.

Fixes

  • Workspaces are now immutable

  • ShapeFactor support added to XML reading and writing

  • An error is raised if a fit initialization parameter is outside of its bounds (preventing hypotest with POI outside of bounds)

Features

Python API

  • Inverting hypothesis tests to get upper limits now has an API with pyhf.infer.intervals.upperlimit

  • Building workspaces from a model and data added with pyhf.workspace.build

CLI API

  • Added CLI API for pyhf.infer.fit: pyhf fit

  • pyhf combine now allows for merging channels: pyhf combine --merge-channels --join <join option>

  • Added utility to download archived pyhf pallets (workspaces + patchsets) to contrib module: pyhf contrib download

Contributors

v0.5.3 benefited from contributions from:

  • Karthikeyan Singaravelan