Merge pull request #33 from SpeysideHEP/dev

logging, gradients, and bibtex

.github/workflows/tests.yml

@@ -18,7 +18,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.9", "3.10", "3.11"]
+        python-version: ["3.8", "3.9", "3.10", "3.11"]
         os: [ubuntu-latest, macos-latest]
 
     steps:

.zenodo.json

@@ -1,8 +1,8 @@
 {
     "description": "smooth inference for reinterpretation studies",
     "license": "MIT",
-    "title": "SpeysideHEP/spey: v0.1.5",
-    "version": "v0.1.5",
+    "title": "SpeysideHEP/spey: v0.1.6",
+    "version": "v0.1.6",
     "upload_type": "software",
     "creators": [
         {
@@ -29,7 +29,7 @@
         },
         {
             "scheme": "url",
-            "identifier": "https://github.com/SpeysideHEP/spey/tree/v0.1.5",
+            "identifier": "https://github.com/SpeysideHEP/spey/tree/v0.1.6",
             "relation": "isSupplementTo"
         },
         {

docs/api.rst

@@ -16,15 +16,19 @@ Top-Level
 
     version
     about
+    check_updates
     ExpectationType
     AvailableBackends
     get_backend
     get_backend_metadata
+    get_backend_bibtex
+    cite
     reset_backend_entries
     statistical_model_wrapper
     helper_functions.correlation_to_covariance
     helper_functions.covariance_to_correlation
     optimizer.core.fit
+    set_log_level
 
 Main Classes
 ------------
@@ -82,6 +86,17 @@ Hypothesis testing
     asymptotic_calculator.compute_asymptotic_confidence_level
     toy_calculator.compute_toy_confidence_level
 
+Gradient Tools
+--------------
+
+.. currentmodule:: spey.math
+
+.. autosummary:: 
+    :toctree: _generated/
+
+    value_and_grad
+    hessian
+
 Default Backends
 ----------------
 

docs/releases/changelog-v0.1.md

@@ -1,15 +1,16 @@
 # Release notes v0.1
 
-## New features since last release
+Specific upgrades for the latest release can be found [here](https://github.com/SpeysideHEP/spey/releases/latest).
 
-* Exclusion limit calculator has been extended to include p-value computation
-  from chi-square.
+## New features since the last release
+
+* The exclusion limit calculator has been extended to include p-value computation from chi-square.
   ([#17](https://github.com/SpeysideHEP/spey/pull/17))
 
 * $\chi^2$ function has been extended to compute background + signal vs background only model.
   ([#17](https://github.com/SpeysideHEP/spey/pull/17))
 
-* Poisson based likelihood constructor without uncertainties has been added
+* A Poisson-based likelihood constructor without uncertainties has been added
   (Request by Veronica Sanz for EFT studies).
   ([#22](https://github.com/SpeysideHEP/spey/pull/22))
 
@@ -25,19 +26,37 @@
   before approximating through $q_{\mu,A}$.
   [#25](https://github.com/SpeysideHEP/spey/pull/25)
 
-* Update clarification on text based keyword arguments.
+* Update clarification on text-based keyword arguments.
   ([#30](https://github.com/SpeysideHEP/spey/pull/30))
 
+* Adding logging across the software and implementing tools to silence them.
+  ([#32](https://github.com/SpeysideHEP/spey/pull/32))
+
+* Spey will automatically look for updates during initiation.
+  ([#32](https://github.com/SpeysideHEP/spey/pull/32))
+
+* Utilities to retrieve BibTeX information for third-party plug-ins.
+  ([#32](https://github.com/SpeysideHEP/spey/pull/32))
+
+* Add math utilities for users to extract gradient and hessian of negative log-likelihood
+  ([#31](https://github.com/SpeysideHEP/spey/pull/31))
+
+* Improve gradient execution for `default_pdf`.
+  ([#31](https://github.com/SpeysideHEP/spey/pull/31))
+
+* Add more tests for code coverage.
+  ([#33](https://github.com/SpeysideHEP/spey/pull/33))
+
 ## Bug Fixes
 
-* In accordance to the latest updates ```UnCorrStatisticsCombiner``` has been updated with
-  chi-square computer. See issue [#19](https://github.com/SpeysideHEP/spey/issues/19).
+* In accordance with the latest updates, `UnCorrStatisticsCombiner` has been updated with
+  a chi-square computer. See issue [#19](https://github.com/SpeysideHEP/spey/issues/19).
   ([#20](https://github.com/SpeysideHEP/spey/pull/20))
 
 * Execution error fix during likelihood computation for models with single nuisance parameter.
   ([#22](https://github.com/SpeysideHEP/spey/pull/22))
 
-* Numeric problem rising from `==` which has been updated to `np.isclose`
+* The numeric problem rising from `==` which has been updated to `np.isclose`
   see issue [#23](https://github.com/SpeysideHEP/spey/issues/23).
   ([#25](https://github.com/SpeysideHEP/spey/pull/25))
 

docs/tutorials.rst

@@ -7,5 +7,6 @@ Kitchen Sink
    tutorials/intro_spey
    tutorials/functional_tuto
    tutorials/histogram
+   tutorials/gradients
    tuto_plugin
    Introduction to Spey (PyHEP 2023) <https://github.com/SpeysideHEP/PyHEP-2023>

docs/tutorials/gradients.md

@@ -0,0 +1,92 @@
+---
+myst:
+  html_meta:
+    "property=og:title": "Gradient of a Statistical Model"
+    "property=og:description": "Modules to compute gradient and Hessian of negative log-probabilities"
+    "property=og:image": "https://spey.readthedocs.io/en/main/_static/spey-logo.png"
+jupytext:
+  formats: ipynb,md:myst
+  text_representation:
+    extension: .md
+    format_name: myst
+    format_version: 0.12
+    jupytext_version: 1.8.2
+kernelspec:
+  display_name: Python 3
+  language: python
+  name: python3
+---
+
+# Gradient of a Statistical Model
+
+````{margin}
+```{note}
+In previous versions gradient and Hessian was limited to internal computations only.
+```
+````
+
+With version 0.1.6, Spey includes additional functionalities to extract gradient and Hessian information directly from the statistical model. The gradient and Hessian are defined as follows
+
+$$
+{\rm Gradient} = -\frac{d\log\mathcal{L}(\theta)}{d\theta}\quad , \quad {\rm Hessian} = -\frac{d^2\log\mathcal{L}(\theta)}{d\theta_i d\theta_j}\quad , \quad \mu ,\theta_i \in \theta \ .
+$$
+
+In order to access this information we will use `spey.math` module.
+
+```{code-cell} ipython3
+:tags: [hide-cell]
+import spey
+from spey.math import value_and_grad, hessian
+import numpy as np
+np.random.seed(14)
+```
+
+{py:func}`spey.math.value_and_grad` returns a function that computes negative log-likelihood and its gradient for a given statistical model and {py:func}`spey.math.hessian` returns a function that computes Hessian of negative log-likelihood.
+
+Let us examine this on ``"default_pdf.uncorrelated_background"``:
+
+```{code-cell} ipython3
+pdf_wrapper = spey.get_backend("default_pdf.uncorrelated_background")
+
+data = [36, 33]
+signal_yields = [12.0, 15.0]
+background_yields = [50.0, 48.0]
+background_unc = [12.0, 16.0]
+
+stat_model = pdf_wrapper(
+    signal_yields=signal_yields,
+    background_yields=background_yields,
+    data=data,
+    absolute_uncertainties=background_unc,
+)
+```
+
+Here we constructed a two-bin statistical model with observations $36,\ 33$, signal yields $12,\ 15$ and background yields $50\pm12,\ 48\pm16$. We can construct the function that will return negative log probability and its gradient as follows
+
+```{code-cell} ipython3
+neg_logprob = value_and_grad(stat_model)
+```
+
+Notice that this function constructs a negative log-probability for the observed statistical model using the default data that we provided earlier. This can be changed using ``expected`` and ``data`` keywords. Now we can choose nuisance parameters and execute the function:
+
+```{code-cell} ipython3
+nui = np.random.uniform(0,1,(3,))
+neg_logprob(nui)
+```
+
+```python
+(27.81902589793928, array([13.29067478,  6.17223275,  9.28814191]))
+```
+
+For this particular model, we have only two nuisance parameters, $\theta_i$, and signal strength, $\mu$, due to the structure of the statistical model. For Hessian, we can use the same formulation:
+
+```{code-cell} ipython3
+hess = hessian(stat_model)
+hess(nui)
+```
+
+```python
+array([[ 2.74153126,  1.21034187,  1.63326868],
+       [ 1.21034187,  2.21034187, -0.        ],
+       [ 1.63326868, -0.        ,  2.74215326]])
+```

setup.py

@@ -12,6 +12,7 @@
     "autograd==1.5",
     "semantic_version~=2.10",
     "tqdm>=4.64.0",
+    "requests>=2.31.0",
 ]
 
 backend_plugins = [