Docs improve webiste

docs/docs/contribute.md

@@ -38,12 +38,13 @@ the end of every year. Additionally, we mention all contributors in the releases
     propose and then working on your pull request after getting some feedback from
     others.
 
-### How to contribute
+### Contribution workflow
 
-The following steps describe all parts of the workflow for doing a contribution such as
-installing locally `sbi` from source, creating a `conda` environment, setting up
-your `git` repository, etc. We've taken strong inspiration from the guides for
-contribution of [`scikit-learn`](https://scikit-learn.org/stable/developers/contributing.html)
+The following steps describe all parts of the workflow for doing a contribution
+such as installing locally `sbi` from source, creating a `conda` environment,
+setting up your `git` repository, etc. We've taken strong inspiration from the
+contribution guides of
+[`scikit-learn`](https://scikit-learn.org/stable/developers/contributing.html)
 and [`mne`](https://mne.tools/stable/development/contributing.html):
 
 **Step 1**: [Create an account](https://github.com/) on GitHub if you do not
@@ -216,10 +217,3 @@ mkdocs serve
 and open a browser on the page proposed by `mkdocs`. Now, whenever you
 make changes to the markdown files of the documentation, you can see the results
 almost immediately in the browser.
-
-Note that the tutorials and examples are initially written in jupyter notebooks
-and then converted to markdown programatically. To do so locally, you should run
-```
-jupyter nbconvert --to markdown ../tutorials/*.ipynb --output-dir docs/tutorial/
-jupyter nbconvert --to markdown ../examples/*.ipynb --output-dir docs/examples/
-```

docs/docs/examples

@@ -0,0 +1 @@
+../../examples/

docs/docs/faq.md

@@ -1,15 +1,9 @@
 # Frequently asked questions
 
-[Can the algorithms deal with invalid data, e.g., NaN or inf?](faq/question_02_nans.md)
-
-[What should I do when my 'posterior samples are outside of the prior support' in SNPE?](faq/question_01_leakage.md)
-
-[When using multiple workers, I get a pickling error. Can I still use multiprocessing?](faq/question_03_pickling_error.md)
-
-[Can I use the GPU for training the density estimator?](faq/question_04_gpu.md)
-
-[How should I save and load objects in `sbi`?](faq/question_05_pickling.md)
-
-[Can I stop neural network training and resume it later?](faq/question_06_resume_training.md)
-
-[How can I use a prior that is not defined in PyTorch?](faq/question_07_custom_prior.md)
+1. [What should I do when my 'posterior samples are outside of the prior support' in SNPE?](faq/question_01_leakage.md)
+2. [Can the algorithms deal with invalid data, e.g., NaN or inf?](faq/question_02_nans.md)
+3. [When using multiple workers, I get a pickling error. Can I still use multiprocessing?](faq/question_03_pickling_error.md)
+4. [Can I use the GPU for training the density estimator?](faq/question_04_gpu.md)
+5. [How should I save and load objects in `sbi`?](faq/question_05_pickling.md)
+6. [Can I stop neural network training and resume it later?](faq/question_06_resume_training.md)
+7. [How can I use a prior that is not defined in PyTorch?](faq/question_07_custom_prior.md)

docs/docs/install.md

@@ -1,22 +1,26 @@
 # Installation
 
 `sbi` requires Python 3.8 or higher. A GPU is not required, but can lead to
-speed-up in some cases. We recommend to use a [`conda`](https://docs.conda.io/en/latest/miniconda.html) virtual
-environment ([Miniconda installation instructions](https://docs.conda.io/en/latest/miniconda.html)).
-If `conda` is installed on the system, an environment for installing `sbi` can be created as follows:
+speed-up in some cases. We recommend using a
+[`conda`](https://docs.conda.io/en/latest/miniconda.html) virtual environment
+([Miniconda installation
+instructions](https://docs.conda.io/en/latest/miniconda.html)). If `conda` is
+installed on the system, an environment for installing `sbi` can be created as
+follows:
 
 ```commandline
 # Create an environment for sbi (indicate Python 3.8 or higher); activate it
 $ conda create -n sbi_env python=3.10 && conda activate sbi_env
 ```
 
-Independent of whether you are using `conda` or not, `sbi` can be installed using `pip`:
+Independent of whether you are using `conda` or not, `sbi` can be installed
+using `pip`:
 
 ```commandline
 pip install sbi
 ```
 
-To test the installation, drop into a python prompt and run
+To test the installation, drop into a Python prompt and run
 
 ```python
 from sbi.examples.minimal import simple

docs/docs/reference/index.md

@@ -0,0 +1,21 @@
+# API Reference:
+
+<div class="grid cards" markdown>
+
+- [Inference](inference.md)
+  <br/>
+  *SBI algorithms and helper functions.*
+- [Neural Networks](models.md)
+  <br/>
+  *Utilities to build neural network-based density estimators and feature extractors.*
+- [Posteriors](posteriors.md)
+  <br/>
+  *Posterior classes*
+- [Potentials](potentials.md)
+  <br/>
+  *Potential function classes for posterior sampling.*
+- [Analysis](analysis.md)
+  <br/>
+  *Utilities for SBI visualizations and analyses.*
+
+</div>

docs/docs/reference/inference.md

@@ -1,16 +1,5 @@
 # Inference
 
-## Helpers
-
-::: sbi.inference.base.infer
-
-::: sbi.inference.base.simulate_for_sbi
-
-::: sbi.utils.user_input_checks.process_prior
-
-::: sbi.utils.user_input_checks.process_simulator
-
-
 ## Algorithms
 
 ::: sbi.inference.snpe.snpe_a.SNPE_A
@@ -57,3 +46,13 @@
     selection:
       filters: [ "!^_", "^__", "!^__class__" ]
       inherited_members: true
+
+## Helpers
+
+::: sbi.inference.base.infer
+
+::: sbi.inference.base.simulate_for_sbi
+
+::: sbi.utils.user_input_checks.process_prior
+
+::: sbi.utils.user_input_checks.process_simulator

docs/docs/tutorials

@@ -0,0 +1 @@
+../../tutorials/

docs/mkdocs.yml

@@ -3,40 +3,13 @@ site_url: "https://sbi-dev.github.io/sbi/"
 
 nav:
   - Home: index.md
-  - Installation: install.md
-  - Tutorials and Examples:
-      - Introduction:
-        - Getting started: tutorial/00_getting_started_flexible.md
-        - Amortized inference: tutorial/01_gaussian_amortized.md
-        - Implemented algorithms: tutorial/16_implemented_methods.md
-      - Advanced:
-        - Multi-round inference: tutorial/03_multiround_inference.md
-        - Sampling algorithms in sbi: tutorial/11_sampler_interface.md
-        - Custom density estimators: tutorial/04_density_estimators.md
-        - Embedding nets for observations: tutorial/05_embedding_net.md
-        - SBI with trial-based data: tutorial/14_iid_data_and_permutation_invariant_embeddings.md
-        - Handling invalid simulations: tutorial/08_restriction_estimator.md
-        - Crafting summary statistics: tutorial/10_crafting_summary_statistics.md
-      - Diagnostics:
-        - Posterior predictive checks: tutorial/12_diagnostics_posterior_predictive_check.md
-        - Simulation-based calibration: tutorial/13_diagnostics_simulation_based_calibration.md
-        - Density plots and MCMC diagnostics with ArviZ: tutorial/15_mcmc_diagnostics_with_arviz.md
-      - Analysis:
-        - Conditional distributions: tutorial/07_conditional_distributions.md
-        - Posterior sensitivity analysis: tutorial/09_sensitivity_analysis.md
-      - Examples:
-        - Hodgkin-Huxley example: examples/00_HH_simulator.md
-        - Decision making model: examples/01_decision_making_model.md
-  - API Reference:
-    - Inference: reference/inference.md
-    - Neural Networks: reference/models.md
-    - Posteriors: reference/posteriors.md
-    - Potentials: reference/potentials.md
-    - Analysis: reference/analysis.md
+  - Tutorials and Examples: tutorials/index.md
+  - API Reference: reference/index.md
+  - FAQ: faq.md
   - Contributing:
     - How to contribute: contribute.md
     - Code of Conduct: code_of_conduct.md
-  - FAQ: faq.md
+  - Citation: citation.md
   - Credits: credits.md
 
 repo_name: 'sbi-dev/sbi'
@@ -64,6 +37,8 @@ markdown_extensions:
   - extra
   - smarty
   - admonition
+  - attr_list
+  - md_in_html
   - codehilite:
       guess_lang: false
   - toc:
@@ -78,8 +53,7 @@ markdown_extensions:
   - pymdownx.caret
   - pymdownx.critic
   - pymdownx.details
-  - pymdownx.emoji:
-      emoji_generator: tag:yaml.org,2002:python/name:pymdownx.emoji.to_svg
+  - pymdownx.emoji
   - pymdownx.inlinehilite
   - pymdownx.magiclink
   - pymdownx.mark
@@ -89,8 +63,13 @@ markdown_extensions:
       custom_checkbox: true
   - pymdownx.tilde
 
+
 plugins:
   - search
+  - mkdocs-jupyter:
+      include: ["*.ipynb"] # Default: ["*.py", "*.ipynb"]
+      ignore: [".ipynb_checkpoints/*.ipynb"]
+      no_input: True
   - mkdocstrings:
       default_handler: python
       handlers:

pyproject.toml

@@ -47,15 +47,20 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
-dev = [
+doc = [
     # Documentation
+    "jupyter_contrib_nbextensions",
+    "notebook <= 6.4.12",
+    "traitlets <= 5.9.0",
+    "ipython <= 8.9.0",
     "mkdocs",
     "mkdocs-material",
     "markdown-include",
     "mkdocs-redirects",
+    "mkdocs-jupyter",
     "mkdocstrings[python] >= 0.18",
-    "jupyter",
-    "nbconvert",
+]
+dev = [
     # Lint
     "pre-commit == 3.5.0",
     "pyyaml",

tutorials/16_implemented_methods.ipynb

@@ -131,6 +131,34 @@
     "    proposal = RestrictedPrior(prior, accept_reject_fn, sample_with=\"rejection\")"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "3642634d",
+   "metadata": {},
+   "source": [
+    "**BayesFlow: Learning complex stochastic models with invertible neural\n",
+    "networks**<br> by Radev, S. T., Mertens, U. K., Voss, A., Ardizzone, L., & Köthe,\n",
+    "U. (2020) (IEEE transactions on neural networks and learning systems 2020)<br>\n",
+    "[Paper](https://ieeexplore.ieee.org/abstract/document/9298920)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "da7554dd",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# The BayesFlow functionality can be obtained via single-round SNPE.\n",
+    "from sbi.inference import SNPE\n",
+    "\n",
+    "inference = SNPE(prior)\n",
+    "theta = prior.sample((num_sims,))\n",
+    "x = simulator(theta)\n",
+    "inference.append_simulations(theta, x).train()\n",
+    "posterior = inference.build_posterior().set_default_x(x_o)"
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "d13f84e2-d35a-4f54-8cbf-0e4be1a38fb3",
@@ -468,7 +496,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.8.12"
+   "version": "3.10.0"
   },
   "vscode": {
    "interpreter": {