From c559a38a0b4435620dbc0211c868c573525afd88 Mon Sep 17 00:00:00 2001
From: Alexander Fabisch <afabisch@googlemail.com>
Date: Fri, 3 Jan 2025 19:28:11 +0100
Subject: [PATCH] Make docstrings more consistent

---
 pytransform3d/uncertainty.py | 47 ++++++++++++++++--------------------
 1 file changed, 21 insertions(+), 26 deletions(-)

diff --git a/pytransform3d/uncertainty.py b/pytransform3d/uncertainty.py
index 68cd5dd43..448879c93 100644
--- a/pytransform3d/uncertainty.py
+++ b/pytransform3d/uncertainty.py
@@ -19,8 +19,9 @@
 def estimate_gaussian_rotation_matrix_from_samples(samples):
     """Estimate Gaussian distribution over rotations from samples.
 
-    Uses iterative approximation of mean described by Eade [1]_ and computes
-    covariance in exponential coordinate space (using an unbiased estimator).
+    Computes the Fréchet mean of the samples and the covariance in tangent
+    space (exponential coordinates of rotation / rotation vectors) using an
+    unbiased estimator as outlines by Eade [1]_.
 
     Parameters
     ----------
@@ -30,10 +31,15 @@ def estimate_gaussian_rotation_matrix_from_samples(samples):
     Returns
     -------
     mean : array, shape (3, 3)
-        Mean as rotation matrix.
+        Mean of the Gaussian distribution as rotation matrix.
 
     cov : array, shape (3, 3)
-        Covariance of distribution in exponential coordinate space.
+        Covariance of the Gaussian distribution in exponential coordinates.
+
+    See Also
+    --------
+    frechet_mean
+        Algorithm used to compute the mean of the Gaussian.
 
     References
     ----------
@@ -60,25 +66,11 @@ def compact_axis_angles_from_matrices(Rs):
 
 
 def estimate_gaussian_transform_from_samples(samples):
-    r"""Estimate Gaussian distribution over transformations from samples.
-
-    Uses iterative computation of mean described by Eade [1]_ and computes
-    covariance in exponential coordinate space (using an unbiased estimator).
-    The derivation of the procedure is presented by Pennec [2]_.
-
-    1. For a set of transformations :math:`\{T_1, \ldots, T_N\}`, we initialize
-       the estimated mean :math:`\overline{T}_0 \leftarrow T_1`.
-    2. For a fixed number of steps, in each iteration :math:`k` we improve the
-       estimation of the mean by
-
-       a. Computing the distance of each sample to the current estimate of the
-          mean in exponential coordinates
-          :math:`V_{i,k} \leftarrow T_i \cdot \overline{T}_k^{-1}`.
-       b. Updating the estimate of the mean
-          :math:`\overline{T}_{k+1} \leftarrow Exp(\frac{1}{N}\sum_i V_{i,k}) \cdot \overline{T}_k`.
+    """Estimate Gaussian distribution over transformations from samples.
 
-    3. Estimate the covariance in the space of exponential coordinates with
-       :math:`\Sigma \leftarrow \frac{1}{N - 1} \sum_i \left[ V_{i,k} \cdot V_{i,k}^T \right]`
+    Computes the Fréchet mean of the samples and the covariance in tangent
+    space (exponential coordinates of transformation) using an unbiased
+    estimator as outlines by Eade [1]_.
 
     Parameters
     ----------
@@ -93,14 +85,15 @@ def estimate_gaussian_transform_from_samples(samples):
     cov : array, shape (6, 6)
         Covariance of distribution in exponential coordinate space.
 
+    See Also
+    --------
+    frechet_mean
+        Algorithm used to compute the mean of the Gaussian.
+
     References
     ----------
     .. [1] Eade, E. (2017). Lie Groups for 2D and 3D Transformations.
        https://ethaneade.com/lie.pdf
-
-    .. [2] Pennec, X. (2006). Intrinsic Statistics on Riemannian Manifolds:
-       Basic Tools for Geometric Measurements. J Math Imaging Vis 25, 127-154.
-       https://doi.org/10.1007/s10851-006-6228-4
     """
     mean, mean_diffs = frechet_mean(
         samples=samples,
@@ -172,6 +165,8 @@ def frechet_mean(
 
     mean_diffs : array, shape (n_samples, n_tangent_space_components)
         Differences between the mean and the samples in the tangent space.
+        These can be used to compute the covariance. They are returned to
+        avoid recomputing them.
 
     See Also
     --------