Unified docstrings formatting for sphinx

Author: han-ol

bayesflow/approximators/point_approximator.py

@@ -15,8 +15,8 @@ class PointApproximator(ContinuousApproximator):
     A workflow for fast amortized point estimation of a conditional distribution.
 
     The distribution is approximated by point estimators, parameterized by a feed-forward
-    :class:`bayesflow.networks.PointInferenceNetwork`. Conditions can be compressed by an optional summary network
-    (inheriting from :class:`bayesflow.networks.SummaryNetwork`) or used directly as input to the inference network.
+    :py:class:`~bayesflow.networks.PointInferenceNetwork`. Conditions can be compressed by an optional summary network
+    (inheriting from :py:class:`~bayesflow.networks.SummaryNetwork`) or used directly as input to the inference network.
     """
 
     def estimate(
@@ -90,7 +90,7 @@ def sample(
             for the sampling process.
         split : bool, optional
             If True, the sampled arrays are split along the last axis, by default False.
-            Currently not supported for :class:`PointApproximator` .
+            Currently not supported for :py:class:`PointApproximator` .
         **kwargs
             Additional keyword arguments passed to underlying processing functions.
 

bayesflow/scores/multivariate_normal_score.py

@@ -23,7 +23,7 @@ class MultivariateNormalScore(ParametricDistributionScore):
     This variable contains names of prediction heads that should lead to a warning when the adapter is applied
     in inverse direction to them.
 
-    For more information see :class:`ScoringRule`.
+    For more information see :py:class:`ScoringRule`.
     """
 
     def __init__(self, dim: int = None, links: dict = None, **kwargs):

bayesflow/scores/normed_difference_score.py

@@ -15,7 +15,10 @@ class NormedDifferenceScore(ScoringRule):
 
     def __init__(self, k: int, **kwargs):
         super().__init__(**kwargs)
+
+        #: Exponent to absolute difference
         self.k = k
+
         self.config = {"k": k}
 
     def get_head_shapes_from_target_shape(self, target_shape: Shape):
@@ -24,13 +27,15 @@ def get_head_shapes_from_target_shape(self, target_shape: Shape):
         return dict(value=target_shape[1:])
 
     def score(self, estimates: dict[str, Tensor], targets: Tensor, weights: Tensor = None) -> Tensor:
-        """
-        Computes the scoring function based on the absolute difference between estimates and targets.
+        r"""
+        Computes the scoring function based on the absolute difference between **estimates** and **targets**.
+
+        :math:`S(\hat \theta, \theta; k) = | \hat \theta - \theta |^k`
 
-        This function extracts the "value" tensor from the `estimates` dictionary and computes
+        This function extracts the Tensor named ``"value"`` from the **estimates** dictionary and computes
         the element-wise absolute difference between the estimates and the true targets. The
-        difference is then exponentiated by `self.k`. The final score is computed using the
-        `aggregate` method, which optionally applies weighting.
+        difference is then exponentiated by :py:attr:`k`. The final score is computed using the
+        :py:func:`aggregate()` method, which optionally applies weighting.
 
         Parameters
         ----------

bayesflow/scores/parametric_distribution_score.py

@@ -23,31 +23,10 @@ def sample(self, *args, **kwargs):
         raise NotImplementedError
 
     def score(self, estimates: dict[str, Tensor], targets: Tensor, weights: Tensor = None) -> Tensor:
-        """
-        Computes the quantile-based scoring function.
-
-        This function extracts the "value" tensor from the `estimates` dictionary and computes
-        the pointwise difference between the estimates and the targets, expanding the target
-        dimensions as necessary.
-
-        The scoring function applies a quantile-based transformation to the difference, computing the
-        mean score across a specified axis. The final score is then aggregated, optionally applying weights.
-
-        Parameters
-        ----------
-        estimates : dict[str, Tensor]
-            A dictionary containing tensors of estimated values. The "value" key must be present.
-        targets : Tensor
-            A tensor of true target values. The shape is adjusted to align with estimates.
-        weights : Tensor, optional
-            A tensor of weights corresponding to each estimate-target pair. If provided, it is used
-            to compute a weighted aggregate score.
-
-        Returns
-        -------
-        Tensor
-            The aggregated quantile-based score, computed using the absolute pointwise difference
-            transformed by the quantile adjustment, optionally weighted.
+        r"""
+        Computes the log-score for a predicted parametric probability distribution given realized **targets**.
+
+        :math:`S(\hat p_\phi, \theta; k) = \log(\hat p_\phi(\theta))`
         """
         scores = -self.log_prob(x=targets, **estimates)
         score = self.aggregate(scores, weights)

bayesflow/scores/scoring_rule.py

@@ -15,14 +15,14 @@ class ScoringRule:
     when sampling from the true distribution. By minimizing an expected score, estimates with
     different properties can be obtained.
 
-    To define a custom :class:`ScoringRule`, inherit from this class and overwrite the score method.
+    To define a custom :py:class:`ScoringRule`, inherit from this class and overwrite the score method.
     For proper serialization, any new constructor arguments must be taken care of in a `get_config` method.
 
     Estimates are typically parameterized by projection heads consisting of a neural network component
     and a link to project into the correct output space.
 
-    A :class:`ScoringRule` can score estimates consisting of multiple parts. See :class:`MultivariateNormalScore`
-    for an example of a :class:`ParametricDistributionScore`. That score evaluates an estimated mean
+    A :py:class:`ScoringRule` can score estimates consisting of multiple parts. See :py:class:`MultivariateNormalScore`
+    for an example of a :py:class:`ParametricDistributionScore`. That score evaluates an estimated mean
     and covariance simultaneously.
     """
 
@@ -34,7 +34,7 @@ class ScoringRule:
     Prediction heads can output estimates in spaces other than the target distribution space.
     To such estimates the adapter cannot be straightforwardly applied in inverse direction,
     because the adapter is built to map vectors from the inference variable space. When subclassing
-    :class:`ScoringRule`, add the names of such heads to the following list to warn users about difficulties
+    :py:class:`ScoringRule`, add the names of such heads to the following list to warn users about difficulties
     with a type of estimate whenever the adapter is applied to them in inverse direction.
     """
 
@@ -128,7 +128,7 @@ def get_head(self, key: str, output_shape: Shape) -> keras.Sequential:
         2. dense: A trainable linear projection with as many units as are required by the next component.
         3. reshape: Changes shape of output of projection to match requirements of next component.
         4. link: Transforms unconstrained values into a constrained space for the final estimator.
-           See :mod:`bayesflow.links` for examples.
+           See :py:mod:`~bayesflow.links` for examples.
 
         This method initializes the components in reverse order to meet all requirements and returns them.
 
@@ -138,7 +138,7 @@ def get_head(self, key: str, output_shape: Shape) -> keras.Sequential:
             Name of head for which to request a link.
         output_shape: Shape
             The necessary shape of estimated values for the given key as returned by
-            :func:`get_head_shapes_from_target_shape()`.
+            :py:func:`get_head_shapes_from_target_shape()`.
 
         Returns
         -------
@@ -181,7 +181,7 @@ def score(self, estimates: dict[str, Tensor], targets: Tensor, weights: Tensor)
 
         Examples
         --------
-        The following shows how to score estimates with a :class:`MeanScore`. All :class:`ScoringRule` s
+        The following shows how to score estimates with a :py:class:`MeanScore`. All :py:class:`ScoringRule`\ s
         follow this pattern, only differing in the structure of the estimates dictionary.
 
         >>> import keras
@@ -207,7 +207,7 @@ def score(self, estimates: dict[str, Tensor], targets: Tensor, weights: Tensor)
 
     def aggregate(self, scores: Tensor, weights: Tensor = None) -> Tensor:
         """
-        Computes the mean of scores, optionally applying weights.
+        Computes the mean of **scores**, optionally applying **weights**.
 
         This function computes the mean value of the given scores. When weights are provided,
         it first multiplies the scores by the weights and then computes the mean of the result.
@@ -224,8 +224,8 @@ def aggregate(self, scores: Tensor, weights: Tensor = None) -> Tensor:
         Returns
         -------
         Tensor
-            The aggregated score computed as a weighted mean if `weights` is provided,
-            or as the simple mean of `scores` otherwise.
+            The aggregated score computed as a weighted mean if **weights** is provided,
+            or as the simple mean of **scores** otherwise.
         """
 
         if weights is not None: