Release 2.0.4

.gitignore

@@ -39,3 +39,6 @@ docs/
 
 # MacOS
 .DS_Store
+
+# Rproj
+.Rproj.user

README.md

@@ -49,45 +49,12 @@ neural networks for parameter estimation, model comparison, and model validation
 when working with intractable simulators whose behavior as a whole is too
 complex to be described analytically.
 
-## Getting Started
-
-Using the high-level interface is easy, as demonstrated by the minimal working example below:
-
-```python
-import bayesflow as bf
-
-workflow = bf.BasicWorkflow(
-    inference_network=bf.networks.CouplingFlow(),
-    summary_network=bf.networks.TimeSeriesNetwork(),
-    inference_variables=["parameters"],
-    summary_variables=["observables"],
-    simulator=bf.simulators.SIR()
-)
-
-history = workflow.fit_online(epochs=15, batch_size=32, num_batches_per_epoch=200)
-
-diagnostics = workflow.plot_default_diagnostics(test_data=300)
-```
-
-For an in-depth exposition, check out our walkthrough notebooks below.
-
-1. [Linear regression starter example](examples/Linear_Regression_Starter.ipynb)
-2. [From ABC to BayesFlow](examples/From_ABC_to_BayesFlow.ipynb)
-3. [Two moons starter example](examples/Two_Moons_Starter.ipynb)
-4. [Rapid iteration with point estimators](examples/Lotka_Volterra_Point_Estimation_and_Expert_Stats.ipynb)
-5. [SIR model with custom summary network](examples/SIR_Posterior_Estimation.ipynb)
-6. [Bayesian experimental design](examples/Bayesian_Experimental_Design.ipynb)
-7. [Simple model comparison example](examples/One_Sample_TTest.ipynb)
-8. [Moving from BayesFlow v1.1 to v2.0](examples/From_BayesFlow_1.1_to_2.0.ipynb)
-
-More tutorials are always welcome! Please consider making a pull request if you have a cool application that you want to contribute.
-
 ## Install
 
-You can install the latest stable version from PyPI using:
+We currently support Python 3.10 to 3.12. You can install the latest stable version from PyPI using:
 
 ```bash
-pip install bayesflow
+pip install "bayesflow>=2.0"
 ```
 
 If you want the latest features, you can install from source:
@@ -132,9 +99,47 @@ export KERAS_BACKEND=jax
 
 This way, you also don't have to manually set the backend every time you are starting Python to use BayesFlow.
 
-**Caution:** Some development environments (e.g., VSCode or PyCharm) can silently overwrite environment variables. If you have set your backend as an environment variable and you still get keras-related import errors when loading BayesFlow, these IDE shenanigans might be the culprit. Try setting the keras backend in your Python script via `import os; os.environ["KERAS_BACKEND"] = "<YOUR-BACKEND>"`.
+## Getting Started
+
+Using the high-level interface is easy, as demonstrated by the minimal working example below:
+
+```python
+import bayesflow as bf
+
+workflow = bf.BasicWorkflow(
+    inference_network=bf.networks.CouplingFlow(),
+    summary_network=bf.networks.TimeSeriesNetwork(),
+    inference_variables=["parameters"],
+    summary_variables=["observables"],
+    simulator=bf.simulators.SIR()
+)
+
+history = workflow.fit_online(epochs=15, batch_size=32, num_batches_per_epoch=200)
+
+diagnostics = workflow.plot_default_diagnostics(test_data=300)
+```
+
+For an in-depth exposition, check out our expanding list of resources below.
+
+### Books
+
+Many examples from [Bayesian Cognitive Modeling: A Practical Course](https://bayesmodels.com/) by Lee & Wagenmakers (2013) in [BayesFlow](https://kucharssim.github.io/bayesflow-cognitive-modeling-book/).
+
+### Tutorial notebooks
+
+1. [Linear regression starter example](examples/Linear_Regression_Starter.ipynb)
+2. [From ABC to BayesFlow](examples/From_ABC_to_BayesFlow.ipynb)
+3. [Two moons starter example](examples/Two_Moons_Starter.ipynb)
+4. [Rapid iteration with point estimators](examples/Lotka_Volterra_Point_Estimation.ipynb)
+5. [SIR model with custom summary network](examples/SIR_Posterior_Estimation.ipynb)
+6. [Bayesian experimental design](examples/Bayesian_Experimental_Design.ipynb)
+7. [Simple model comparison example](examples/One_Sample_TTest.ipynb)
+8. [Likelihood estimation](examples/Likelihood_Estimation.ipynb)
+9. [Moving from BayesFlow v1.1 to v2.0](examples/From_BayesFlow_1.1_to_2.0.ipynb)
+
+More tutorials are always welcome! Please consider making a pull request if you have a cool application that you want to contribute.
 
-### From Source
+## Contributing
 
 If you want to contribute to BayesFlow, we recommend installing it from source, see [CONTRIBUTING.md](CONTRIBUTING.md) for more details.
 

bayesflow/adapters/adapter.py

@@ -14,17 +14,24 @@
     Drop,
     ExpandDims,
     FilterTransform,
+    Group,
     Keep,
     Log,
     MapTransform,
+    NNPE,
     NumpyTransform,
     OneHot,
     Rename,
     SerializableCustomTransform,
+    Squeeze,
     Sqrt,
     Standardize,
     ToArray,
     Transform,
+    Ungroup,
+    RandomSubsample,
+    Take,
+    NanToNum,
 )
 from .transforms.filter_transform import Predicate
 
