Merge branch 'dev' into point-estimation

Author: han-ol

.github/workflows/multiversion-docs.yaml

@@ -3,12 +3,13 @@
 name: multiversion-docs
 
 on:
+  pull_request:
+    branches:
+      - dev
   workflow_dispatch:
-# execute this workflow automatically when we push to master or dev
-#   push:
-#     branches:
-#       - master
-#       - dev
+  push:
+    branches:
+      - dev
 
 jobs:
 
@@ -51,6 +52,7 @@ jobs:
       - name: Commit changes to docs
         run: |
           cd ./gh-pages-dev
+          git rm --quiet -rf .
           cp -R ../dev/docs/* ./
           git config --local user.email ""
           git config --local user.name "github-actions"

README.md

@@ -94,9 +94,9 @@ conda env create --file environment.yaml --name bayesflow
 Check out some of our walk-through notebooks below. We are actively working on porting all notebooks to the new interface so more will be available soon!
 
 1. [Linear regression starter example](examples/Linear_Regression_Starter.ipynb)
-2. [Two moons starter example](examples/Two_Moons_Starter.ipynb)
-3. [SIR model with custom summary network](examples/SIR_Posterior_Estimation.ipynb)
-4. [SBML model using an external simulator](examples/From_ABC_to_BayesFlow.ipynb)
+2. [From ABC to BayesFlow](examples/From_ABC_to_BayesFlow.ipynb)
+3. [Two moons starter example](examples/Two_Moons_Starter.ipynb)
+4. [SIR model with custom summary network](examples/SIR_Posterior_Estimation.ipynb)
 5. [Hyperparameter optimization](examples/Hyperparameter_Optimization.ipynb)
 6. [Bayesian experimental design](examples/Bayesian_Experimental_Design.ipynb)
 7. [Simple model comparison example (One-Sample T-Test)](examples/One_Sample_TTest.ipynb)

bayesflow/adapters/__init__.py

@@ -1,2 +1,6 @@
 from . import transforms
 from .adapter import Adapter
+
+from ..utils._docs import _add_imports_to_all
+
+_add_imports_to_all(include_modules=["transforms"])

bayesflow/adapters/adapter.py

@@ -233,12 +233,17 @@ def constrain(
         lower: int | float | np.ndarray = None,
         upper: int | float | np.ndarray = None,
         method: str = "default",
+        inclusive: str = "both",
+        epsilon: float = 1e-15,
     ):
         if isinstance(keys, str):
             keys = [keys]
 
         transform = MapTransform(
-            transform_map={key: Constrain(lower=lower, upper=upper, method=method) for key in keys}
+            transform_map={
+                key: Constrain(lower=lower, upper=upper, method=method, inclusive=inclusive, epsilon=epsilon)
+                for key in keys
+            }
         )
         self.transforms.append(transform)
         return self

bayesflow/adapters/transforms/__init__.py

@@ -16,3 +16,7 @@
 from .standardize import Standardize
 from .to_array import ToArray
 from .transform import Transform
+
+from ...utils._docs import _add_imports_to_all
+
+_add_imports_to_all(include_modules=["transforms"])

bayesflow/adapters/transforms/constrain.py

@@ -16,7 +16,7 @@
 @serializable(package="bayesflow.adapters")
 class Constrain(ElementwiseTransform):
     """
-    Constrains neural network predictions of a data variable to specificied bounds.
+    Constrains neural network predictions of a data variable to specified bounds.
 
     Parameters:
         String containing the name of the data variable to be transformed e.g. "sigma". See examples below.
@@ -28,14 +28,21 @@ class Constrain(ElementwiseTransform):
             - 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.
 
-        Useage:
+        Usage:
         adapter = (
             bf.Adapter()
             .constrain("sigma", lower=0)
@@ -45,14 +52,19 @@ class Constrain(ElementwiseTransform):
         [0,1] then we would constrain the neural network to estimate p in the following way.
 
         Usage:
-        adapter = (
-            bf.Adapter()
-            .constrain("p", lower=0, upper=1, method = "sigmoid")
-            )
+        >>> import bayesflow as bf
+        >>> adapter = bf.Adapter()
+        >>> adapter.constrain("p", lower=0, upper=1, method="sigmoid", inclusive="both")
     """
 
     def __init__(
-        self, *, lower: int | float | np.ndarray = None, upper: int | float | np.ndarray = None, method: str = "default"
+        self,
+        *,
+        lower: int | float | np.ndarray = None,
+        upper: int | float | np.ndarray = None,
+        method: str = "default",
+        inclusive: str = "both",
+        epsilon: float = 1e-15,
     ):
         super().__init__()
 
@@ -121,12 +133,31 @@ def unconstrain(x):
 
         self.lower = lower
         self.upper = upper
-
         self.method = method
+        self.inclusive = inclusive
+        self.epsilon = epsilon
 
         self.constrain = constrain
         self.unconstrain = unconstrain
 
+        # do this last to avoid serialization issues
+        match inclusive:
+            case "lower":
+                if lower is not None:
+                    lower = lower - epsilon
+            case "upper":
+                if upper is not None:
+                    upper = upper + epsilon
+            case True | "both":
+                if lower is not None:
+                    lower = lower - epsilon
+                if upper is not None:
+                    upper = upper + epsilon
+            case False | None | "none":
+                pass
+            case other:
+                raise ValueError(f"Unsupported value for 'inclusive': {other!r}.")
+
     @classmethod
     def from_config(cls, config: dict, custom_objects=None) -> "Constrain":
         return cls(**config)
@@ -136,6 +167,8 @@ def get_config(self) -> dict:
             "lower": self.lower,
             "upper": self.upper,
             "method": self.method,
+            "inclusive": self.inclusive,
+            "epsilon": self.epsilon,
         }
 
     def forward(self, data: np.ndarray, **kwargs) -> np.ndarray:

bayesflow/approximators/__init__.py

@@ -2,3 +2,7 @@
 from .continuous_approximator import ContinuousApproximator
 from .point_approximator import PointApproximator
 from .model_comparison_approximator import ModelComparisonApproximator
+
+from ..utils._docs import _add_imports_to_all
+
+_add_imports_to_all(include_modules=[])

bayesflow/approximators/continuous_approximator.py

@@ -184,6 +184,8 @@ def sample(
         **kwargs,
     ) -> dict[str, np.ndarray]:
         conditions = self.adapter(conditions, strict=False, stage="inference", **kwargs)
+        # at inference time, inference_variables are estimated by the networks and thus ignored in conditions
+        conditions.pop("inference_variables", None)
         conditions = keras.tree.map_structure(keras.ops.convert_to_tensor, conditions)
         conditions = {"inference_variables": self._sample(num_samples=num_samples, **conditions, **kwargs)}
         conditions = keras.tree.map_structure(keras.ops.convert_to_numpy, conditions)

bayesflow/approximators/model_comparison_approximator.py

@@ -208,6 +208,8 @@ def predict(
         **kwargs,
     ) -> np.ndarray:
         conditions = self.adapter(conditions, strict=False, stage="inference", **kwargs)
+        # at inference time, model_indices are predicted by the networks and thus ignored in conditions
+        conditions.pop("model_indices", None)
         conditions = keras.tree.map_structure(keras.ops.convert_to_tensor, conditions)
 
         output = self._predict(**conditions, **kwargs)

bayesflow/benchmarks/__init__.py

@@ -1,2 +1,6 @@
 from .simulators import TwoMoons
 from .simulators import LotkaVolterra
+
+from ..utils._docs import _add_imports_to_all
+
+_add_imports_to_all(include_modules=[])