diff --git a/docs/conf.py b/docs/conf.py index 276d85a52b..f9c747400c 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -500,5 +500,7 @@ def setup(app): r'https://doi\.org/10\.31526/.*', # https://doi.org/10.1051/epjconf/x DOI URLs will periodically generate 500 Server Error r'https://doi\.org/10\.1051/epjconf/.*', + # tags for a release won't exist until it is made, but the release notes need to reference them + r'https://github.com/scikit-hep/pyhf/releases/tag/.*', ] linkcheck_retries = 50 diff --git a/docs/contributors.rst b/docs/contributors.rst index a0da954d61..7fdf9fcce0 100644 --- a/docs/contributors.rst +++ b/docs/contributors.rst @@ -27,6 +27,7 @@ Contributors include: - Mason Proffitt - Lars Henkelmann - Aryan Roy +- Graeme Watt - Jerry Ling - Nathan Simpson - Beojan Stanislaus diff --git a/docs/release-notes.rst b/docs/release-notes.rst index 0ce738d57a..87e9335ef9 100644 --- a/docs/release-notes.rst +++ b/docs/release-notes.rst @@ -2,6 +2,7 @@ Release Notes ============= +.. include:: release-notes/v0.7.0.rst .. include:: release-notes/v0.6.3.rst .. include:: release-notes/v0.6.2.rst .. include:: release-notes/v0.6.1.rst diff --git a/docs/release-notes/v0.7.0.rst b/docs/release-notes/v0.7.0.rst new file mode 100644 index 0000000000..f6c17aca9f --- /dev/null +++ b/docs/release-notes/v0.7.0.rst @@ -0,0 +1,291 @@ +|release v0.7.0|_ +================= + +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 :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 :math:`\lim_{\lambda \to 0} \,\mathrm{Pois}(n | \lambda)` is well defined. + (PR :pr:`1657`) +* :func:`pyhf.readxml.parse` now supports reading of XML configurations with absolute paths. + To support this, ``pyhf xlm2json`` now has a ``-v/--mount`` option. + (PR :pr:`1909`) +* Support for model specifications without a parameter of interest defined is added. + (PRs :pr:`1638`, :pr:`1636`) +* The :class:`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 :pr:`1639`) +* ``pyhf.pdf._ModelConfig.par_names`` is changed to be a property attribute. + (PR :pr:`2027`) +* The order of model parameters is now sorted by model parameter name. + (PR :pr:`1625`) +* Support for writing user custom modifiers is added. + (PRs :pr:`1625`, :pr:`1644`) +* Performance in :class:`pyhf.readxml` is increased by improvements to + :func:`pyhf.readxml.import_root_histogram`. + (PR :pr:`1691`) +* :func:`pyhf.contrib.utils.download` is now more robust to different target file types. + (PRs :pr:`1697`, :pr:`1704`) +* A ``pyhf.default_backend`` has been added that is configurable through a + ``default`` kwarg in :func:`pyhf.set_backend`. + (PR :pr:`1646`) + This is part of work to make ``pyhf`` fully automatic differentiable. + (Issue :issue:`882`) +* Schema validation now allows for both :class:`list` and ``pyhf.tensorlib`` objects + to exist in the model specification. + (PR :pr:`1647`) +* The minimum required dependencies have been updated to support added features: + + - ``scipy>=1.2.0`` (PR :pr:`1274`) + - ``click>=8.0.0`` (PRs :pr:`1909`, :pr:`1958`) + - ``jsonschema>=4.15.0`` (PRs :pr:`1976`, :pr:`1979`) + - ``importlib_resources>=1.4.0`` (for Python 3.7, 3.8) (PR :pr:`1979`) + - ``typing_extensions>=3.7.4.3`` (for Python 3.7 only) (PRs :pr:`1940`, :pr:`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 :pr:`1962`) + - PyTorch backend requires ``torch>=1.10.0`` (PR :pr:`1657`) + - TensorFlow backend requires ``tensorflow>=2.7.0``, ``tensorflow-probability>=0.11.0`` (PRs :pr:`1962`, :pr:`1657`) + - iminuit optimizer requires ``iminuit>=2.7.0`` (PR :pr:`1895`) + - ``'xmlio'`` extra requires ``uproot>=4.1.1`` (PR :pr:`1567`) + +Fixes +----- + +* Use improvements to ``jsonschema.RefResolver`` to avoid + ``jsonschema.exceptions.RefResolutionError``. + (PR :pr:`1976`) + +* Use the conditional maximum likelihood estimators of the nuisance parameters + to create the sampling distributions for :class:`pyhf.infer.calculators.ToyCalculator`. + (PR :pr:`1610`) + This follows the joint recommendations of the ATLAS and CMS experiments in + |LHC Higgs search combination procedure|_. + +Features +-------- + +Python API +~~~~~~~~~~ + +* The following functions have been added to the ``pyhf.tensorlib`` API: + + + - ``pyhf.tensorlib.transpose`` (PR :pr:`1696`) + - ``pyhf.tensorlib.percentile`` (PR :pr:`817`) + +* :func:`pyhf.readxml.parse` now supports reading of XML configurations with absolute paths + with the addition of the ``mounts`` optional argument. + (PR :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 :pr:`1753`, :pr:`1818`) + + .. code:: pycon + + >>> 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 :func:`pyhf.workspace.Workspace.model` the parameter of interest specified + in the measurement may now be overridden using the added ``poi_name`` kwarg. + (PR :pr:`1636`) + +* The :class:`pyhf.parameters.paramsets` classes ``suggested_fixed`` attribute behavior has + been updated to return a :class:`list` of :class:`bool` of length ``n_parameters``. + To access the behavior used in ``pyhf`` ``v0.6.x`` use the ``suggested_fixed_as_bool`` attribute. + (PR :pr:`1639`) + +* ``pyhf.pdf._ModelConfig.par_names`` is changed to be a property attribute. + (PR :pr:`2027`) + +* The order of model parameters is now sorted by model parameter name. + (PR :pr:`1625`) + + .. code:: pycon + + >>> 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 :pr:`1625`, :pr:`1644`) + This is still in the stage where it is `targeted at expert users + `_. + +* ``{modifier}_builder`` classes are added for all modifiers. + (PRs :pr:`1625`) + For example, :class:`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 :pr:`1819`) + +* Supported options for :func:`pyhf.infer.hypotest` can now be passed as kwargs + through the :func:`pyhf.infer.intervals.upper_limits.upper_limit` API. + (PR :pr:`1613`) + This now enables things like using :class:`pyhf.infer.calculators.ToyCalculator` + as the calculator used for the hypothesis test scan: + + .. code:: pycon + + >>> 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 + :func:`pyhf.infer.hypotest`. + (PR :pr:`1554`) + +* A ``validate`` kwarg has been added to :func:`pyhf.workspace.Workspace` and + :func:`pyhf.pdf.Model` to allow skipping validation. + (PR :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 :func:`pyhf.set_backend`. + (PR :pr:`1646`) + This allows setting the ``pyhf.default_backend`` to be different from the value of + ``pyhf.tensorlib`` returned by :func:`pyhf.get_backend`, which can be useful in situations + where differentiable model construction is needed. + + .. code:: pycon + + >>> import jax + >>> import pyhf + >>> pyhf.set_backend("jax", default=True) + >>> pyhf.set_backend("numpy") + >>> pyhf.get_backend() + (, ) + >>> pyhf.default_backend + + >>> 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 :class:`list` and ``pyhf.tensorlib`` objects + to exist in the model specification. + (PR :pr:`1647`) + + .. code:: pycon + + >>> 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 :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! + + .. code:: console + + 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 :func:`pyhf.infer.intervals.upperlimit` API has been deprecated in favor of + :func:`pyhf.infer.intervals.upper_limits.upper_limit`. + The :func:`pyhf.infer.intervals.upperlimit` API will removed in ``pyhf`` ``v0.9.0``. + (PR :pr:`1274`) + +Removals +-------- + +Python API +~~~~~~~~~~ + +* The :func:`pyhf.simplemodels.hepdata_like` API, deprecated since ``pyhf`` + ``v0.6.2``, has been removed. + (PR :pr:`1670`) + Use the :func:`pyhf.simplemodels.uncorrelated_background` API instead. + +* :class:`pyhf.workspace.Workspace`'s ``parameters`` attribute is removed in favor of + using :class:`pyhf.pdf._ModelConfig`'s ``parameters``. + (PR :pr:`1625`) + +* :func:`pyhf.workspace.Workspace.get_measurement` has the ``poi_name`` kwarg removed. + (PR :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 + +.. |release v0.7.0| replace:: ``v0.7.0`` +.. _`release v0.7.0`: https://github.com/scikit-hep/pyhf/releases/tag/v0.7.0 + +.. _LHC Higgs search combination procedure: https://inspirehep.net/literature/1196797 +.. |LHC Higgs search combination procedure| replace:: *Procedure for the LHC Higgs boson search combination in Summer 2011* diff --git a/src/pyhf/cli/rootio.py b/src/pyhf/cli/rootio.py index d1312c2641..053304f381 100644 --- a/src/pyhf/cli/rootio.py +++ b/src/pyhf/cli/rootio.py @@ -27,7 +27,7 @@ def cli(): @click.option( '-v', '--mount', - help='Consists of two fields, separated by a colon character ( : ). The first field is the local path to where files are located, the second field is the path where the file or directory are saved in the XML configuration. This is similar in spirit to docker.', + help='Consists of two fields, separated by a colon character ( : ). The first field is the local path to where files are located, the second field is the path where the file or directory are saved in the XML configuration. This is similar in spirit to Docker.', type=VolumeMountPath(exists=True, resolve_path=True, path_type=Path), default=None, multiple=True,