From c096838d01fcb0cdd61f003f082a2c97db409f28 Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Tue, 9 Jul 2024 17:29:44 +0200
Subject: [PATCH] doc: bring docstrings text from #201
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Jon Haitz Legarreta Gorroño <jon.haitz.legarreta@gmail.com>
---
 src/eddymotion/model/dipy.py | 64 +++++++++++++++++++++++++++++++++++-
 1 file changed, 63 insertions(+), 1 deletion(-)

diff --git a/src/eddymotion/model/dipy.py b/src/eddymotion/model/dipy.py
index a7cbb3ef..56d8d032 100644
--- a/src/eddymotion/model/dipy.py
+++ b/src/eddymotion/model/dipy.py
@@ -20,7 +20,69 @@
 #
 #     https://www.nipreps.org/community/licensing/
 #
-"""DIPY-like models (a sandbox to trial them out before upstreaming to DIPY)."""
+r"""
+DIPY-like models (a sandbox to trial them out before upstreaming to DIPY).
+
+Gaussian Process Model: Pairwise orientation angles
+---------------------------------------------------
+Squared Exponential covariance kernel
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Kernel based on a squared exponential function for Gaussian processes on
+multi-shell DWI data following to eqs. 14 and 16 in [Andersson15]_.
+For a 2-shell case, the $$\mathbf{K}$$ kernel can be written as:
+
+.. math::
+    \begin{equation}
+    \mathbf{K} = \left[
+    \begin{matrix}
+        \lambda C_{\theta}(\theta (\mathbf{G}_{1}); a) + \sigma_{1}^{2} \mathbf{I} &
+        \lambda C_{\theta}(\theta (\mathbf{G}_{2}, \mathbf{G}_{1}); a) C_{b}(b_{2}, b_{1}; \ell) \\
+        \lambda C_{\theta}(\theta (\mathbf{G}_{1}, \mathbf{G}_{2}); a) C_{b}(b_{1}, b_{2}; \ell) &
+        \lambda C_{\theta}(\theta (\mathbf{G}_{2}); a) + \sigma_{2}^{2} \mathbf{I} \\
+    \end{matrix}
+    \right]
+    \end{equation}
+
+**Squared exponential shell-wise covariance kernel**:
+Compute the squared exponential smooth function describing how the
+covariance changes along the b direction.
+It uses the log of the b-values as the measure of distance along the
+b-direction according to eq. 15 in [Andersson15]_.
+
+.. math::
+    C_{b}(b, b'; \ell) = \exp\left( - \frac{(\log b - \log b')^2}{2 \ell^2} \right).
+
+**Squared exponential covariance kernel**:
+Compute the squared exponential covariance matrix following to eq. 14 in [Andersson15]_.
+
+.. math::
+    k(\textbf{x}, \textbf{x'}) = C_{\theta}(\mathbf{g}, \mathbf{g'}; a) C_{b}(\abs{b - b'}; \ell)
+
+where :math:`C_{\theta}` is given by:
+
+.. math::
+    \begin{equation}
+    C(\theta) =
+    \begin{cases}
+    1 - \frac{3 \theta}{2 a} + \frac{\theta^3}{2 a^3} & \textnormal{if} \; \theta \leq a \\
+    0 & \textnormal{if} \; \theta > a
+    \end{cases}
+    \end{equation}
+
+:math:`\theta` being computed as:
+
+.. math::
+    \theta(\mathbf{g}, \mathbf{g'}) = \arccos(\abs{\langle \mathbf{g}, \mathbf{g'} \rangle})
+and :math:`C_{b}` is given by:
+
+.. math::
+    C_{b}(b, b'; \ell) = \exp\left( - \frac{(\log b - \log b')^2}{2 \ell^2} \right)
+
+:math:`b` and :math:`b'` being the b-values, and :math:`\mathbf{g}` and
+:math:`\mathbf{g'}` the unit diffusion-encoding gradient unit vectors of the
+shells; and :math:`{a, \ell}` some hyperparameters.
+
+"""
 
 from __future__ import annotations