fix: update readme and faq to new tutorials folder.

janfb · janfb · commit a3c54d97261f · 2024-08-27T17:31:01.000+02:00
diff --git a/README.md b/README.md
@@ -7,7 +7,7 @@
 
 ## `sbi`: Simulation-Based Inference
 
-[Getting Started](https://sbi-dev.github.io/sbi/latest/tutorial/00_getting_started/) |
+[Getting Started](https://sbi-dev.github.io/sbi/latest/tutorials/00_getting_started/) |
 [Documentation](https://sbi-dev.github.io/sbi/)
 
 `sbi` is a Python package for simulation-based inference, designed to meet the needs of
@@ -26,7 +26,7 @@ and revealing potential interactions between parameters.
 
 - **Low-Level Interfaces**: For those who require maximum control over the inference
   process, `sbi` provides low-level interfaces that allow you to fine-tune many aspects
-  of your work.
+  of your workflow.
 - **High-Level Interfaces**: If you prefer simplicity and efficiency, `sbi` also offers
   high-level interfaces that enable quick and easy implementation of complex inference
   tasks.
@@ -89,18 +89,18 @@ print(posterior)
 ## Tutorials
 
 If you're new to `sbi`, we recommend starting with our [Getting
-Started](https://sbi-dev.github.io/sbi/latest/tutorial/00_getting_started/) tutorial.
+Started](https://sbi-dev.github.io/sbi/latest/tutorials/00_getting_started/) tutorial.
 
 You can also access and run these tutorials directly in your browser by opening
 [Codespace](https://docs.github.com/en/codespaces/overview). To do so, click the green
 “Code” button on the GitHub repository and select “Open with Codespaces.” This provides
-a fully functional environment where you can explore sbi through Jupyter notebooks.
+a fully functional environment where you can explore `sbi` through Jupyter notebooks.
 
 ## Inference Algorithms
 
 The following inference algorithms are currently available. You can find instructions on
 how to run each of these methods
-[here](https://sbi-dev.github.io/sbi/latest/tutorial/16_implemented_methods/).
+[here](https://sbi-dev.github.io/sbi/latest/tutorials/16_implemented_methods/).
 
 ### Neural Posterior Estimation: amortized (NPE) and sequential (SNPE)
 
diff --git a/docs/docs/faq/question_01_leakage.md b/docs/docs/faq/question_01_leakage.md
@@ -18,12 +18,11 @@ This approach will make sampling slower, but samples will not "leak".
 
 - resort to single-round SNPE and (if necessary) increase your simulation budget.
 
-- if your prior is either Gaussian (torch.distributions.MultivariateNormal) or
-Uniform (sbi.utils.BoxUniform), you can avoid leakage by using a mixture density
-network as density estimator. I.e., using the [flexible
-interface](https://sbi-dev.github.io/sbi/tutorial/03_flexible_interface/), set
-`density_estimator='mdn'`. When running inference, there should be a print
-statement "Using SNPE-C with non-atomic loss".
+- if your prior is either Gaussian (torch.distributions.MultivariateNormal) or Uniform
+(sbi.utils.BoxUniform), you can avoid leakage by using a mixture density network as
+density estimator. I.e., set `density_estimator='mdn'` when creating the `SNPE`
+inference object. When running inference, there should be a print statement "Using
+SNPE-C with non-atomic loss".
 
 - use a different algorithm, e.g., SNRE and SNLE. Note, however, that these algorithms
 can have different issues and potential pitfalls.
diff --git a/docs/docs/faq/question_02_nans.md b/docs/docs/faq/question_02_nans.md
@@ -8,7 +8,7 @@ In cases where a very large fraction of simulations return `NaN` or `inf`,
 discarding many simulations can be wasteful. There are two options to deal with
 this: Either you use the `RestrictionEstimator` to learn regions in parameter
 space that do not produce `NaN` or `inf`, see
-[here](https://sbi-dev.github.io/sbi/tutorial/08_restriction_estimator/).
+[here](https://sbi-dev.github.io/sbi/latest/tutorials/06_restriction_estimator/).
 Alternatively, you can manually substitute the 'invalid' values with a
 reasonable replacement. For example, at the end of your simulation code, you
 search for invalid entries and replace them with a floating point number.
diff --git a/docs/docs/faq/question_03_pickling_error.md b/docs/docs/faq/question_03_pickling_error.md
@@ -40,8 +40,13 @@ def my_simulator(parameters):
 
 You can also write your own code to parallelize simulations with whatever
 multiprocessing framework you prefer. You can then simulate your data outside of
-`sbi` and pass the simulated data as shown in the [flexible
-interface](https://sbi-dev.github.io/sbi/tutorial/02_flexible_interface/):
+`sbi` and pass the simulated data using `.append_simulations`:
+
+```python
+# Given pre-simulated theta and x
+trainer = SNPE(prior)
+trainer.append_simulations(theta, x).train()
+```
 
 ## Some more background
 
diff --git a/docs/docs/faq/question_06_resume_training.md b/docs/docs/faq/question_06_resume_training.md
@@ -2,10 +2,7 @@
 # Can I stop neural network training and resume it later?
 
 Many clusters have a time limit, and `sbi` might exceed this limit. You can
-circumvent this problem by using the [flexible
-interface](https://sbi-dev.github.io/sbi/tutorial/02_flexible_interface/). After
-simulations are finished, `sbi` trains a neural network. If this process takes
-too long, you can stop training and resume it later. The syntax is:
+circumvent this problem by stopping and resuming training:
 
 ```python
 inference = SNPE(prior=prior)
diff --git a/docs/docs/index.md b/docs/docs/index.md
@@ -45,7 +45,7 @@ Then, check out our material:
 -  :rocket: [__Tutorials and Examples__](tutorials/index.md)
    <br/><br/>
    *Various examples illustrating how to<br/> [get
-   started](tutorials/00_getting_started_flexible.md) or use the `sbi` package.*
+   started](tutorials/00_getting_started.md) or use the `sbi` package.*
 
 -  :building_construction: [__Reference API__](reference/index.md)
    <br/><br/>
diff --git a/docs/docs/tutorials/index.md b/docs/docs/tutorials/index.md
@@ -15,7 +15,7 @@ inference.
 ## Introduction
 
 <div class="grid cards" markdown>
-- [Getting started](00_getting_started_flexible.md)
+- [Getting started](00_getting_started.md)
 - [Amortized inference](01_gaussian_amortized.md)
 - [More flexibility for training and sampling](18_training_interface.md)
 - [Implemented algorithms](16_implemented_methods.md)
diff --git a/sbi/inference/base.py b/sbi/inference/base.py
@@ -57,7 +57,7 @@ def infer(
     The scope of this function is limited to the most essential features of sbi. For
     more flexibility (e.g. multi-round inference, different density estimators) please
     use the flexible interface described here:
-    https://sbi-dev.github.io/sbi/tutorial/02_flexible_interface/
+    https://sbi-dev.github.io/sbi/latest/tutorials/02_multiround_inference/
 
     Args:
         simulator: A function that takes parameters $\theta$ and maps them to
@@ -98,7 +98,7 @@ def infer(
         warn(
             "We discourage the use the simple interface in more complicated settings. "
             "Have a look into the flexible interface, e.g. in our tutorial "
-            "(https://sbi-dev.github.io/sbi/tutorial/02_flexible_interface/).",
+            "(https://sbi-dev.github.io/sbi/latest/tutorials/00_getting_started).",
             stacklevel=2,
         )
     # Set variables to empty dicts to be able to pass them
diff --git a/tutorials/00_getting_started.ipynb b/tutorials/00_getting_started.ipynb
@@ -11,7 +11,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Note, you can find the original version of this notebook at [/tutorials/00_getting_started_flexible.ipynb](https://github.com/sbi-dev/sbi/blob/main/tutorials/00_getting_started_flexible.ipynb) in the `sbi` repository."
+    "Note, you can find the original version of this notebook at [/tutorials/00_getting_started.ipynb](https://github.com/sbi-dev/sbi/blob/main/tutorials/00_getting_started.ipynb) in the `sbi` repository."
    ]
   },
   {
@@ -137,7 +137,7 @@
    "source": [
     "> Note: In the `sbi` toolbox, NPE is run by using the `SNPE` (Sequential NPE) class for only one iteration of simulation and training. \n",
     "\n",
-    "> Note: This is where you could specify an alternative inference object such as (S)NRE for ratio estimation or (S)NLE for likelihood estimation. Here, you can see [all implemented methods](https://sbi-dev.github.io/sbi/tutorial/16_implemented_methods/)."
+    "> Note: This is where you could specify an alternative inference object such as (S)NRE for ratio estimation or (S)NLE for likelihood estimation. Here, you can see [all implemented methods](https://sbi-dev.github.io/sbi/latest/tutorials/16_implemented_methods/)."
    ]
   },
   {
diff --git a/tutorials/01_gaussian_amortized.ipynb b/tutorials/01_gaussian_amortized.ipynb
@@ -20,7 +20,7 @@
    "source": [
     "In this tutorial, we introduce **amortization** that is the capability to evaluate the posterior for different observations without having to re-run inference.\n",
     "\n",
-    "We will demonstrate how `sbi` can infer an amortized posterior for the illustrative linear Gaussian example introduced in [Getting Started](https://sbi-dev.github.io/sbi/tutorial/00_getting_started_flexible/), that takes in 3 parameters ($\\theta$). "
+    "We will demonstrate how `sbi` can infer an amortized posterior for the illustrative linear Gaussian example introduced in [Getting Started](https://sbi-dev.github.io/sbi/latest/tutorials/00_getting_started/), that takes in 3 parameters ($\\theta$). "
    ]
   },
   {
diff --git a/tutorials/04_embedding_networks.ipynb b/tutorials/04_embedding_networks.ipynb
@@ -250,7 +250,7 @@
     "\n",
     "- Fully-connected multi-layer perceptron\n",
     "- Convolutional neural network (1D and 2D convolutions)\n",
-    "- Permutation-invariant neural network (for trial-based data, see [here](https://sbi-dev.github.io/sbi/tutorial/14_iid_data_and_permutation_invariant_embeddings/))\n",
+    "- Permutation-invariant neural network (for trial-based data, see [here](https://sbi-dev.github.io/sbi/latest/tutorials/12_iid_data_and_permutation_invariant_embeddings/))\n",
     "\n",
     "In the example considered here, the most appropriate `embedding_net` would be a CNN for two-dimensional images. We can setup it as per:\n"
    ]
diff --git a/tutorials/05_conditional_distributions.ipynb b/tutorials/05_conditional_distributions.ipynb
@@ -26204,7 +26204,7 @@
    "source": [
     "## Sampling conditional distributions\n",
     "\n",
-    "So far, we have demonstrated how one can plot 2D conditional distributions with `conditional_pairplot()` and how one can compute the pairwise conditional correlation coefficient with `conditional_corrcoeff()`. In some cases, it can be useful to keep a subset of parameters fixed and to vary **more than two** parameters. This can be done by sampling the conditonal posterior $p(\\theta_i | \\theta_{j \\neq i}, x_o)$. As of `sbi` `v0.18.0`, this functionality requires using the [sampler interface](https://sbi-dev.github.io/sbi/tutorial/11_sampler_interface/). In this tutorial, we demonstrate this functionality on a linear gaussian simulator with four parameters. We would like to fix the forth parameter to $\\theta_4=0.2$ and sample the first three parameters given that value, i.e. we want to sample $p(\\theta_1, \\theta_2, \\theta_3 | \\theta_4 = 0.2, x_o)$. For an application in neuroscience, see [Deistler, Gonçalves, Macke, 2021](https://www.biorxiv.org/content/10.1101/2021.07.30.454484v4.abstract).\n"
+    "So far, we have demonstrated how one can plot 2D conditional distributions with `conditional_pairplot()` and how one can compute the pairwise conditional correlation coefficient with `conditional_corrcoeff()`. In some cases, it can be useful to keep a subset of parameters fixed and to vary **more than two** parameters. This can be done by sampling the conditonal posterior $p(\\theta_i | \\theta_{j \\neq i}, x_o)$. As of `sbi` `v0.18.0`, this functionality requires using the [sampler interface](https://sbi-dev.github.io/sbi/latest/tutorials/09_sampler_interface/). In this tutorial, we demonstrate this functionality on a linear gaussian simulator with four parameters. We would like to fix the forth parameter to $\\theta_4=0.2$ and sample the first three parameters given that value, i.e. we want to sample $p(\\theta_1, \\theta_2, \\theta_3 | \\theta_4 = 0.2, x_o)$. For an application in neuroscience, see [Deistler, Gonçalves, Macke, 2021](https://www.biorxiv.org/content/10.1101/2021.07.30.454484v4.abstract).\n"
    ]
   },
   {
@@ -26280,7 +26280,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Now we want to build the conditional potential (please read throught the tutorial [09_sampler_interface](https://www.mackelab.org/sbi/tutorial/09_sampler_interface/) for an explanation of potential functions). For this, we have to pass a `condition`. In our case, we want to condition the forth parameter on $\\theta_4=0.2$. Regardless of how many parameters one wants to condition on, in `sbi`, one has to pass a `condition` value for all parameters. The first three values will simply be ignored. We can tell the algorithm which parameters should be kept fixed and which ones should be sampled with the argument `dims_to_sample`.\n"
+    "Now we want to build the conditional potential (please read through the tutorial [09_sampler_interface](https://sbi-dev.github.io/sbi/dev/tutorials/09_sampler_interface/) for an explanation of potential functions). For this, we have to pass a `condition`. In our case, we want to condition the forth parameter on $\\theta_4=0.2$. Regardless of how many parameters one wants to condition on, in `sbi`, one has to pass a `condition` value for all parameters. The first three values will simply be ignored. We can tell the algorithm which parameters should be kept fixed and which ones should be sampled with the argument `dims_to_sample`.\n"
    ]
   },
   {
diff --git a/tutorials/18_training_interface.ipynb b/tutorials/18_training_interface.ipynb
@@ -240,7 +240,7 @@
    "id": "3f1cab68-4196-47ee-a4c2-3ed2cd8a454b",
    "metadata": {},
    "source": [
-    "You can also wrap the `DensityEstimator` as a `DirectPosterior`. The `DirectPosterior` is also returned by  `inference.build_posterior` and you have already learned how to use it in the [introduction tutorial](https://sbi-dev.github.io/sbi/dev/tutorials/00_getting_started_flexible/) and the [amortization tutotrial](https://sbi-dev.github.io/sbi/dev/tutorials/01_gaussian_amortized/). It adds the following functionality over the raw `DensityEstimator`:\n",
+    "You can also wrap the `DensityEstimator` as a `DirectPosterior`. The `DirectPosterior` is also returned by  `inference.build_posterior` and you have already learned how to use it in the [introduction tutorial](https://sbi-dev.github.io/sbi/dev/tutorials/00_getting_started/) and the [amortization tutotrial](https://sbi-dev.github.io/sbi/dev/tutorials/01_gaussian_amortized/). It adds the following functionality over the raw `DensityEstimator`:\n",
     "\n",
     "- automatically reject samples outside of the prior bounds  \n",
     "- compute the Maximum-a-posteriori (MAP) estimate\n",
diff --git a/tutorials/Example_01_DecisionMakingModel.ipynb b/tutorials/Example_01_DecisionMakingModel.ipynb
@@ -7,7 +7,7 @@
     "# SBI for decision-making models\n",
     "\n",
     "In [a previous\n",
-    "tutorial](https://sbi-dev.github.io/sbi/tutorial/14_iid_data_and_permutation_invariant_embedding.md),\n",
+    "tutorial](https://sbi-dev.github.io/sbi/latest/tutorials/12_iid_data_and_permutation_invariant_embeddings.md),\n",
     "we showed how to use SBI with trial-based iid data. Such scenarios can arise,\n",
     "for example, in models of perceptual decision making. In addition to trial-based\n",
     "iid data points, these models often come with mixed data types and varying\n",

Original file line number	Diff line number	Diff line change
`@@ -11,7 +11,7 @@`
`11`	`11`	`"cell_type": "markdown",`
`12`	`12`	`"metadata": {},`
`13`	`13`	`"source": [`
`14`		- "Note, you can find the original version of this notebook at [/tutorials/00_getting_started_flexible.ipynb](https://github.com/sbi-dev/sbi/blob/main/tutorials/00_getting_started_flexible.ipynb) in the `sbi` repository."
	`14`	+ "Note, you can find the original version of this notebook at [/tutorials/00_getting_started.ipynb](https://github.com/sbi-dev/sbi/blob/main/tutorials/00_getting_started.ipynb) in the `sbi` repository."
`15`	`15`	`]`
`16`	`16`	`},`
`17`	`17`	`{`
`@@ -137,7 +137,7 @@`
`137`	`137`	`"source": [`
`138`	`138`	"> Note: In the `sbi` toolbox, NPE is run by using the `SNPE` (Sequential NPE) class for only one iteration of simulation and training. \n",
`139`	`139`	`"\n",`
`140`		`- "> Note: This is where you could specify an alternative inference object such as (S)NRE for ratio estimation or (S)NLE for likelihood estimation. Here, you can see [all implemented methods](https://sbi-dev.github.io/sbi/tutorial/16_implemented_methods/)."`
	`140`	`+ "> Note: This is where you could specify an alternative inference object such as (S)NRE for ratio estimation or (S)NLE for likelihood estimation. Here, you can see [all implemented methods](https://sbi-dev.github.io/sbi/latest/tutorials/16_implemented_methods/)."`
`141`	`141`	`]`
`142`	`142`	`},`
`143`	`143`	`{`
Original file line number	Diff line number	Diff line change
`@@ -20,7 +20,7 @@`
`20`	`20`	`"source": [`
`21`	`21`	`"In this tutorial, we introduce amortization that is the capability to evaluate the posterior for different observations without having to re-run inference.\n",`
`22`	`22`	`"\n",`
`23`		- "We will demonstrate how `sbi` can infer an amortized posterior for the illustrative linear Gaussian example introduced in [Getting Started](https://sbi-dev.github.io/sbi/tutorial/00_getting_started_flexible/), that takes in 3 parameters ($\\theta$). "
	`23`	+ "We will demonstrate how `sbi` can infer an amortized posterior for the illustrative linear Gaussian example introduced in [Getting Started](https://sbi-dev.github.io/sbi/latest/tutorials/00_getting_started/), that takes in 3 parameters ($\\theta$). "
`24`	`24`	`]`
`25`	`25`	`},`
`26`	`26`	`{`