Merge pull request #41 from mvdoc/mnt/order

MNT Reorder notebooks and improve naming

Author: mvdoc

README.rst

@@ -1,43 +1,45 @@
-============================
-Voxelwise modeling tutorials
-============================
+==================================
+Voxelwise Encoding Model tutorials
+==================================
 
 |Github| |Python| |License| |Build| |Build Tutorials| |Downloads|
 
-Welcome to the voxelwise modeling tutorial from the
-`GallantLab <https://gallantlab.org>`_.
+Welcome to the Voxelwise Encoding Model tutorials, brought to you by the
+`Gallant Lab <https://gallantlab.org>`_.
 
 Paper
 =====
 
 If you use these tutorials for your work, consider citing the corresponding paper:
 
-Dupré La Tour, T., Visconti di Oleggio Castello, M., & Gallant, J. L. (2024). The Voxelwise Modeling framework: a tutorial introduction to fitting encoding models to fMRI data. https://doi.org/10.31234/osf.io/t975e
+   Dupré La Tour, T., Visconti di Oleggio Castello, M., & Gallant, J. L. (2024). The Voxelwise Encoding Model framework: a tutorial introduction to fitting encoding models to fMRI data. https://doi.org/10.31234/osf.io/t975e
 
 You can find a copy of the paper `here <paper/voxelwise_tutorials_paper.pdf>`_.
 
 Tutorials
 =========
 
-This repository contains tutorials describing how to use the voxelwise modeling
-framework. `Voxelwise modeling
-<https://gallantlab.github.io/voxelwise_tutorials/voxelwise_modeling.html>`_ is
+This repository contains tutorials describing how to use the Voxelwise Encoding Model 
+(VEM) framework. `VEM
+<https://gallantlab.github.io/voxelwise_tutorials/pages/voxelwise_modeling.html>`_ is
 a framework to perform functional magnetic resonance imaging (fMRI) data
 analysis, fitting encoding models at the voxel level.
 
 To explore these tutorials, one can:
 
-- read the rendered examples in the tutorials
-  `website <https://gallantlab.github.io/voxelwise_tutorials/>`_ (recommended)
-- run the merged notebook in
+- Read the rendered examples in the tutorials
+  `website <https://gallantlab.github.io/voxelwise_tutorials/>`_ (recommended).
+- Run the merged notebook in
   `Colab <https://colab.research.google.com/github/gallantlab/voxelwise_tutorials/blob/main/tutorials/notebooks/shortclips/merged_for_colab.ipynb>`_.
-- run the Jupyter notebooks (`tutorials/notebooks <tutorials/notebooks>`_ directory) locally
+- Run the Jupyter notebooks (`tutorials/notebooks <tutorials/notebooks>`_ directory) locally.
+
+The tutorials are best explored in order, starting with the "shortclips"
+tutorial. The "vim2" tutorial is optional and redundant with the "shortclips" one.
 
-The tutorials are best explored in order, starting with the "Shortclips"
-tutorial.
 
 Dockerfiles
 ===========
+
 This repository contains Dockerfiles to run the tutorials locally. Please see the
 instructions in the `docker <docker>`_ directory.
 

tutorials/Makefile

@@ -22,22 +22,22 @@ NBDIR = notebooks/shortclips
 
 merge-notebooks:
 	python merge_notebooks.py \
-		$(NBDIR)/00_setup_colab.ipynb \
-		$(NBDIR)/01_plot_explainable_variance.ipynb \
-		$(NBDIR)/02_plot_ridge_regression.ipynb \
-		$(NBDIR)/03_plot_wordnet_model.ipynb \
-		$(NBDIR)/04_plot_hemodynamic_response.ipynb \
-		$(NBDIR)/05_plot_motion_energy_model.ipynb \
-		$(NBDIR)/06_plot_banded_ridge_model.ipynb \
+		$(NBDIR)/01_setup_colab.ipynb \
+		$(NBDIR)/03_compute_explainable_variance.ipynb \
+		$(NBDIR)/04_understand_ridge_regression.ipynb \
+		$(NBDIR)/05_fit_wordnet_model.ipynb \
+		$(NBDIR)/06_visualize_hemodynamic_response.ipynb \
+		$(NBDIR)/08_fit_motion_energy_model.ipynb \
+		$(NBDIR)/09_fit_banded_ridge_model.ipynb \
 		> $(NBDIR)/merged_for_colab.ipynb
 	echo "Saved in $(NBDIR)/merged_for_colab.ipynb"
 
 	python merge_notebooks.py \