@@ -598,6 +605,52 @@ def expand_dims(self, keys: str | Sequence[str], *, axis: int | tuple):
         self.transforms.append(transform)
         return self
 
+    def group(self, keys: Sequence[str], into: str, *, prefix: str = ""):
+        """Append a :py:class:`~transforms.Group` transform to the adapter.
+
+        Groups the given variables as a dictionary in the key `into`. As most transforms do
+        not support nested structures, this should usually be the last transform in the adapter.
+
+        Parameters
+        ----------
+        keys : Sequence of str
+            The names of the variables to group together.
+        into : str
+            The name of the variable to store the grouped variables in.
+        prefix : str, optional
+            An optional common prefix of the variable names before grouping, which will be removed after grouping.
+
+        Raises
+        ------
+        ValueError
+            If a prefix is specified, but a provided key does not start with the prefix.
+        """
+        if isinstance(keys, str):
+            keys = [keys]
+
+        transform = Group(keys=keys, into=into, prefix=prefix)
+        self.transforms.append(transform)
+        return self
+
+    def ungroup(self, key: str, *, prefix: str = ""):
+        """Append an :py:class:`~transforms.Ungroup` transform to the adapter.
+
+        Ungroups the the variables in `key` from a dictionary into individual entries. Most transforms do
+        not support nested structures, so this can be used to flatten a nested structure.
+        The nesting can be re-established after the transforms using the :py:meth:`group` method.
+
+        Parameters
+        ----------
+        key : str
+            The name of the variable to ungroup. The corresponding variable has to be a dictionary.
+        prefix : str, optional
+            An optional common prefix that will be added to the ungrouped variable names. This can be necessary
+            to avoid duplicate names.
+        """
+        transform = Ungroup(key=key, prefix=prefix)
+        self.transforms.append(transform)
+        return self
+
     def keep(self, keys: str | Sequence[str]):
         """Append a :py:class:`~transforms.Keep` transform to the adapter.
 
@@ -648,6 +701,43 @@ def map_dtype(self, keys: str | Sequence[str], to_dtype: str):
         self.transforms.append(transform)
         return self
 
+    def nnpe(
+        self,
+        keys: str | Sequence[str],
+        *,
+        spike_scale: float | None = None,
+        slab_scale: float | None = None,
+        per_dimension: bool = True,
+        seed: int | None = None,
+    ):
+        """Append an :py:class:`~transforms.NNPE` transform to the adapter.
+
+        Parameters
+        ----------
+        keys : str or Sequence of str
+            The names of the variables to transform.
+        spike_scale : float or np.ndarray or None, default=None
+            The scale of the spike (Normal) distribution. Automatically determined if None.
+        slab_scale : float or np.ndarray or None, default=None
+            The scale of the slab (Cauchy) distribution. Automatically determined if None.
+        per_dimension : bool, default=True
+            If true, noise is applied per dimension of the last axis of the input data.
+            If false, noise is applied globally.
+        seed : int or None
+            The seed for the random number generator. If None, a random seed is used.
+        """
+        if isinstance(keys, str):
+            keys = [keys]
+
+        transform = MapTransform(
+            {
+                key: NNPE(spike_scale=spike_scale, slab_scale=slab_scale, per_dimension=per_dimension, seed=seed)
+                for key in keys
+            }
+        )
+        self.transforms.append(transform)
+        return self
+
     def one_hot(self, keys: str | Sequence[str], num_classes: int):
         """Append a :py:class:`~transforms.OneHot` transform to the adapter.
 
@@ -665,6 +755,28 @@ def one_hot(self, keys: str | Sequence[str], num_classes: int):
         self.transforms.append(transform)
         return self
 
