[no ci] docs: formatting, mostly in transforms

Author: vpratz

bayesflow/adapters/transforms/as_set.py

@@ -4,8 +4,8 @@
 
 
 class AsSet(ElementwiseTransform):
-    """
-    The `.as_set(["x", "y"])` transform indicates that both `x` and `y` are treated as sets.
+    """The `.as_set(["x", "y"])` transform indicates that both `x` and `y` are treated as sets.
+
     That is, their values will be treated as *exchangable* such that they will imply
     the same inference regardless of the values' order.
     This is useful, for example, in a linear regression context where we can index
@@ -17,12 +17,9 @@ class AsSet(ElementwiseTransform):
     In the future, the transform will have more advanced behavior
     to better ensure the correct treatment of sets.
 
-    Useage:
-
-    adapter = (
-        bf.Adapter()
-        .as_set(["x", "y"])
-        )
+    Examples
+    --------
+    >>> adapter = bf.Adapter().as_set(["x", "y"])
     """
 
     def forward(self, data: np.ndarray, **kwargs) -> np.ndarray:

bayesflow/adapters/transforms/as_time_series.py

@@ -4,22 +4,18 @@
 
 
 class AsTimeSeries(ElementwiseTransform):
-    """
-    The `.as_time_series` transform can be used to indicate that
-    variables shall be treated as time series.
+    """The `.as_time_series` transform can be used to indicate that variables shall be treated as time series.
 
     Currently, all this transformation does is to ensure that the variable
     arrays are at least 3D. The 2rd dimension is treated as the
     time series dimension and the 3rd dimension as the data dimension.
     In the future, the transform will have more advanced behavior
     to better ensure the correct treatment of time series data.
 
-    Useage:
+    Examples
+    --------
 
-    adapter = (
-        bf.Adapter()
-        .as_time_series(["x", "y"])
-        )
+    >>> adapter = bf.Adapter().as_time_series(["x", "y"])
     """
 
     def forward(self, data: np.ndarray, **kwargs) -> np.ndarray:

bayesflow/adapters/transforms/broadcast.py

@@ -15,40 +15,50 @@ class Broadcast(Transform):
     """
     Broadcasts arrays or scalars to the shape of a given other array.
 
-    Parameters:
-
-    expand: Where should new dimensions be added to match the number of dimensions in `to`?
-    Can be "left", "right", or an integer or tuple containing the indices of the new dimensions.
-    The latter is needed if we want to include a dimension in the middle, which will be required
-    for more advanced cases. By default we expand left.
-
-    exclude: Which dimensions (of the dimensions after expansion) should retain their size,
-    rather than being broadcasted to the corresponding dimension size of `to`?
-    By default we exclude the last dimension (usually the data dimension) from broadcasting the size.
-
-    Examples:
-        shape (1, ) array:
-        >>> a = np.array((1,))
-        shape (2, 3) array:
-        >>> b = np.array([[1, 2, 3], [4, 5, 6]])
-        shape (2, 2, 3) array:
-        >>> c = np.array([[[1, 2, 3], [4, 5, 6]], [[4, 5, 6], [1, 2, 3]]])
-        >>> dat = dict(a=a, b=b, c=c)
-
-        >>> bc = bf.adapters.transforms.Broadcast("a", to="b")
-        >>> new_dat = bc.forward(dat)
-        >>> new_dat["a"].shape
-        (2, 1)
-
-        >>> bc = bf.adapters.transforms.Broadcast("a", to="b", exclude=None)
-        >>> new_dat = bc.forward(dat)
-        >>> new_dat["a"].shape
-        (2, 3)
-
-        >>> bc = bf.adapters.transforms.Broadcast("b", to="c", expand=1)
-        >>> new_dat = bc.forward(dat)
-        >>> new_dat["b"].shape
-        (2, 2, 3)
+    Parameters
+    ----------
+    keys: sequence of str,
+        Input a list of strings, where the strings are the names of data variables.
+    expand: str or int or tuple, optional
+        Where should new dimensions be added to match the number of dimensions in `to`?
+        Can be "left", "right", or an integer or tuple containing the indices of the new dimensions.
+        The latter is needed if we want to include a dimension in the middle, which will be required
+        for more advanced cases. By default we expand left.
+
+    exclude: int or tuple, optional
+        Which dimensions (of the dimensions after expansion) should retain their size,
+        rather than being broadcasted to the corresponding dimension size of `to`?
+        By default we exclude the last dimension (usually the data dimension) from broadcasting the size.
+
+    Examples
+    --------
+    shape (1, ) array:
+
+    >>> a = np.array((1,))
+
+    shape (2, 3) array:
+
+    >>> b = np.array([[1, 2, 3], [4, 5, 6]])
+
+    shape (2, 2, 3) array:
+
+    >>> c = np.array([[[1, 2, 3], [4, 5, 6]], [[4, 5, 6], [1, 2, 3]]])
+
+    >>> dat = dict(a=a, b=b, c=c)
+    >>> bc = bf.adapters.transforms.Broadcast("a", to="b")
+    >>> new_dat = bc.forward(dat)
+    >>> new_dat["a"].shape
+    (2, 1)
+
+    >>> bc = bf.adapters.transforms.Broadcast("a", to="b", exclude=None)
+    >>> new_dat = bc.forward(dat)
+    >>> new_dat["a"].shape
+    (2, 3)
+
+    >>> bc = bf.adapters.transforms.Broadcast("b", to="c", expand=1)
+    >>> new_dat = bc.forward(dat)
+    >>> new_dat["b"].shape
+    (2, 2, 3)
 
     It is recommended to precede this transform with a :class:`bayesflow.adapters.transforms.ToArray` transform.
     """

