DOC improve organisation #1147

tomMoral · 2024-04-22T01:40:43Z

Related to doc improvements described in #1008

codecov · 2024-04-22T01:51:03Z

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 74.24%. Comparing base (0b5f931) to head (867355a).
Report is 8 commits behind head on main.

Additional details and impacted files

@@             Coverage Diff             @@
##             main    #1147       +/-   ##
===========================================
- Coverage   85.13%   74.24%   -10.89%     
===========================================
  Files          90       90               
  Lines        6651     6931      +280     
===========================================
- Hits         5662     5146      -516     
- Misses        989     1785      +796

Flag	Coverage Δ
unittests	`74.24% <ø> (-10.89%)`	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

see 49 files with indirect coverage changes

janfb · 2024-05-07T13:00:47Z

Note: for building the docs site locally I needed to run the following commands in an empty condo env with python=3.10:

pip install -e ".[doc,dev]"
pip install jupyter_contrib_nbextensions
pip install --upgrade notebook==6.4.12
pip uninstall traitlets 
pip install traitlets==5.9.0
pip uninstall ipython
pip install ipython==8.9.0

...

mkdocs serve

I believe this is due to our custom Jupyter notebook extensions (e.g., jupyter_contrib_nbextensions) not being compatible with the new notebook 7 release from last year. As a consequence, we need to downgrade notebook, traitlets and ipython.

janfb

this is great, thanks a lot!

I added some comments and pushed 2 commits implementing some of my suggestions.

janfb · 2024-05-07T13:01:37Z

docs/docs/contribute.md

