Merge pull request #208 from LabForComputationalVision/cleanup_tutorials

Cleanup tutorials
plenoptic-org · May 18, 2023 · 7f43f20 · 7f43f20
2 parents 7cb62b6 + 4583c0e
commit 7f43f20
Show file tree

Hide file tree

Showing 40 changed files with 1,544 additions and 1,026 deletions.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -148,7 +148,8 @@ jobs:
     - uses: actions/checkout@v3
     - name: Check for file
       shell: bash
-      run: if [[ -z "$(grep ${{ matrix.notebook }} docs/tutorials/*nblink)" ]] ; then
+      # there are two levels that the notebooks can be in
+      run: if [[ -z "$(grep ${{ matrix.notebook }} docs/tutorials/*nblink)" && -z "$(grep ${{ matrix.notebook }} docs/tutorials/*/*nblink)" ]] ; then
         exit 1; fi
   no_extra_nblinks:
     runs-on: ubuntu-latest
@@ -159,6 +160,7 @@ jobs:
       shell: bash
       run: |
         n_nblink=0; for file in docs/tutorials/*nblink; do let "n_nblink+=1"; done;
+        for file in docs/tutorials/*/*nblink; do let "n_nblink+=1"; done;
         n_ipynb=0; for file in examples/*ipynb; do let "n_ipynb+=1"; done;
         if [[ $n_nblink != $n_ipynb ]]; then exit 1; fi;
 

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -416,9 +416,9 @@ make html
 
 We build tutorials as Jupyter notebooks so that they can be launched in Binder
 and people can play with them on their local machine. In order to include them
-in the built docs, add a `nblink` file to the `docs/tutorials/` directory. We
-check for this during the tests, so you won't be able to merge your pull request
-into `main` unless you've done this!
+in the built docs, add a `nblink` file to the `docs/tutorials/` directory or one
+of its sub-directories. We check for this during the tests, so you won't be able
+to merge your pull request into `main` unless you've done this!
 
 This is a json file that should contain the path to the notebook, like so, for
 `docs/tutorials/my_awesome_tutorial.nblink`:
@@ -430,7 +430,9 @@ This is a json file that should contain the path to the notebook, like so, for
 ```
 
 note that you *cannot* have a trailing comma there, because json is very
-particular.
+particular. And note that the number of `../` you need will depend on whether
+the `nblink` file lives in `docs/tutorials/` or one of its sub-directories.
+
 If you have extra media (such as images) that are rendered in the notebook, you
 need to specify them as well, otherwise they won't render in the documentation:
 
@@ -444,8 +446,13 @@ need to specify them as well, otherwise they won't render in the documentation:
 
 note that `extra-media` must be a list, even with a single path.
 
-See the [nbsphinx-link](https://github.com/vidartf/nbsphinx-link)
-page for more details.
+See the [nbsphinx-link](https://github.com/vidartf/nbsphinx-link) page for more
+details.
+
+The location of the `.nblink` file (in `docs/tutorials`, `docs/tutorials/intro`,
+etc.) determines which of the sub-headings it appears under in the table of
+contents. View the `toctree` directives at the bottom of `index.rst` to see
+which subfolders corresponds to which
 
 *NOTE*: In order for the `toctree` formatting to work correctly, your notebook
 should have exactly one H1 title (i.e., line starting with a single `#`), but

diff --git a/README.md b/README.md
@@ -25,7 +25,7 @@ experiments for further investigation.
     for an in-depth introduction.
 -   If you understand the basics of synthesis and want to get started
     using `plenoptic` quickly, see the
-    [Quickstart](tutorials/00_quickstart.nblink) tutorial.
+    [Quickstart](examples/00_quickstart.ipynb) tutorial.
 
 ### Installation
 
@@ -60,18 +60,18 @@ with a random string, `matplotlib` will tell you the available choices.
 
 ![](docs/images/example_synth.svg)
 
--   [Metamers](tutorials/06_Metamer.nblink): given a model and a
+-   [Metamers](examples/06_Metamer.ipynb): given a model and a
     reference image, stochastically generate a new image whose model
     representation is identical to that of the reference image. This
     method investigates what image features the model disregards
     entirely.
--   [Eigendistortions](tutorials/02_Eigendistortions.nblink): given a
+-   [Eigendistortions](examples/02_Eigendistortions.ipynb): given a
     model and a reference image, compute the image perturbation that
     produces the smallest and largest changes in the model response
     space. This method investigates the image features the model
     considers the least and most important.
 -   [Maximal differentiation (MAD)
-    competition](tutorials/07_MAD_Competition.nblink): given two metrics
+    competition](examples/07_MAD_Competition.ipynb): given two metrics
     that measure distance between images and a reference image, generate
     pairs of images that optimally differentiate the models.
     Specifically, synthesize a pair of images that the first model says
@@ -80,7 +80,7 @@ with a random string, `matplotlib` will tell you the available choices.
     a second pair with the roles of the two models reversed. This method
     allows for efficient comparison of two metrics, highlighting the
     aspects in which their sensitivities differ.
--   [Geodesics](tutorials/05_Geodesics.nblink): given a model and two
+-   [Geodesics](examples/05_Geodesics.ipynb): given a model and two
     images, synthesize a sequence of images that lie on the shortest
     ("geodesic") path in the model's representation space. This
     method investigates how a model represents motion and what changes

diff --git a/docs/index.rst b/docs/index.rst
@@ -87,7 +87,8 @@ Synthesis methods
   that of the reference image. This method investigates what image features the
   model disregards entirely.
 
-  - Example papers: [Portilla2000]_, [Freeman2011]_
+  - Example papers: [Portilla2000]_, [Freeman2011]_, [Deza2019]_,
+    [Feather2019]_, [Wallis2019]_
 - `Eigendistortions <tutorials/02_Eigendistortions.nblink>`_: given a model and a
   reference image, compute the image perturbation that produces the smallest and
   largest changes in the model response space. This method investigates the
@@ -161,30 +162,46 @@ In all cases, please follow our `code of conduct
 <https://github.com/LabForComputationalVision/plenoptic/blob/main/CODE_OF_CONDUCT.md>`_.
 
 .. toctree::
-   :maxdepth: 1
-   :caption: Contents:
+   :titlesonly:
+   :caption: Basic concepts
+   :glob:
 
    install
    conceptual_intro
    models
-   synthesis
-   tips
-   reproducibility
-   api/modules
+   tutorials/*
 
 .. toctree::
    :titlesonly:
    :glob:
-   :caption: Tutorials and examples
+   :caption: Synthesis method introductions
 
-   tutorials/*
+   tutorials/intro/*
+
+.. toctree::
+   :titlesonly:
+   :glob:
+   :caption: Models and metrics
 
-Indices and tables
-==================
+   tutorials/models/*
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+.. toctree::
+   :titlesonly:
+   :glob:
+   :caption: Synthesis method examples
+
+   tutorials/applications/*
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+   :caption: Advanced usage
+
+   synthesis
+   tips
+   reproducibility
+   Modules <api/modules>
+   tutorials/advanced/*
 
 .. [Portilla2000] Portilla, J., & Simoncelli, E. P. (2000). A parametric texture
    model based on joint statistics of complex wavelet coefficients.
@@ -194,6 +211,15 @@ Indices and tables
 .. [Freeman2011] Freeman, J., & Simoncelli, E. P. (2011). Metamers of the
    ventral stream. Nature Neuroscience, 14(9), 1195–1201.
    http://www.cns.nyu.edu/pub/eero/freeman10-reprint.pdf
+.. [Deza2019] Deza, A., Jonnalagadda, A., & Eckstein, M. P. (2019). Towards
+   metamerism via foveated style transfer. In , International Conference on
+   Learning Representations.
+.. [Feather2019] Feather, J., Durango, A., Gonzalez, R., & McDermott, J. (2019).
+   Metamers of neural networks reveal divergence from human perceptual systems.
+   In NeurIPS (pp. 10078–10089).
+.. [Wallis2019] Wallis, T. S., Funke, C. M., Ecker, A. S., Gatys, L. A.,
+   Wichmann, F. A., & Bethge, M. (2019). Image content is more important than
+   bouma's law for scene metamers. eLife. http://dx.doi.org/10.7554/elife.42512
 .. [Berardino2017] Berardino, A., Laparra, V., J Ball\'e, & Simoncelli, E. P.
    (2017). Eigen-distortions of hierarchical representations. In I. Guyon, U.
    Luxburg, S. Bengio, H. Wallach, R. Fergus, S. Vishwanathan, & R. Garnett,

diff --git a/docs/synthesis.rst b/docs/synthesis.rst
@@ -1,7 +1,7 @@
 .. _synthesis-objects:
 
-Synthesis objects
-*****************
+Synthesis object design
+***********************
 
 The following describes how synthesis objects are structured. This is probably
 most useful if you are creating a new synthesis method that you would like to
@@ -17,7 +17,7 @@ testing), but we want to avoid forcing too much similarity.
 
 In the following description:
 
-* *must* connotes a requirement; any synthesis object not meeting this property
+** *must* connotes a requirement; any synthesis object not meeting this property
   will not be merged and is not considered "plenoptic-compliant".
 * *should* connotes a suggestion; a compelling reason is required if the
   property is not met.
@@ -108,7 +108,7 @@ for an example. If possible, this plot should be able to be animated to show
 progress over time. See
 :func:`plenoptic.synthesize.metamer.plot_synthesis_status` for an example.
 
-See our :doc:`/tutorials/Display` notebook for description and examples of the
+See our :doc:`/tutorials/advanced/Display` notebook for description and examples of the
 included plotting and display code.
 
 Optimized synthesis

diff --git a/docs/tutorials/01_Linear_approximation_of_nonlinear_model.nblink b/docs/tutorials/01_Linear_approximation_of_nonlinear_model.nblink
diff --git a/docs/tutorials/02_Eigendistortions.nblink b/docs/tutorials/02_Eigendistortions.nblink
diff --git a/docs/tutorials/03_Steerable_Pyramid.nblink b/docs/tutorials/03_Steerable_Pyramid.nblink
diff --git a/docs/tutorials/04_Perceptual_distance.nblink b/docs/tutorials/04_Perceptual_distance.nblink
diff --git a/docs/tutorials/05_Geodesics.nblink b/docs/tutorials/05_Geodesics.nblink
diff --git a/docs/tutorials/06_Metamer.nblink b/docs/tutorials/06_Metamer.nblink
diff --git a/docs/tutorials/07_MAD_Competition.nblink b/docs/tutorials/07_MAD_Competition.nblink
diff --git a/docs/tutorials/08_Simple_MAD.nblink b/docs/tutorials/08_Simple_MAD.nblink
diff --git a/docs/tutorials/09_Original_MAD.nblink b/docs/tutorials/09_Original_MAD.nblink
diff --git a/docs/tutorials/Demo_Eigendistortion.nblink b/docs/tutorials/Demo_Eigendistortion.nblink
diff --git a/docs/tutorials/Display.nblink b/docs/tutorials/Display.nblink
diff --git a/docs/tutorials/Metamer-Portilla-Simoncelli.nblink b/docs/tutorials/Metamer-Portilla-Simoncelli.nblink
diff --git a/docs/tutorials/Synthesis_extensions.nblink b/docs/tutorials/Synthesis_extensions.nblink
diff --git a/docs/tutorials/advanced/Display.nblink b/docs/tutorials/advanced/Display.nblink
@@ -0,0 +1,3 @@
+{
+	"path": "../../../examples/Display.ipynb"
+}
diff --git a/docs/tutorials/advanced/Synthesis_extensions.nblink b/docs/tutorials/advanced/Synthesis_extensions.nblink
@@ -0,0 +1,3 @@
+{
+	"path": "../../../examples/Synthesis_extensions.ipynb"
+}
diff --git a/docs/tutorials/applications/09_Original_MAD.nblink b/docs/tutorials/applications/09_Original_MAD.nblink
@@ -0,0 +1,3 @@
+{
+	"path": "../../../examples/09_Original_MAD.ipynb"
+}
diff --git a/docs/tutorials/applications/Demo_Eigendistortion.nblink b/docs/tutorials/applications/Demo_Eigendistortion.nblink
@@ -0,0 +1,4 @@
+{
+	"path": "../../../examples/Demo_Eigendistortion.ipynb",
+	"extra-media": ["../../../examples/assets/eigendistortions"]
+}
diff --git a/docs/tutorials/intro/02_Eigendistortions.nblink b/docs/tutorials/intro/02_Eigendistortions.nblink
@@ -0,0 +1,3 @@
+{
+	"path": "../../../examples/02_Eigendistortions.ipynb"
+}
diff --git a/docs/tutorials/intro/05_Geodesics.nblink b/docs/tutorials/intro/05_Geodesics.nblink
@@ -0,0 +1,3 @@
+{
+	"path": "../../../examples/05_Geodesics.ipynb"
+}
diff --git a/docs/tutorials/intro/06_Metamer.nblink b/docs/tutorials/intro/06_Metamer.nblink
@@ -0,0 +1,3 @@
+{
+	"path": "../../../examples/06_Metamer.ipynb"
+}
diff --git a/docs/tutorials/intro/07_Simple_MAD.nblink b/docs/tutorials/intro/07_Simple_MAD.nblink
@@ -0,0 +1,3 @@
+{
+	"path": "../../../examples/07_Simple_MAD.ipynb"
+}
diff --git a/docs/tutorials/intro/08_MAD_Competition.nblink b/docs/tutorials/intro/08_MAD_Competition.nblink
@@ -0,0 +1,3 @@
+{
+	"path": "../../../examples/08_MAD_Competition.ipynb"
+}
diff --git a/docs/tutorials/models/03_Steerable_Pyramid.nblink b/docs/tutorials/models/03_Steerable_Pyramid.nblink
@@ -0,0 +1,3 @@
+{
+	"path": "../../../examples/03_Steerable_Pyramid.ipynb"
+}
diff --git a/docs/tutorials/models/04_Perceptual_distance.nblink b/docs/tutorials/models/04_Perceptual_distance.nblink
@@ -0,0 +1,3 @@
+{
+	"path": "../../../examples/04_Perceptual_distance.ipynb"
+}
diff --git a/docs/tutorials/models/Metamer-Portilla-Simoncelli.nblink b/docs/tutorials/models/Metamer-Portilla-Simoncelli.nblink
@@ -0,0 +1,3 @@
+{
+	"path": "../../../examples/Metamer-Portilla-Simoncelli.ipynb"
+}
diff --git a/docs/tutorials/testing-new-synthesis.nblink b/docs/tutorials/testing-new-synthesis.nblink
diff --git a/examples/00_quickstart.ipynb b/examples/00_quickstart.ipynb
@@ -178,7 +178,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Okay, now we're ready to start with metamer synthesis. To initialize, we only need the model and the image (there are some additional options, but the defaults are fine in this case; see the [Metamer notebook](06_Metamer.nblink) if you're interested). In general, you'll probably need to play with these options to find a good solution. It's also probably a good idea, while getting started, to set `store_progress` to `True` (to store every iteration) or some `int` (to store every `int` iterations) so you can examine synthesis progress."
+    "Okay, now we're ready to start with metamer synthesis. To initialize, we only need the model and the image (there are some additional options, but the defaults are fine in this case; see the [Metamer notebook](intro/06_Metamer.nblink) if you're interested). In general, you'll probably need to play with these options to find a good solution. It's also probably a good idea, while getting started, to set `store_progress` to `True` (to store every iteration) or some `int` (to store every `int` iterations) so you can examine synthesis progress."
    ]
   },
   {