bayesflow/adapters/transforms/concatenate.py

@@ -14,20 +14,25 @@
 class Concatenate(Transform):
     """Concatenate multiple arrays into a new key. Used to specify how data variables should be treated by the network.
 
-    Parameters:
-        keys: Input a list of strings, where the strings are the names of data variables.
-        into: A string telling the network how to use the variables named in keys.
-        axis: integer specifing along which axis to concatonate the keys. The last axis is used by default.
-
-    Example:
+    Parameters
+    ----------
+    keys: sequence of str,
+        Input a list of strings, where the strings are the names of data variables.
+    into: str
+        A string telling the network how to use the variables named in keys.
+    axis: int, optional
+        integer specifing along which axis to concatonate the keys. The last axis is used by default.
+
+    Examples
+    --------
     Suppose you have a simulator that generates variables "beta" and "sigma" from priors and then observation
     variables "x" and "y". We can then use concatonate in the following way
 
-    adapter = (
+    >>> adapter = (
         bf.Adapter()
             .concatenate(["beta", "sigma"], into="inference_variables")
             .concatenate(["x", "y"], into="summary_variables")
-     )
+    )
     """
 
     def __init__(self, keys: Sequence[str], *, into: str, axis: int = -1, _indices: list | None = None):

bayesflow/adapters/transforms/constrain.py

@@ -18,43 +18,48 @@ class Constrain(ElementwiseTransform):
     """
     Constrains neural network predictions of a data variable to specified bounds.
 
-    Parameters:
+    Parameters
+    ----------
+    * : str
         String containing the name of the data variable to be transformed e.g. "sigma". See examples below.
 
-    Named Parameters:
-        lower: Lower bound for named data variable.
-        upper: Upper bound for named data variable.
-        method: Method by which to shrink the network predictions space to specified bounds. Choose from
-            - Double bounded methods: sigmoid, expit, (default = sigmoid)
-            - Lower bound only methods: softplus, exp, (default = softplus)
-            - Upper bound only methods: softplus, exp, (default = softplus)
-        inclusive: Indicates which bounds are inclusive (or exclusive).
-            - "both" (default): Both lower and upper bounds are inclusive.
-            - "lower": Lower bound is inclusive, upper bound is exclusive.
-            - "upper": Lower bound is exclusive, upper bound is inclusive.
-            - "none": Both lower and upper bounds are exclusive.
-        epsilon: Small value to ensure inclusive bounds are not violated.
-            Current default is 1e-15 as this ensures finite outcomes
-            with the default transformations applied to data exactly at the boundaries.
-
-
-    Examples:
-        1) Let sigma be the standard deviation of a normal distribution,
-        then sigma should always be greater than zero.
-
-        Usage:
-        adapter = (
-            bf.Adapter()
-            .constrain("sigma", lower=0)
-            )
-
-        2 ) Suppose p is the parameter for a binomial distribution where p must be in
-        [0,1] then we would constrain the neural network to estimate p in the following way.
-
-        Usage:
-        >>> import bayesflow as bf
-        >>> adapter = bf.Adapter()
-        >>> adapter.constrain("p", lower=0, upper=1, method="sigmoid", inclusive="both")
+    lower: int or float or np.darray, optional
+        Lower bound for named data variable.
+    upper: int or float or np.darray, optional
+        Upper bound for named data variable.
+    method: str, optional
+        Method by which to shrink the network predictions space to specified bounds. Choose from
+        - Double bounded methods: sigmoid, expit, (default = sigmoid)
+        - Lower bound only methods: softplus, exp, (default = softplus)
+        - Upper bound only methods: softplus, exp, (default = softplus)
+    inclusive: {'both', 'lower', 'upper', 'none'}, optional
+        Indicates which bounds are inclusive (or exclusive).
+        - "both" (default): Both lower and upper bounds are inclusive.
+        - "lower": Lower bound is inclusive, upper bound is exclusive.
+        - "upper": Lower bound is exclusive, upper bound is inclusive.
+        - "none": Both lower and upper bounds are exclusive.
+    epsilon: float, optional
+        Small value to ensure inclusive bounds are not violated.
+        Current default is 1e-15 as this ensures finite outcomes
+        with the default transformations applied to data exactly at the boundaries.
+
+    Examples
+    --------
+
+    1) Let sigma be the standard deviation of a normal distribution,
+    then sigma should always be greater than zero.
+
+    >>> adapter = (
+        bf.Adapter()
+        .constrain("sigma", lower=0)
+    )
+
+    2) Suppose p is the parameter for a binomial distribution where p must be in
+    [0,1] then we would constrain the neural network to estimate p in the following way.
+
+    >>> import bayesflow as bf
+    >>> adapter = bf.Adapter()
+    >>> adapter.constrain("p", lower=0, upper=1, method="sigmoid", inclusive="both")
     """
 
     def __init__(

bayesflow/adapters/transforms/convert_dtype.py

@@ -12,6 +12,13 @@
 class ConvertDType(ElementwiseTransform):
     """
     Default transform used to convert all floats from float64 to float32 to be in line with keras framework.
+
+    Parameters
+    ----------
+    from_dtype : str
+        Original dtype
+    to_dtype : str
+        Target dtype
     """
 
     def __init__(self, from_dtype: str, to_dtype: str):

bayesflow/adapters/transforms/drop.py

@@ -14,10 +14,13 @@ class Drop(Transform):
     """
     Transform to drop variables from further calculation.
 
-    Parameters:
-        keys: list of strings, containing names of data variables that should be dropped
+    Parameters
+    ----------
+    keys: sequence of str
+        Names of data variables that should be dropped
 
-    Example:
+    Examples
+    --------
 
     >>> import bayesflow as bf
     >>> a = [1, 2, 3, 4]

bayesflow/adapters/transforms/expand_dims.py

@@ -12,27 +12,32 @@
 class ExpandDims(ElementwiseTransform):
     """
     Expand the shape of an array.
-    Examples:
-        shape (3,) array:
-        >>> a = np.array([1, 2, 3])
-        shape (2, 3) array:
-        >>> b = np.array([[1, 2, 3], [4, 5, 6]])
-        >>> dat = dict(a=a, b=b)
-
-        >>> ed = bf.adapters.transforms.ExpandDims("a", axis=0)
-        >>> new_dat = ed.forward(dat)
-        >>> new_dat["a"].shape
-        (1, 3)
-
-        >>> ed = bf.adapters.transforms.ExpandDims("a", axis=1)
-        >>> new_dat = ed.forward(dat)
-        >>> new_dat["a"].shape
-        (3, 1)
-
-        >>> ed = bf.adapters.transforms.ExpandDims("b", axis=1)
-        >>> new_dat = ed.forward(dat)
-        >>> new_dat["b"].shape
-        (2, 1, 3)
+
+    Examples
+    --------
+    shape (3,) array:
+
+    >>> a = np.array([1, 2, 3])
+
+    shape (2, 3) array:
+
+    >>> b = np.array([[1, 2, 3], [4, 5, 6]])
+    >>> dat = dict(a=a, b=b)
+
+    >>> ed = bf.adapters.transforms.ExpandDims("a", axis=0)
+    >>> new_dat = ed.forward(dat)
+    >>> new_dat["a"].shape
+    (1, 3)
+
+    >>> ed = bf.adapters.transforms.ExpandDims("a", axis=1)
+    >>> new_dat = ed.forward(dat)
+    >>> new_dat["a"].shape
+    (3, 1)
+
+    >>> ed = bf.adapters.transforms.ExpandDims("b", axis=1)
+    >>> new_dat = ed.forward(dat)
+    >>> new_dat["b"].shape
+    (2, 1, 3)
 
     It is recommended to precede this transform with a :class:`bayesflow.adapters.transforms.ToArray` transform.
     """

bayesflow/adapters/transforms/filter_transform.py

@@ -22,8 +22,9 @@ def __call__(self, key: str, value: np.ndarray, inverse: bool) -> bool:
 @serializable(package="bayesflow.adapters")
 class FilterTransform(Transform):
     """
-    Implements a transform that applies a different transform on a subset of the data. Used by other transforms and
-    base adapter class.
+    Implements a transform that applies a different transform on a subset of the data.
+
+    Used by other transforms and base adapter class.
     """
 
     def __init__(