Merge pull request #40 from SpeysideHEP/gaussian

Add Normal/MultivariateNormal PDFs

.github/workflows/tests.yml

@@ -35,4 +35,5 @@ jobs:
         python -m pip install -e .
     - name: Test with pytest
       run: |
+        python -c 'import spey;spey.about()'
         pytest --cov=spey tests/*py #--cov-fail-under 99

.zenodo.json

@@ -1,8 +1,8 @@
 {
     "description": "smooth inference for reinterpretation studies",
     "license": "MIT",
-    "title": "SpeysideHEP/spey: v0.1.8",
-    "version": "v0.1.8",
+    "title": "SpeysideHEP/spey: v0.1.9",
+    "version": "v0.1.9",
     "upload_type": "software",
     "creators": [
         {
@@ -18,7 +18,9 @@
         "statistics",
         "fitting",
         "scipy",
-        "auto-differentiation"
+        "auto-differentiation",
+        "inference",
+        "differentiable programming"
     ],
     "related_identifiers": [
         {
@@ -29,7 +31,7 @@
         },
         {
             "scheme": "url",
-            "identifier": "https://github.com/SpeysideHEP/spey/tree/v0.1.8",
+            "identifier": "https://github.com/SpeysideHEP/spey/tree/v0.1.9",
             "relation": "isSupplementTo"
         },
         {

CITATIONS.bib

@@ -15,11 +15,11 @@ @article{Araz:2023bwx
 
 @software{spey_zenodo,
     author    = {Araz, Jack Y.},
-    title     = {SpeysideHEP/spey: v0.1.8},
+    title     = {SpeysideHEP/spey: v0.1.9},
     month     = feb,
     year      = 2024,
     publisher = {Zenodo},
-    version   = {v0.1.8},
+    version   = {v0.1.9},
     doi       = {10.5281/zenodo.10671596},
     url       = {https://doi.org/10.5281/zenodo.10671596}
 }

docs/api.rst

@@ -137,6 +137,8 @@ Simple PDFs
     :toctree: _generated/
 
     simple_pdf.Poisson
+    simple_pdf.Gaussian
+    simple_pdf.MultivariateNormal
 
 
 Exceptions

docs/known_issues.rst

@@ -1,5 +1,8 @@
 Known Issues
 ============
 
-* It has been observed that the Scipy version and its compiler, which is used for maximising and profiling
-  the likelihood can have a slight effect on the results.
+* It has been observed that the Scipy version and its compiler, which is used for maximising and profiling the likelihood can have a slight effect on the results.
+
+* NumPy v2.0.0 does not work with autograd, which is used in "default_pdf.XXX" likelihoods. The dependencies are reformulated accordingly.
+
+* There are some dependency issues in some sub-versions of Python 3.12. This is due to deprecated system packages. Updates can be followed in PR `#39 <https://github.com/SpeysideHEP/spey/pull/39>`_.

docs/plugins.rst

@@ -3,6 +3,32 @@
 Plug-ins
 ========
 
+.. list-table::
+   :header-rows: 1
+
+   * - Keyword
+     - Summary
+   * - ``'default_pdf.uncorrelated_background'``
+     - :ref:`Combination of Poisson and Gaussian PDF, assuming uncorrelated bins. <uncorrelated_background>`
+   * - ``'default_pdf.correlated_background'``
+     - :ref:`Combination of Poisson and Gaussian PDF, with correlated bins. <correlated_background>`
+   * - ``'default_pdf.third_moment_expansion'``
+     - :ref:`Simplified likelihood, extended with third moments of the background. <third_moment_expansion>`
+   * - ``'default_pdf.effective_sigma'``
+     - :ref:`Simplified likelihood, extended with asymmetric uncertainties.  <effective_sigma>`
+   * - ``'default_pdf.poisson'``
+     - :ref:`Poisson distribution, without uncertainties.  <poisson>`
+   * - ``'default_pdf.normal'``
+     - :ref:`Gaussian distribution.  <normal>`
+   * - ``'default_pdf.multivariate_normal'``
+     - :ref:`Multivariate Normal distribution.  <multinormal>`
+   * - ``'pyhf'``
+     - `External plug-in <https://spey-pyhf.readthedocs.io>`_ uses ``pyhf`` to construct the likelihoods.
+   * - ``'pyhf.uncorrelated_background'``
+     - `External plug-in <https://spey-pyhf.readthedocs.io>`_ constructs ``pyhf``-based uncorrelated likelihoods.
+   * - ``'pyhf.simplify'``
+     - `See doc. <https://spey-pyhf.readthedocs.io/en/main/simplify.html>`_ converts full ``pyhf`` likelihoods into simplified framework.
+
 .. meta::
     :property=og:title: Plug-ins
     :property=og:description: Currently supported likelihood prescriptions.
@@ -61,6 +87,8 @@ All default plug-ins are defined using the following main likelihood structure
 
 The first term represents the primary model, and the second represents the constraint model.
 
+.. _uncorrelated_background:
+
 ``'default_pdf.uncorrelated_background'``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -110,6 +138,8 @@ This particular example implements a two-bin histogram with uncorrelated bins. T
 For all the properties of :obj:`~spey.StatisticalModel` class, we refer the reader to the corresponding
 API description.
 
+.. _correlated_background:
+
 ``'default_pdf.correlated_background'``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -159,6 +189,8 @@ as expected.
  * ``analysis`` (optional): Unique identifier for the analysis.
  * ``xsection`` (optional): Cross-section value for the signal hypothesis. Units determined by the user.
 
+.. _third_moment_expansion:
+
 ``'default_pdf.third_moment_expansion'``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -230,6 +262,7 @@ reduced the exclusion limit.
  * ``analysis`` (optional): Unique identifier for the analysis.
  * ``xsection`` (optional): Cross-section value for the signal hypothesis. Units determined by the user.
 
+.. _effective_sigma:
 
 ``'default_pdf.effective_sigma'``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -289,6 +322,8 @@ Once again, the exclusion limit can be computed as
  * ``analysis`` (optional): Unique identifier for the analysis.
  * ``xsection`` (optional): Cross-section value for the signal hypothesis. Units determined by the user.
 
+.. _poisson:
+
 ``'default_pdf.poisson'``
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -320,6 +355,78 @@ It can take any number of yields.
  * ``analysis`` (optional): Unique identifier for the analysis.
  * ``xsection`` (optional): Cross-section value for the signal hypothesis. Units determined by the user.
 
+.. _normal:
+
+``'default_pdf.normal'``
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Simple Normal distribution implementation;
+
+.. math::
+
+    \mathcal{L}(\mu) = \prod_{i\in{\rm bins}} \frac{1}{\sigma^i \sqrt{2\pi}} \exp\left[-\frac{1}{2} \left(\frac{\mu n_s^i + n_b^i - n^i}{\sigma^i} \right)^2 \right]
+
+It can take any number of yields.
+
+.. code-block:: python3
+    :linenos:
+
+    >>> pdf_wrapper = spey.get_backend("default_pdf.normal")
+    >>> statistical_model = pdf_wrapper(
+    ...     signal_yields=[12.0, 15.0],
+    ...     background_yields=[50.0,48.0],
+    ...     data=[36, 33],
+    ...     absolute_uncertainties=[20.0, 10.0],
+    ...     analysis="example",
+    ...     xsection=0.123,
+    ... )
+
+**Arguments:**
+
+ * ``signal_yields``: keyword for signal yields. It can take one or more values as a list or NumPy array.
+ * ``background_yields``: keyword for background-only expectations. It can take one or more values as a list or NumPy array.
+ * ``data``: keyword for observations. It can take one or more values as a list or NumPy array.
+ * ``absolute_uncertainties``: absolute uncertainties on the background
+ * ``analysis`` (optional): Unique identifier for the analysis.
+ * ``xsection`` (optional): Cross-section value for the signal hypothesis. Units determined by the user.
+
+
+.. _multinormal:
+
+``'default_pdf.multivariate_normal'``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Simple Normal distribution implementation;
+
+.. math::
+
+    \mathcal{L}(\mu) = \frac{1}{\sqrt{(2\pi)^k {\rm det}[\Sigma] }} \exp\left[-\frac{1}{2} (\mu n_s + n_b - n)\Sigma^{-1} (\mu n_s + n_b - n)^T \right]
+
+It can take any number of yields.
+
+.. code-block:: python3
+    :linenos:
+
+    >>> pdf_wrapper = spey.get_backend("default_pdf.multivariate_normal")
+    >>> statistical_model = pdf_wrapper(
+    ...     signal_yields=[12.0, 15.0],
+    ...     background_yields=[50.0,48.0],
+    ...     data=[36, 33],
+    ...     covariance_matrix=[[144.0,13.0], [25.0, 256.0]],
+    ...     analysis="example",
+    ...     xsection=0.123,
+    ... )
+
+**Arguments:**
+
+ * ``signal_yields``: keyword for signal yields. It can take one or more values as a list or NumPy array.
+ * ``background_yields``: keyword for background-only expectations. It can take one or more values as a list or NumPy array.
+ * ``data``: keyword for observations. It can take one or more values as a list or NumPy array.
+ * ``covariance_matrix``: covariance matrix (square matrix)
+ * ``analysis`` (optional): Unique identifier for the analysis.
+ * ``xsection`` (optional): Cross-section value for the signal hypothesis. Units determined by the user.
+
+
 
 External Plug-ins
 -----------------

docs/releases/changelog-v0.1.md

@@ -14,6 +14,9 @@ Specific upgrades for the latest release can be found [here](https://github.com/
   (Request by Veronica Sanz for EFT studies).
   ([#22](https://github.com/SpeysideHEP/spey/pull/22))
 
+* Normal and multivariate normal distributions have been added (for integration to Contur, requested by Jon Butterworth and Joe Egan).
+  ([#40](https://github.com/SpeysideHEP/spey/pull/40))
+
 ## Improvements
 
 * Backend inspection has been added for the models that act like intermediate functions.
@@ -66,9 +69,13 @@ Specific upgrades for the latest release can be found [here](https://github.com/
 * Bug fix in signal uncertainty synthesizer
   ([#34](https://github.com/SpeysideHEP/spey/pull/34))
 
-* Signal uncertainties were causing a narrower $\chi^2$ distribution due to the weight of the constraint term. 
+* Signal uncertainties were causing a narrower $\chi^2$ distribution due to the weight of the constraint term.
   ([#38](https://github.com/SpeysideHEP/spey/pull/38))
 
+* Scipy and Autograd version limitations have been relieved. But there is a clash with numpy v2.0
+  so numpy version has been limited to less than 2.0.
+  ([#40](https://github.com/SpeysideHEP/spey/pull/40))
+
 ## Contributors
 
 This release contains contributions from (in alphabetical order):

setup.py

@@ -7,9 +7,9 @@
     version = f.readlines()[-1].split()[-1].strip("\"'")
 
 requirements = [
-    "numpy>=1.21.6",
-    "scipy==1.10.0",
-    "autograd==1.5",
+    "numpy>=1.21.6, <2.0.0",
+    "scipy>=1.10.0",
+    "autograd>=1.5",
     "semantic_version~=2.10",
     "tqdm>=4.64.0",
     "requests>=2.31.0",
@@ -21,6 +21,8 @@
     "default_pdf.third_moment_expansion = spey.backends.default_pdf:ThirdMomentExpansion",
     "default_pdf.effective_sigma = spey.backends.default_pdf:EffectiveSigma",
     "default_pdf.poisson = spey.backends.default_pdf.simple_pdf:Poisson",
+    "default_pdf.normal = spey.backends.default_pdf.simple_pdf:Gaussian",
+    "default_pdf.multivariate_normal = spey.backends.default_pdf.simple_pdf:MultivariateNormal",
 ]
 
 setup(

src/spey/__init__.py

@@ -3,7 +3,7 @@
 import re
 import sys
 import textwrap
-from typing import Any, Callable, Dict, List, Optional, Text, Tuple, Union, Literal
+from typing import Any, Callable, Dict, List, Literal, Optional, Text, Tuple, Union
 
 import numpy as np
 import pkg_resources
@@ -14,7 +14,7 @@
 from spey.interface.statistical_model import StatisticalModel, statistical_model_wrapper
 from spey.system import logger
 from spey.system.exceptions import PluginError
-from spey.system.webutils import get_bibtex, check_updates, ConnectionError
+from spey.system.webutils import ConnectionError, check_updates, get_bibtex
 
 from ._version import __version__
 from .about import about

src/spey/_version.py

@@ -1,3 +1,3 @@
 """Version number (major.minor.patch[-label])"""
 
-__version__ = "0.1.8"
+__version__ = "0.1.9"