Examples in the online documentation

[robmoss]

The Numerical Examples section of the documentation introduces a range of mathematical models, and shows various output plots generated by LINFA.

• To help the reader understand how each model is implemented in LINFA, it might be helpful to either (a) link to the Python source file for each example; or (b) use the literalinclude directive to include relevant chunks of code in the documentation itself.

• Does the log-loss for the Three-element Windkessel Model get worse as the number of iterations increases? If so, should this page include some comments that point this out and discuss the implications for the obtained fit?

• The README.md links to two very helpful notebook tutorials (2D and 3D ballistic models). These notebooks demonstrate how to perform inference tasks and highlight some of LINFA's key features. I found them very helpful in trying to understand how to run LINFA with my own model (as opposed to running one of the models in the test suite) — I felt that these notebooks were the missing link I was looking for.

  It would be great to have some of this information included in the online documentation; possibly as a separate page under "Numerical examples", or anywhere else that the authors feel is suitable. I did a search and found that Sphinx can render .ipynb files as HTML pages with the nbsphinx extension.

[daneschi]

Thank you for these comments.

• I have included the code in the examples using the literalinclude directive as suggested.
• That RCR example uses annealing, so it is normal for the loss to increase going from t=0 to t=1, instead of being reduced monotonically like for the other examples. I have added a comment so this is more clear.
• I tried the nbsphinx extension to render notebooks, but I get a large number of errors and warning, like these below:

WARNING: Block quote ends without a blank line; unexpected unindent.
ERROR: Unexpected indentation.

I'm trying to fix these problem. Have you seen them before?

[robmoss]

Hi @daneschi

That RCR example uses annealing, so it is normal for the loss to increase going from t=0 to t=1, instead of being reduced monotonically like for the other examples. I have added a comment so this is more clear.

Thanks very much for the clarification, I was thoroughly confused!

I tried the nbsphinx extension to render notebooks, but I get a large number of errors and warning [...] Have you seen them before?

I haven't used the nbsphinx extension myself, but I've just given it a try and found a few things:

1. I needed to install nbsphinx (it's not listed in docs/requirements.txt).
   • I also installed ipython (also not listed) to avoid some warnings about syntax highlighting.
   • I also removed the numpy version in docs/requirements.txt so that it could install a newer version — otherwise it would try to build numpy from source when using Python 3.10.
2. The nbsphinx docs say to add the file names of your notebooks (without the .ipynb extension) to the toctree directive, rather than creating a .rst file and using the include directive.
   • I suspect this was the cause of the "unexpected indentation" error message.
3. When I added the notebook files to the toctree in docs/content/num_examples.rst, sphinx complained that it couldn't find the referenced images (which are in ./tutorial).
   • I resolved this by moving the tutorial directory to docs/content/tutorial.
   • The notebook links in README.md would need to be updated.

The toctree in docs/contents/num_examples.rst now looks like this:

.. toctree::
   :maxdepth: 2

   tutorial/tutorial_linfa_2d
   tutorial/tutorial_linfa_3d
   trivial
   ...

After these steps, I was able to build the documentation and view the notebooks!

There is still one warning:

MissingIDFieldWarning: Cell is missing an id field, this will become a hard error in future nbformat versions. You may want to use `normalize()` on your notebooks before validations (available since nbformat 5.1.4). Previous versions of nbformat are fixing this issue transparently, and will stop doing so in the future.
  validate(nb)

The good news is that this can be resolved relatively easily.

[daneschi]

Thank you @robmoss! I have included the tutorials in the documentation and updated it on readthedocs.

[robmoss]

The tutorials look great!