Skip to content

v0.7.0
Compare
Choose a tag to compare
@matthewfeickert matthewfeickert released this 24 Sep 19:10
· 285 commits to main since this release
v0.7.0
931dd36

This is a minor release from v0.6.3 → v0.7.0.

Important Notes

  • Please note this release has API breaking changes and carefully read these notes while updating your code to the v0.7.0 API.

  • All backends are now fully compatible and tested with Python 3.10. (PR #1809)

  • The pyhf.tensorlib.poisson API now allows for the expected rate parameter lam to be 0 in the case that the observed events n is 0 given that the limit $$\lim_{\lambda \to 0} ,\mathrm{Pois}(n | \lambda)$$ is well defined. (PR #1657)

  • pyhf.readxml.parse now supports reading of XML configurations with absolute paths. To support this, pyhf xlm2json now has a -v/--mount option. (PR #1909)

  • Support for model specifications without a parameter of interest defined is added. (PRs #1638, #1636)

  • The pyhf.parameters.paramsets classes suggested_fixed attribute behavior has been updated. To access the behavior used in pyhf v0.6.x use the suggested_fixed_as_bool attribute. (PR #1639)

  • pyhf.pdf._ModelConfig.par_names is changed to be a property attribute. (PR #2027)

  • The order of model parameters is now sorted by model parameter name. (PR #1625)

  • Support for writing user custom modifiers is added. (PRs #1625, #1644)

  • Performance in pyhf.readxml is increased by improvements to pyhf.readxml.import_root_histogram. (PR #1691)

  • pyhf.contrib.utils.download is now more robust to different target file types. (PRs #1697, #1704)

  • A pyhf.default_backend has been added that is configurable through a default kwarg in pyhf.set_backend. (PR #1646) This is part of work to make pyhf fully automatic differentiable. (Issue #882)

  • Schema validation now allows for both list and pyhf.tensorlib objects to exist in the model specification. (PR #1647)

  • The minimum required dependencies have been updated to support added features:

    • scipy>=1.2.0 (PR #1274)
    • click>=8.0.0 (PRs #1909, #1958)
    • jsonschema>=4.15.0 (PRs #1976, #1979)
    • importlib_resources>=1.4.0 (for Python 3.7, 3.8) (PR #1979)
    • typing_extensions>=3.7.4.3 (for Python 3.7 only) (PRs #1940, #1961)

  • The minimum required backend versions have been updated to support added features:

    • JAX backend requires jax>=0.2.10, jaxlib>=0.1.61 (PR #1962)
    • PyTorch backend requires torch>=1.10.0 (PR #1657)
    • TensorFlow backend requires tensorflow>=2.7.0, tensorflow-probability>=0.11.0 (PRs #1962, #1657)
    • iminuit optimizer requires iminuit>=2.7.0 (PR #1895)
    • 'xmlio' extra requires uproot>=4.1.1 (PR #1567)

Fixes

  • Use improvements to jsonschema.RefResolver to avoid jsonschema.exceptions.RefResolutionError. (PR #1976)

  • Use the conditional maximum likelihood estimators of the nuisance parameters to create the sampling distributions for pyhf.infer.calculators.ToyCalculator. (PR #1610) This follows the joint recommendations of the ATLAS and CMS experiments in Procedure for the LHC Higgs boson search combination in Summer 2011.

Features

Python API

  • The following functions have been added to the pyhf.tensorlib API:

    • pyhf.tensorlib.transpose (PR #1696)
    • pyhf.tensorlib.percentile (PR #817)

  • pyhf.readxml.parse now supports reading of XML configurations with absolute paths with the addition of the mounts optional argument. (PR #1909)

  • Support for overriding the paths for finding schemas is added, using the pyhf installed location as a base via pyhf.utils.schemas. (PRs #1753, #1818)

      >>> from pathlib import Path
  >>> import pyhf.schema
  >>> current_schema_path = pyhf.schema.path
  >>> current_schema_path
  PosixPath('/path/to/your/venv/lib/python3.X/site-packages/pyhf/schemas')
  >>> custom_schema_path = Path("/path/to/custom/pyhf/schema")
  >>> with pyhf.schema(custom_schema_path):
  ...     print(repr(pyhf.schema.path))
  ...
  PosixPath('/path/to/custom/pyhf/schema')
  >>> pyhf.schema.path
  PosixPath('/path/to/your/venv/lib/python3.X/site-packages/pyhf/schemas')

  • In pyhf.workspace.Workspace.model the parameter of interest specified in the measurement may now be overridden using the added poi_name kwarg. (PR #1636)

  • The pyhf.parameters.paramsets classes suggested_fixed attribute behavior has been updated to return a list of bool of length n_parameters. To access the behavior used in pyhf v0.6.x use the suggested_fixed_as_bool attribute. (PR #1639)

  • pyhf.pdf._ModelConfig.par_names is changed to be a property attribute. (PR #2027)

  • The order of model parameters is now sorted by model parameter name. (PR #1625)

      >>> import pyhf
  >>> model = pyhf.simplemodels.correlated_background(
  ...     signal=[12.0, 11.0],
  ...     bkg=[50.0, 52.0],
  ...     bkg_up=[45.0, 57.0],
  ...     bkg_down=[55.0, 47.0],
  ... )
  >>> model.config.par_order
  ['correlated_bkg_uncertainty', 'mu']
  >>> model.config.par_names
  ['correlated_bkg_uncertainty', 'mu']

  • Support for writing user custom modifiers is added.
    (PRs #1625, #1644) This is still in the stage where it is targeted at expert users.

  • {modifier}_builder classes are added for all modifiers. (PRs #1625) For example, pyhf.modifiers.histosys.histosys_builder.

  • When using pyhf.writexml and the normfactor parameter config is missing inits or bounds, fall back to using default values. (PRs #1819)

  • Supported options for pyhf.infer.hypotest can now be passed as kwargs through the pyhf.infer.intervals.upper_limits.upper_limit API. (PR #1613) This now enables things like using pyhf.infer.calculators.ToyCalculator as the calculator used for the hypothesis test scan:

      >>> import numpy as np
  >>> import pyhf
  >>> pyhf.set_backend("jax")
  >>> model = pyhf.simplemodels.uncorrelated_background(
  ...     signal=[12.0, 11.0], bkg=[50.0, 52.0], bkg_uncertainty=[3.0, 7.0]
  ... )
  >>> observations = [51, 48]
  >>> data = pyhf.tensorlib.astensor(observations + model.config.auxdata)
  >>> scan = np.linspace(0, 5, 21)
  >>> obs_limit, exp_limits, (scan, results) = pyhf.infer.intervals.upper_limits.upper_limit(
  ...     data, model, scan, return_results=True, calctype="toybased", ntoys=3000
  ... )

  • Allow for fit parameter values from required fits in pyhf.infer.test_statistics functions to be returned by use of return_fitted_pars kwarg with the pyhf.infer.test_statistics functions and return_calculator kwarg with pyhf.infer.hypotest. (PR #1554)

  • A validate kwarg has been added to pyhf.workspace.Workspace and
    pyhf.pdf.Model to allow skipping validation. (PR #1646) This should only be used by expert users who understand the risks.

  • A pyhf.default_backend has been added that is configurable through a default kwarg in pyhf.set_backend. (PR #1646) This allows setting the pyhf.default_backend to be different from the value of pyhf.tensorlib returned by pyhf.get_backend, which can be useful in situations where differentiable model construction is needed.

      >>> import jax
  >>> import pyhf
  >>> pyhf.set_backend("jax", default=True)
  >>> pyhf.set_backend("numpy")
  >>> pyhf.get_backend()
  (<pyhf.tensor.numpy_backend.numpy_backend object at 0x...>, <pyhf.optimize.scipy_optimizer object at 0x...>)
  >>> pyhf.default_backend
  <pyhf.tensor.jax_backend.jax_backend object at 0x...>
  >>> def example_op(x):
  ...     return 2 * pyhf.default_backend.power(pyhf.default_backend.astensor(x), 3)
  ...
  >>> example_op([2.0])
  DeviceArray([16.], dtype=float64)
  >>> jax.jacrev(jax.jit(example_op))([2.0])
  [DeviceArray([24.], dtype=float64, weak_type=True)]

  • Schema validation now allows for both list and pyhf.tensorlib objects to exist in the model specification. (PR #1647)

        >>> import pyhf
    >>> signal = pyhf.tensorlib.astensor([12.0, 11.0])
    >>> background = pyhf.tensorlib.astensor([50.0, 52.0])
    >>> background_uncertainty = pyhf.tensorlib.astensor([3.0, 7.0])
    >>> model = pyhf.simplemodels.uncorrelated_background(
    ...     signal=signal, bkg=background, bkg_uncertainty=background_uncertainty
    ... )

CLI API

  • The pyhf xlm2json CLI API now has a -v/--mount option to support reading XML configurations with absolute paths. (PR #1909) Similar to Docker volume mounts, the options allows a user to pass two fields separated by a colon (:). The first field is a local path and the second field is the absolute path specified in the XML configuration to be substituted. Without the -v/--mount option a user would have to manually edit the absolute path in each XML file it appeared in!

    pyhf xml2json \
    --mount /local/path/to/workspace:/absolute/path/to/replace/inside/xml \
    --output-file workspace.json \
    workspace/analysis_config.xml

Deprecations

Python API

  • The pyhf.infer.intervals.upperlimit API has been deprecated in favor of pyhf.infer.intervals.upper_limits.upper_limit.
    The pyhf.infer.intervals.upperlimit API will removed in pyhf v0.9.0. (PR #1274)

Removals

Python API

  • The pyhf.simplemodels.hepdata_like API, deprecated since pyhf v0.6.2, has been removed. (PR #1670) Use the pyhf.simplemodels.uncorrelated_background API instead.

  • pyhf.workspace.Workspace's parameters attribute is removed in favor of using pyhf.pdf._ModelConfig's parameters. (PR #1625)

  • pyhf.workspace.Workspace.get_measurement has the poi_name kwarg removed. (PR #1636)

Contributors

v0.7.0 benefited from contributions from:

  • Alexander Held
  • Mason Proffitt
  • Lars Henkelmann
  • Aryan Roy
  • Graeme Watt
  • Jerry Ling
  • Nathan Simpson
  • Beojan Stanislaus

Changes

New Contributors

Full Changelog: v0.6.3...v0.7.0

Contributors

kratsg, lukasheinrich, and 12 other contributors
Assets 2
Loading
0 Join discussion