-		$(NBDIR)/00_setup_colab.ipynb \
-		$(NBDIR)/01_plot_explainable_variance.ipynb \
-		$(NBDIR)/03_plot_wordnet_model.ipynb \
-		$(NBDIR)/05_plot_motion_energy_model.ipynb \
-		$(NBDIR)/06_plot_banded_ridge_model.ipynb \
+		$(NBDIR)/01_setup_colab.ipynb \
+		$(NBDIR)/03_compute_explainable_variance.ipynb \
+		$(NBDIR)/05_fit_wordnet_model.ipynb \
+		$(NBDIR)/08_fit_motion_energy_model.ipynb \
+		$(NBDIR)/09_fit_banded_ridge_model.ipynb \
 		> $(NBDIR)/merged_for_colab_model_fitting.ipynb
 	echo "Saved in $(NBDIR)/merged_for_colab_model_fitting.ipynb"
 

tutorials/_toc.yml

@@ -9,14 +9,14 @@ sections:
 - file: notebooks/shortclips/README
   title: Shortclips tutorial
   sections:
-  - file: notebooks/shortclips/00_download_shortclips
-  - file: notebooks/shortclips/01_plot_explainable_variance
-  - file: notebooks/shortclips/02_plot_ridge_regression
-  - file: notebooks/shortclips/03_plot_wordnet_model
-  - file: notebooks/shortclips/04_plot_hemodynamic_response
-  - file: notebooks/shortclips/05_plot_motion_energy_model
-  - file: notebooks/shortclips/06_plot_banded_ridge_model
+  - file: notebooks/shortclips/02_download_shortclips
+  - file: notebooks/shortclips/03_compute_explainable_variance
+  - file: notebooks/shortclips/04_understand_ridge_regression
+  - file: notebooks/shortclips/05_fit_wordnet_model
+  - file: notebooks/shortclips/06_visualize_hemodynamic_response
   - file: notebooks/shortclips/07_extract_motion_energy
+  - file: notebooks/shortclips/08_fit_motion_energy_model
+  - file: notebooks/shortclips/09_fit_banded_ridge_model
 - file: notebooks/vim2/README
   title: Vim-2 tutorial (optional)
   sections:

…otebooks/shortclips/00_setup_colab.ipynb …otebooks/shortclips/01_setup_colab.ipynbtutorials/notebooks/shortclips/00_setup_colab.ipynb renamed to tutorials/notebooks/shortclips/01_setup_colab.ipynb tutorials/notebooks/shortclips/00_setup_colab.ipynb renamed to tutorials/notebooks/shortclips/01_setup_colab.ipynb

@@ -8,8 +8,12 @@
         "# Setup Google Colab\n",
         "\n",
         "In this script, we setup a Google Colab environment. This script will only work\n",
