Transformation warning using a class variable; docstring links

Author: han-ol

bayesflow/approximators/point_approximator.py

@@ -14,8 +14,9 @@ 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 `PointInferenceNetwork`.
-    Conditions can be compressed by an optional `SummaryNetwork` or used directly as input to the inference network.
+    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.
     """
 
     def estimate(
@@ -89,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 `PointApproximator`.
+            Currently not supported for :class:`PointApproximator` .
         **kwargs
             Additional keyword arguments passed to underlying processing functions.
 
@@ -135,15 +136,14 @@ def log_prob(
         Returns
         -------
         log_prob : np.ndarray or dict[str, np.ndarray]
-            Log-probabilities of the distribution `p(inference_variables | inference_conditions, h(summary_conditions))`
-            for all parametric scoring rules.
+            Log-probabilities of the distribution
+            `p(inference_variables | inference_conditions, h(summary_conditions))` for all parametric scoring rules.
 
             If only one parametric score is available, output is an array of log-probabilities.
 
             Output is a dictionary if multiple parametric scores are available.
             Then, each key is the name of a score and values are corresponding log-probabilities.
 
-
             Log-probabilities have shape (num_datasets,).
         """
         log_prob = super().log_prob(data=data, **kwargs)
@@ -167,7 +167,7 @@ def _apply_inverse_adapter_to_estimates(
         for score_key, score_val in estimates.items():
             processed[score_key] = {}
             for head_key, estimate in score_val.items():
-                if head_key in self.inference_network.scores[score_key].not_transforming_like_vector_warning:
+                if head_key in self.inference_network.scores[score_key].NOT_TRANSFORMING_LIKE_VECTOR_WARNING:
                     logging.warning(
                         f"Estimate '{score_key}.{head_key}' is marked to not transform like a vector. "
                         f"It was treated like a vector by the adapter. Handle '{head_key}' estimates with care."

bayesflow/scores/multivariate_normal_score.py

@@ -16,15 +16,22 @@ class MultivariateNormalScore(ParametricDistributionScore):
     Scores a predicted mean and covariance matrix with the log-score of the probability of the materialized value.
     """
 
+    NOT_TRANSFORMING_LIKE_VECTOR_WARNING = ("covariance",)
+    """
+    Marks head for covariance matrix as an exception for adapter transformations.
+
+    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`.
+    """
+
     def __init__(self, dim: int = None, links: dict = None, **kwargs):
         super().__init__(links=links, **kwargs)
 
         self.dim = dim
         self.links = links or {"covariance": PositiveDefinite()}
 
-        # mark head for covariance matrix as an exception for adapter transformations
-        self.not_transforming_like_vector = ["covariance"]
-
         self.config = {"dim": dim}
 
     def get_config(self):

bayesflow/scores/scoring_rule.py

@@ -15,14 +15,27 @@ class ScoringRule:
     when sampling from the true distribution. By minimizing an expected score, estimates with
     different properties can be obtained.
 
-    To define a custom ``ScoringRule``, inherit from this class and overwrite the score method.
+    To define a custom :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.
 
-    `ScoringRule`s can score estimates consisting of multiple parts. See `MultivariateNormalScore` for an example
-    of a `ParametricDistributionScore`. The score evaluates an estimated mean and covariance simultaneously.
+    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
+    and covariance simultaneously.
+    """
+
+    NOT_TRANSFORMING_LIKE_VECTOR_WARNING = tuple()
+    """
+    This variable contains names of prediction heads that should lead to a warning when the adapter is applied
+    in inverse direction to them.
+
+    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
+    with a type of estimate whenever the adapter is applied to them in inverse direction.
     """
 
     def __init__(
@@ -35,13 +48,6 @@ def __init__(
         self.subnets_kwargs = subnets_kwargs or {}
         self.links = links or {}
 
-        # 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. When subclassing `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.
-        self.not_transforming_like_vector_warning = []
-
         self.config = {"subnets_kwargs": self.subnets_kwargs}
 
     def get_config(self):
@@ -117,10 +123,12 @@ def get_head(self, key: str, output_shape: Shape) -> keras.Sequential:
         """For a specified head key and output shape, request corresponding head network.
 
         A head network has the following components that are called sequentially:
+
         1. subnet: A keras.Layer.
         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.
 
         This method initializes the components in reverse order to meet all requirements and returns them.
 
@@ -130,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
-            `scoring_rule.get_head_shapes_from_target_shape()`.
+            :func:`get_head_shapes_from_target_shape()`.
 
         Returns
         -------
@@ -173,11 +181,11 @@ def score(self, estimates: dict[str, Tensor], targets: Tensor, weights: Tensor)
 
         Examples
         --------
-        The following shows how to score estimates with a ``MeanScore``. All ``ScoringRule`` s follow this pattern,
-        only differing in the structure of the estimates dictionary.
+        The following shows how to score estimates with a :class:`MeanScore`. All :class:`ScoringRule` s
+        follow this pattern, only differing in the structure of the estimates dictionary.
 
         >>> import keras
-        ... from bayesflow.scores import MeanScore
+        >>> from bayesflow.scores import MeanScore
         >>>
         >>> # batch of samples from a normal distribution
         >>> samples = keras.random.normal(shape=(100,))