+    def random_subsample(self, key: str, *, sample_size: int | float, axis: int = -1):
+        """
+        Append a :py:class:`~transforms.RandomSubsample` transform to the adapter.
+
+        Parameters
+        ----------
+        key : str or Sequence of str
+            The name of the variable to subsample.
+        sample_size : int or float
+            The number of samples to draw, or a fraction between 0 and 1 of the total number of samples to draw.
+        axis: int, optional
+            Which axis to draw samples over. The last axis is used by default.
+        """
+
+        if not isinstance(key, str):
+            raise TypeError("Can only subsample one batch entry at a time.")
+
+        transform = MapTransform({key: RandomSubsample(sample_size=sample_size, axis=axis)})
+
+        self.transforms.append(transform)
+        return self
+
     def rename(self, from_key: str, to_key: str):
         """Append a :py:class:`~transforms.Rename` transform to the adapter.
 
@@ -708,6 +820,24 @@ def split(self, key: str, *, into: Sequence[str], indices_or_sections: int | Seq
 
         return self
 
+    def squeeze(self, keys: str | Sequence[str], *, axis: int | tuple):
+        """Append a :py:class:`~transforms.Squeeze` transform to the adapter.
+
+        Parameters
+        ----------
+        keys : str or Sequence of str
+            The names of the variables to squeeze.
+        axis : int or tuple
+            The axis to squeeze. As the number of batch dimensions might change, we advise using negative
+            numbers (i.e., indexing from the end instead of the start).
+        """
+        if isinstance(keys, str):
+            keys = [keys]
+
+        transform = MapTransform({key: Squeeze(axis=axis) for key in keys})
+        self.transforms.append(transform)
+        return self
+
     def sqrt(self, keys: str | Sequence[str]):
         """Append an :py:class:`~transforms.Sqrt` transform to the adapter.
 
@@ -741,7 +871,7 @@ def standardize(
             Names of variables to include in the transform.
         exclude : str or Sequence of str, optional
             Names of variables to exclude from the transform.
-        **kwargs : dict
+        **kwargs :
             Additional keyword arguments passed to the transform.
         """
         transform = FilterTransform(
@@ -754,6 +884,42 @@ def standardize(
         self.transforms.append(transform)
         return self
 
+    def take(
+        self,
+        include: str | Sequence[str] = None,
+        *,
+        indices: Sequence[int],
+        axis: int = -1,
+        predicate: Predicate = None,
+        exclude: str | Sequence[str] = None,
+    ):
+        """
+        Append a :py:class:`~transforms.Take` transform to the adapter.
+
+        Parameters
+        ----------
+        include : str or Sequence of str, optional
+            Names of variables to include in the transform.
+        indices : Sequence of int
+            Which indices to take from the data.
+        axis : int, optional
+            Which axis to take from. The last axis is used by default.
+        predicate : Predicate, optional
+            Function that indicates which variables should be transformed.
+        exclude : str or Sequence of str, optional
+            Names of variables to exclude from the transform.
+        """
+        transform = FilterTransform(
+            transform_constructor=Take,
+            predicate=predicate,
+            include=include,
+            exclude=exclude,
+            indices=indices,
+            axis=axis,
+        )
+        self.transforms.append(transform)
+        return self
+
     def to_array(
         self,
         include: str | Sequence[str] = None,
@@ -791,3 +957,34 @@ def to_dict(self):
         transform = ToDict()
         self.transforms.append(transform)
         return self
+
+    def nan_to_num(
+        self,
+        keys: str | Sequence[str],
+        default_value: float = 0.0,
+        return_mask: bool = False,
+        mask_prefix: str = "mask",
+    ):
+        """
+        Append :py:class:`~bf.adapters.transforms.NanToNum` transform to the adapter.
+
+        Parameters
+        ----------
+        keys : str or sequence of str
+            The names of the variables to clean / mask.
+        default_value : float
+            Value to substitute wherever data is NaN. Defaults to 0.0.
+        return_mask : bool
+            If True, encode a binary missingness mask alongside the data. Defaults to False.
+        mask_prefix : str
+            Prefix for the mask key in the output dictionary. Defaults to 'mask_'. If the mask key already exists,
+            a ValueError is raised to avoid overwriting existing masks.
+        """
+        if isinstance(keys, str):
+            keys = [keys]
+
+        for key in keys:
+            self.transforms.append(
+                NanToNum(key=key, default_value=default_value, return_mask=return_mask, mask_prefix=mask_prefix)
+            )
+        return self

bayesflow/adapters/transforms/__init__.py

@@ -8,21 +8,28 @@
 from .elementwise_transform import ElementwiseTransform
 from .expand_dims import ExpandDims
 from .filter_transform import FilterTransform
+from .group import Group
 from .keep import Keep
 from .log import Log
 from .map_transform import MapTransform
+from .nnpe import NNPE
 from .numpy_transform import NumpyTransform
 from .one_hot import OneHot
 from .rename import Rename
 from .scale import Scale
 from .serializable_custom_transform import SerializableCustomTransform
 from .shift import Shift
 from .split import Split
+from .squeeze import Squeeze
 from .sqrt import Sqrt
 from .standardize import Standardize
 from .to_array import ToArray
 from .to_dict import ToDict
 from .transform import Transform
+from .random_subsample import RandomSubsample
+from .take import Take
+from .ungroup import Ungroup
+from .nan_to_num import NanToNum
 
 from ...utils._docs import _add_imports_to_all