-        "when run from [Google Colab](https://colab.research.google.com/)). You can\n",
-        "skip it if you run the tutorials on your machine.\n"
+        "when run from [Google Colab](https://colab.research.google.com/). You can\n",
+        "skip it if you run the tutorials on your machine.\n",
+        "\n",
+        "> **Note:** This script will install all the required dependencies and download the data.\n",
+        "> It will take around 10 minutes to run, but you need to run it only once in your Colab session.\n",
+        "> If your Colab session is disconnected, you will need to run this script again."
       ]
     },
     {
@@ -22,15 +26,15 @@
         "In Google Colab you can request access to a GPU by changing the runtime type.\n",
         "To do so, click the following menu options in Google Colab:\n",
         "\n",
-        "(Menu) \"Runtime\" -> \"Change runtime type\" -> \"Hardware accelerator\" -> \"GPU\".\n",
+        "> (Menu) \"Runtime\" -> \"Change runtime type\" -> \"Hardware accelerator\" -> \"GPU\".\n",
         "\n"
       ]
     },
     {
       "cell_type": "markdown",
       "metadata": {},
       "source": [
-        "## Download the data and install all required dependencies\n",
+        "## Install all required dependencies and download the data\n",
         "\n",
         "Uncomment and run the following cell to download the required packages.\n",
         "\n"

…/shortclips/00_download_shortclips.ipynb …/shortclips/02_download_shortclips.ipynbtutorials/notebooks/shortclips/00_download_shortclips.ipynb renamed to tutorials/notebooks/shortclips/02_download_shortclips.ipynb tutorials/notebooks/shortclips/00_download_shortclips.ipynb renamed to tutorials/notebooks/shortclips/02_download_shortclips.ipynb

@@ -51,9 +51,8 @@
         "download more subjects.\n",
         "\n",
         "We also skip the stimuli files, since the dataset provides two preprocessed\n",
-        "feature spaces to perform voxelwise modeling without requiring the original\n",
-        "stimuli.\n",
-        "\n"
+        "feature spaces to fit voxelwise encoding models without requiring the original\n",
+        "stimuli."
       ]
     },
     {

…clips/01_plot_explainable_variance.ipynb …ps/03_compute_explainable_variance.ipynbtutorials/notebooks/shortclips/01_plot_explainable_variance.ipynb renamed to tutorials/notebooks/shortclips/03_compute_explainable_variance.ipynb tutorials/notebooks/shortclips/01_plot_explainable_variance.ipynb renamed to tutorials/notebooks/shortclips/03_compute_explainable_variance.ipynb

@@ -15,9 +15,10 @@
         "stimulus-dependent signal and noise. If we present the same stimulus multiple\n",
         "times and we record brain activity for each repetition, the stimulus-dependent\n",
         "signal will be the same across repetitions while the noise will vary across\n",
-        "repetitions. In voxelwise modeling, the features used to model brain activity\n",
-        "are the same for each repetition of the stimulus. Thus, encoding models will\n",
-        "predict only the repeatable stimulus-dependent signal.\n",
+        "repetitions. In the Voxelwise Encoding Model framework, \n",
+        "the features used to model brain activity are the same for each repetition of the \n",
+        "stimulus. Thus, encoding models will predict only the repeatable stimulus-dependent \n",
+        "signal.\n",
         "\n",
         "The stimulus-dependent signal can be estimated by taking the mean of brain\n",
         "responses over repeats of the same stimulus or experiment. The variance of the\n",

…hortclips/02_plot_ridge_regression.ipynb …ips/04_understand_ridge_regression.ipynbtutorials/notebooks/shortclips/02_plot_ridge_regression.ipynb renamed to tutorials/notebooks/shortclips/04_understand_ridge_regression.ipynb tutorials/notebooks/shortclips/02_plot_ridge_regression.ipynb renamed to tutorials/notebooks/shortclips/04_understand_ridge_regression.ipynb

@@ -15,7 +15,7 @@
         "Linear regression is a method to model the relation between some input\n",
         "variables $X \\in \\mathbb{R}^{(n \\times p)}$ (the features) and an output\n",
         "variable $y \\in \\mathbb{R}^{n}$ (the target). Specifically, linear\n",
-        "regression uses a vector of coefficient $w \\in \\mathbb{R}^{p}$` to\n",
+        "regression uses a vector of coefficient $w \\in \\mathbb{R}^{p}$ to\n",
         "predict the output\n",
         "\n",
         "\\begin{align}\\hat{y} = Xw\\end{align}\n",
@@ -30,15 +30,6 @@
         "least squares* (OLS).\n"
       ]
     },
-    {
-      "cell_type": "code",
-      "execution_count": null,
-      "metadata": {
-        "collapsed": false
-      },
-      "outputs": [],
-      "source": []
-    },
     {
       "cell_type": "markdown",
       "metadata": {},