-
-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/
-```


this now happening automatically when running mkdocs serve?

yes, with the mkdocs-jupyter extension.
However, this makes the rendering a bit slower with mkdocs serve as this is run each time you do an update on any file. I will see if it is possible to cache this.

janfb · 2024-05-07T13:29:51Z

docs/docs/index.md

I really like the update for the landing page!
I will make a separate commit with some refactoring. Happy to get your comments on those changes as well!

janfb · 2024-05-07T13:31:14Z

docs/mkdocs.yml

+        - Getting started: tutorials/00_getting_started_flexible.ipynb
+        - Amortized inference: tutorials/01_gaussian_amortized.ipynb
+        - Implemented algorithms: tutorials/16_implemented_methods.md


why do some notebooks have the notebook file ending, and others .md? I guess because the conversion is happening automatically now?

Yes I am not sure either which one is the right one, I will check this.

janfb · 2024-05-07T13:35:33Z

docs/docs/index.md

+```python
+inference = SNPE(prior=prior)
+_ = inference.append_simulations(theta, x).train()
+posterior = inference.build_posterior()
+```


not sure we still need this when we replace the GIF above with actual code that looks very similar to this one here.

I think this showcase the two different API so I would keep it.
But it is true it is more redundant.

janfb · 2024-05-07T13:41:31Z

docs/docs/index.md

+```python
+# simulation
+theta = prior.sample((1000,))
+x = simulator(theta)
+
+# training
+inference = SNPE(prior).append_simulations(theta, x)
+inference.train()
+
+# inference
+posterior = inference.build_posterior()
+posterior_samples = posterior.sample((1000,), x=x_o)
+```


I think it's time to remove the GIF. It just changes to fast and I believe it's not really helpful. I suggest to replace it with an actual code snippet.

I like the idea of an actual code snipet! I think this helps onboarding a lot.
I suggest to add a dummy prior and simulator so this code is actually runnable, it helps a lot understanding the base concept of the toolkit.

tomMoral

A few more comment, I will take another look at the mkdocs-jupyter extension in the afternoon

tomMoral · 2024-05-14T07:44:11Z

docs/docs/index.md

+```python
+# simulation
+theta = prior.sample((1000,))
+x = simulator(theta)
+
+# training
+inference = SNPE(prior).append_simulations(theta, x)
+inference.train()
+
+# inference
+posterior = inference.build_posterior()
+posterior_samples = posterior.sample((1000,), x=x_o)
+```


I like the idea of an actual code snipet! I think this helps onboarding a lot.
I suggest to add a dummy prior and simulator so this code is actually runnable, it helps a lot understanding the base concept of the toolkit.

tomMoral · 2024-05-14T07:53:46Z

docs/docs/index.md

+# simulation
+theta = prior.sample((1000,))
+x = simulator(theta)
+
+# training
+inference = SNPE(prior).append_simulations(theta, x)
+inference.train()
+
+# inference
+posterior = inference.build_posterior()
+posterior_samples = posterior.sample((1000,), x=x_o)


Suggested change

# simulation

theta = prior.sample((1000,))

x = simulator(theta)

# training

inference = SNPE(prior).append_simulations(theta, x)

inference.train()

# inference

posterior = inference.build_posterior()

posterior_samples = posterior.sample((1000,), x=x_o)

import torch

from sbi.inference import SNPE

from sbi.utils import BoxUniform

#define prior and simulator

prior = BoxUniform(torch.tensor([0]), torch.tensor([1]))

simulator = lambda theta: theta + 1

# simulation

theta = prior.sample((1000,))

x = simulator(theta)

# training

inference = SNPE(prior).append_simulations(theta, x)

inference.train()

# inference

x_o = torch.tensor([1.5])

posterior = inference.build_posterior()

posterior_samples = posterior.sample((1000,), x=x_o)

tomMoral · 2024-05-14T07:56:15Z

docs/docs/index.md

+```python
+inference = SNPE(prior=prior)
+_ = inference.append_simulations(theta, x).train()
+posterior = inference.build_posterior()
+```


I think this showcase the two different API so I would keep it.
But it is true it is more redundant.

tomMoral · 2024-05-14T07:57:16Z

docs/docs/reference/index.md

+
+- [Inference](inference.md)
+  <br/>
+  *XXX*


I was not sure of what to put here, if you have suggestion that would be perfect.

tomMoral · 2024-05-14T07:57:39Z

docs/mkdocs.yml

+        - Getting started: tutorials/00_getting_started_flexible.ipynb
+        - Amortized inference: tutorials/01_gaussian_amortized.ipynb
+        - Implemented algorithms: tutorials/16_implemented_methods.md


Yes I am not sure either which one is the right one, I will check this.

DOC improve organisation

8a77ffa

tomMoral added 2 commits April 22, 2024 08:43

FIX pre-commit hooks

14dbf9c

add index for tutorials

89b45a0

janfb added 2 commits May 7, 2024 15:33

refactor new landing page.

8818d70

update docs dependencies

867355a

janfb reviewed May 7, 2024

View reviewed changes

tomMoral commented May 14, 2024

View reviewed changes

janfb requested a review from michaeldeistler May 17, 2024 15:11

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

DOC improve organisation #1147

DOC improve organisation #1147

tomMoral commented Apr 22, 2024 •

edited

codecov bot commented Apr 22, 2024 •

edited

janfb commented May 7, 2024 •

edited

janfb left a comment

janfb May 7, 2024

tomMoral May 14, 2024

janfb May 7, 2024 •

edited

janfb May 7, 2024 •

edited

tomMoral May 14, 2024

janfb May 7, 2024

tomMoral May 14, 2024

janfb May 7, 2024

michaeldeistler May 7, 2024

tomMoral May 14, 2024

tomMoral left a comment

tomMoral May 14, 2024

tomMoral May 14, 2024

tomMoral May 14, 2024

tomMoral May 14, 2024

tomMoral May 14, 2024

DOC improve organisation #1147

Are you sure you want to change the base?

DOC improve organisation #1147

Conversation

tomMoral commented Apr 22, 2024 • edited

codecov bot commented Apr 22, 2024 • edited

Codecov Report

janfb commented May 7, 2024 • edited

janfb left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

janfb May 7, 2024 • edited

Choose a reason for hiding this comment

janfb May 7, 2024 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tomMoral left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tomMoral commented Apr 22, 2024 •

edited

codecov bot commented Apr 22, 2024 •

edited

janfb commented May 7, 2024 •

edited

janfb May 7, 2024 •

edited

janfb May 7, 2024 •

edited