More detailed docs and renamed the transformation warning attribute

Author: han-ol

bayesflow/approximators/point_approximator.py

@@ -131,7 +131,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:
+                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/scoring_rule.py

@@ -17,6 +17,12 @@ class ScoringRule:
 
     To define a custom ``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.
     """
 
     def __init__(
@@ -29,7 +35,12 @@ def __init__(
         self.subnets_kwargs = subnets_kwargs or {}
         self.links = links or {}
 
-        self.not_transforming_like_vector = []
+        # 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}
 
@@ -60,12 +71,15 @@ def get_head_shapes_from_target_shape(self, target_shape: Shape) -> dict[str, Sh
 
     def get_subnet(self, key: str) -> keras.Layer:
         """For a specified key, request a subnet to be used for projecting the shared condition embedding
-        before reshaping to the heads output shape.
+        before further projection and reshaping to the heads output shape.
+
+        If no subnet was specified for the key (e.g. upon initialization),
+        return just an instance of keras.layers.Identity.
 
         Parameters
         ----------
         key : str
-            Name of head for which to request a link.
+            Name of head for which to request a subnet.
 
         Returns
         -------
@@ -80,6 +94,8 @@ def get_subnet(self, key: str) -> keras.Layer:
     def get_link(self, key: str) -> keras.Layer:
         """For a specified key, request a link from network output to estimation target.
 
+        If no link was specified for the key (e.g. upon initialization), return a linear activation.
+
         Parameters
         ----------
         key : str
@@ -98,7 +114,15 @@ def get_link(self, key: str) -> keras.Layer:
             return self.links[key]
 
     def get_head(self, key: str, output_shape: Shape) -> keras.Sequential:
-        """For a specified head key and shape, request corresponding head network.
+        """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.
+
+        This method initializes the components in reverse order to meet all requirements and returns them.
 
         Parameters
         ----------