Add docs and minimal example

Author: stefanradev93

README.md

@@ -9,7 +9,7 @@ It provides users with:
 
 - A user-friendly API for rapid Bayesian workflows
 - A rich collection of neural network architectures
-- Multi-Backend Support via [Keras3](https://keras.io/keras_3/): You can use [PyTorch](https://github.com/pytorch/pytorch), [TensorFlow](https://github.com/tensorflow/tensorflow), or [JAX](https://github.com/google/jax)
+- Multi-backend support via [Keras3](https://keras.io/keras_3/): You can use [PyTorch](https://github.com/pytorch/pytorch), [TensorFlow](https://github.com/tensorflow/tensorflow), or [JAX](https://github.com/google/jax)
 
 BayesFlow is designed to be a flexible and efficient tool that enables rapid statistical inference
 fueled by continuous progress in generative AI and Bayesian inference.
@@ -29,11 +29,36 @@ 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.
 
-## Disclaimer
+## Getting Started
 
-This is the current dev version of BayesFlow, which constitutes a complete refactor of the library built on Keras 3. This way, you can now use any of the major deep learning libraries as backend for BayesFlow. The refactor is still work in progress with some of the advanced features not yet implemented. We are actively working on them and promise to catch up soon.
+Using the high-level interface is easy, as demonstrated by the minimal working example below:
 
-If you encounter any issues, please don't hesitate to open an issue here on [Github](https://github.com/bayesflow-org/bayesflow/issues) or ask questions on our [Discourse Forums](https://discuss.bayesflow.org/).
+```python
+import bayesflow as bf
+
+workflow = bf.BasicWorkflow(
+    inference_network=bf.networks.FlowMatching(),
+    summary_network=bf.networks.TimeSeriesTransformer(),
+    inference_variables=["parameters"],
+    summary_variables=["observables"],
+    simulator=bf.simulators.SIR()
+)
+
+history = workflow.fit_online(epochs=50, batch_size=32, num_batches_per_epoch=500)
+
+diagnostics = workflow.plot_default_diagnostics(test_data=300)
+```
+
+For an in-depth exposition, check out our walkthrough notebooks below. More tutorials are always welcome!
+
+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. [Hyperparameter optimization](examples/Hyperparameter_Optimization.ipynb)
+7. [Bayesian experimental design](examples/Bayesian_Experimental_Design.ipynb)
+8. [Simple model comparison example](examples/One_Sample_TTest.ipynb)
 
 ## Install
 
@@ -89,19 +114,9 @@ cd <local-path-to-bayesflow-repository>
 conda env create --file environment.yaml --name bayesflow
 ```
 
-## Getting Started
-
-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!
+## Reporting Issues
 
-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. [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)
-8. [Rapid iteration with point estimation and expert statistics for Lotka-Volterra dynamics](examples/Lotka_Volterra_point_estimation_and_expert_stats.ipynb)
-9. More coming soon...
+If you encounter any issues, please don't hesitate to open an issue here on [Github](https://github.com/bayesflow-org/bayesflow/issues) or ask questions on our [Discourse Forums](https://discuss.bayesflow.org/).
 
 ## Documentation \& Help
 

bayesflow/approximators/point_approximator.py

@@ -24,6 +24,29 @@ def estimate(
         split: bool = False,
         **kwargs,
     ) -> dict[str, dict[str, np.ndarray]]:
+        """
+        Provides point estimates based on provided conditions (e.g., observables).
+
+        This method processes input conditions, computes estimates, applies necessary adapter transformations,
+        and optionally splits the resulting arrays along the last axis.
+
+        Parameters
+        ----------
+        conditions : dict[str, np.ndarray]
+            A dictionary mapping variable names to NumPy arrays representing the conditions
+            for the estimation process.
+        split : bool, optional
+            If True, the estimated arrays are split along the last axis, by default False.
+        **kwargs
+            Additional keyword arguments passed to underlying processing functions.
+
+        Returns
+        -------
+        dict[str, dict[str, np.ndarray]]
+            A nested dictionary where the top-level keys correspond to original variable names,
+            and values contain dictionaries mapping estimation results to NumPy arrays.
+        """
+
         conditions = self._prepare_conditions(conditions, **kwargs)
         estimates = self._estimate(**conditions, **kwargs)
         estimates = self._apply_inverse_adapter_to_estimates(estimates, **kwargs)
@@ -45,6 +68,33 @@ def sample(
         split: bool = False,
         **kwargs,
     ) -> dict[str, np.ndarray]:
+        """
+        Generate samples from point estimates based on provided conditions. These samples
+        will generally not correspond to samples from the fully Bayesian posterior, since
+        they will assume some parametric form (e.g., Gaussian in the case of mean score).
+
+        This method draws a specified number of samples according to the given conditions,
+        applies necessary transformations, and optionally splits the resulting arrays along the last axis.
+
+        Parameters
+        ----------
+        num_samples : int
+            The number of samples to generate.
+        conditions : dict[str, np.ndarray]
+            A dictionary mapping variable names to NumPy arrays representing the conditions
+            for the sampling process.
+        split : bool, optional
+            If True, the sampled arrays are split along the last axis, by default False.
+        **kwargs
+            Additional keyword arguments passed to underlying processing functions.
+
+        Returns
+        -------
+        dict[str, np.ndarray]
+            A dictionary where keys correspond to variable names and values are NumPy arrays
+            containing the generated samples.
+        """
+
         conditions = self._prepare_conditions(conditions, **kwargs)
         samples = self._sample(num_samples, **conditions, **kwargs)
         samples = self._apply_inverse_adapter_to_samples(samples, **kwargs)