ENH add ridge regression tutorial

Author: TomDLT

doc/Makefile

@@ -39,10 +39,11 @@ merge-notebooks:
 	python merge_notebooks.py \
 		$(NBDIR)/00_setup_colab.ipynb \
 		$(NBDIR)/01_plot_explainable_variance.ipynb \
-		$(NBDIR)/02_plot_wordnet_model.ipynb \
-		$(NBDIR)/03_plot_hemodynamic_response.ipynb \
-		$(NBDIR)/04_plot_motion_energy_model.ipynb \
-		$(NBDIR)/05_plot_banded_ridge_model.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)/merged_for_colab.ipynb
 	echo "Saved in $(NBDIR)/merged_for_colab.ipynb"
 

doc/index.rst

@@ -15,42 +15,38 @@ To explore these tutorials, one can:
 
 - read the rendered examples in the tutorials
   `gallery of examples <_auto_examples/index.html>`_ (recommended)
-- run the Python scripts located in the GitHub repository (`tutorials <https://github.com/gallantlab/voxelwise_tutorials/tree/main/tutorials>`_ directory)
-- run the Jupyter notebooks located in the GitHub repository 
-  (`tutorials/notebooks
+- run the Python scripts (`tutorials <https://github.com/gallantlab/voxelwise_tutorials/tree/main/tutorials>`_ directory)
+- run the Jupyter notebooks (`tutorials/notebooks
   <https://github.com/gallantlab/voxelwise_tutorials/tree/main/tutorials/notebooks>`_
   directory)
 - run the merged notebook in
-  `Colab <https://colab.research.google.com/github/gallantlab/voxelwise_tutorials/blob/main/tutorials/notebooks/movies/merged_for_colab.ipynb>`_.
+  `Google Colab <https://colab.research.google.com/github/gallantlab/voxelwise_tutorials/blob/main/tutorials/notebooks/movies/merged_for_colab.ipynb>`_
 
-The tutorials are best explored in order, starting with the "Movies" tutorial.
+The tutorials are best explored in order, starting with the `Movies tutorial
+<_auto_examples/index.html>`_.
 
 The project is available on GitHub at `gallantlab/voxelwise_tutorials
-<https://github.com/gallantlab/voxelwise_tutorials>`_. On top of the tutorials,
-the GitHub repository contains a Python package called ``voxelwise_tutorials``,
-which contains useful functions to download the data sets, load the files,
-process the data, and visualize the results. Install instructions are available
-`here <voxelwise_package.html>`_. Then, run either the Python scripts or the
-Jupyter notebooks located in the "tutorials" directory.
-
-Tutorials
----------
+<https://github.com/gallantlab/voxelwise_tutorials>`_. On top of the tutorials
+scripts, the GitHub repository contains a Python package called
+``voxelwise_tutorials``, which contains useful functions to download the data
+sets, load the files, process the data, and visualize the results. Install
+instructions are available `here <voxelwise_package.html>`_.
+
+Navigation
+----------
 .. toctree::
    :includehidden:
-   :maxdepth: 2
+   :maxdepth: 1
 
 
    _auto_examples/index
 
-Documentation
--------------
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
-   voxelwise_modeling
+   voxelwise_package
 
 .. toctree::
-   :maxdepth: 2
-
-   voxelwise_package
+   :maxdepth: 1
 
+   voxelwise_modeling

doc/voxelwise_modeling.rst

@@ -1,13 +1,15 @@
-The voxelwise modeling framework
-================================
+References
+==========
 
-VM Framework
-------------
+Voxelwise modeling framework
+----------------------------
 
 Voxelwise modeling (VM) is a framework to perform functional magnetic resonance
-imaging (fMRI) data analysis.
-Over the years, VM has led to many high profile publications 
-[1]_ [2]_ [3]_ [4]_  [5]_ [6]_ [7]_ [8]_ [9]_ [10]_ [11]_.
+imaging (fMRI) data analysis. Over the years, VM has led to many high profile
+publications :ref:`[1]<kay2008>` :ref:`[2]<nas2009>` :ref:`[3]<nis2011>`
+:ref:`[4]<hut2012>` :ref:`[5]<cuk2013>` :ref:`[6]<cuk2013b>`
+:ref:`[7]<sta2013>` :ref:`[8]<hut2016>` :ref:`[9]<deh2017>`
+:ref:`[10]<les2019>` :ref:`[11]<den2019>` :ref:`[12]<nun2019>`.
 
 [...]
 
@@ -18,86 +20,129 @@ VM provides multiple critical improvements over other approaches to fMRI data
 analysis:
 
 #.
-    Most methods for analyzing fMRI data rely on simple contrasts
-    between a small number of conditions. In contrast, VM can efficiently analyze
-    many different stimulus and task features simultaneously. This framework
-    enables the analysis of complex naturalistic stimuli and tasks which contain
-    a large number of features; for example, VM has been used with naturalistic images
-    [1]_ [2]_, movies [3]_, and stories [8]_.
+    Most methods for analyzing fMRI data rely on simple contrasts between a
+    small number of conditions. In contrast, VM can efficiently analyze many
+    different stimulus and task features simultaneously. This framework enables
+    the analysis of complex naturalistic stimuli and tasks which contain a
+    large number of features; for example, VM has been used with naturalistic
+    images :ref:`[1]<kay2008>` :ref:`[2]<nas2009>`, movies :ref:`[3]<nis2011>`,
+    and stories :ref:`[8]<hut2016>`.
 
 #.
     Unlike the traditional null hypothesis testing framework, VM is not prone
-    to overfitting and type I error and generalizes to new subjects and stimuli .
-    VM is a predictive modeling framework that
-    evaluates model performance on a separate test data set not used during fitting.
+    to overfitting and type I error and generalizes to new subjects and stimuli
+    . VM is a predictive modeling framework that evaluates model performance on
+    a separate test data set not used during fitting.
 
 #.
-    VM performs an analysis in each subject’s native brain space instead of lossily
-    transforming subjects into a common group space. This allows VM to produce
-    results with maximal spatial resolution. Each subject provides their own fit
-    and test data, so every subject provides a complete replication of all
-    hypothesis tests.
+    VM performs an analysis in each subject's native brain space instead of
+    lossily transforming subjects into a common group space. This allows VM to
+    produce results with maximal spatial resolution. Each subject provides
+    their own fit and test data, so every subject provides a complete
+    replication of all hypothesis tests.
 
 #.
-    VM produces high-dimensional functional maps rather than simple contrast 
-    maps or correlation matrices. These maps reflect the
-    selectivity of each voxel to thousands of stimulus and task features spread
-    across dozens of feature spaces. These functional maps are much more
-    detailed than those produced using statistical parametric mapping (SPM),
-    multivariate pattern analysis (MVPA), or representational similarity
-    analysis (RSA).
+    VM produces high-dimensional functional maps rather than simple contrast
+    maps or correlation matrices. These maps reflect the selectivity of each
+    voxel to thousands of stimulus and task features spread across dozens of
+    feature spaces. These functional maps are much more detailed than those
+    produced using statistical parametric mapping (SPM), multivariate pattern
+    analysis (MVPA), or representational similarity analysis (RSA).
 
 #.
     VM recovers stable and interpretable functional parcellations, which
-    respect individual variability in anatomy [8]_. 
+    respect individual variability in anatomy :ref:`[8]<hut2016>`. 
 
 
 References
 ----------
 
-.. [1] Kay, K. N., Naselaris, T., Prenger, R. J., & Gallant, J. L. (2008).
+.. _kay2008:
+
+[1] Kay, K. N., Naselaris, T., Prenger, R. J., & Gallant, J. L. (2008).
     Identifying natural images from human brain activity.
     Nature, 452(7185), 352-355.
 
-.. [2] Naselaris, T., Prenger, R. J., Kay, K. N., Oliver, M., & Gallant, J. L. (2009).
+.. _nas2009:
+
+[2] Naselaris, T., Prenger, R. J., Kay, K. N., Oliver, M., & Gallant, J. L. (2009).
     Bayesian reconstruction of natural images from human brain activity.
     Neuron, 63(6), 902-915.
 
-.. [3] Nishimoto, S., Vu, A. T., Naselaris, T., Benjamini, Y., Yu, B., & Gallant, J. L. (2011).
+.. _nis2011:
+
+[3] Nishimoto, S., Vu, A. T., Naselaris, T., Benjamini, Y., Yu, B., & Gallant, J. L. (2011).
     Reconstructing visual experiences from brain activity evoked by natural movies.
     Current Biology, 21(19), 1641-1646.
 
-.. [4] Huth, A. G., Nishimoto, S., Vu, A. T., & Gallant, J. L. (2012).
+.. _hut2012:
+
+[4] Huth, A. G., Nishimoto, S., Vu, A. T., & Gallant, J. L. (2012).
     A continuous semantic space describes the representation of thousands of
     object and action categories across the human brain.
     Neuron, 76(6), 1210-1224.
 
-.. [5] Çukur, T., Nishimoto, S., Huth, A. G., & Gallant, J. L. (2013).
+.. _cuk2013:
+
+[5] Çukur, T., Nishimoto, S., Huth, A. G., & Gallant, J. L. (2013).
     Attention during natural vision warps semantic representation across the human brain.
     Nature neuroscience, 16(6), 763-770.
 
-.. [6] Çukur, T., Huth, A. G., Nishimoto, S., & Gallant, J. L. (2013).
+.. _cuk2013b:
+
+[6] Çukur, T., Huth, A. G., Nishimoto, S., & Gallant, J. L. (2013).
     Functional subdomains within human FFA.
     Journal of Neuroscience, 33(42), 16748-16766.
 
-.. [7] Stansbury, D. E., Naselaris, T., & Gallant, J. L. (2013).
+.. _sta2013:
+
+[7] Stansbury, D. E., Naselaris, T., & Gallant, J. L. (2013).
     Natural scene statistics account for the representation of scene categories
     in human visual cortex.
     Neuron, 79(5), 1025-1034
 
-.. [8] Huth, A. G., De Heer, W. A., Griffiths, T. L., Theunissen, F. E., & Gallant, J. L. (2016).
+.. _hut2016:
+
+[8] Huth, A. G., De Heer, W. A., Griffiths, T. L., Theunissen, F. E., & Gallant, J. L. (2016).
     Natural speech reveals the semantic maps that tile human cerebral cortex.
     Nature, 532(7600), 453-458.
 
-.. [9] de Heer, W. A., Huth, A. G., Griffiths, T. L., Gallant, J. L., & Theunissen, F. E. (2017).
+.. _deh2017:
+
+[9] de Heer, W. A., Huth, A. G., Griffiths, T. L., Gallant, J. L., & Theunissen, F. E. (2017).
     The hierarchical cortical organization of human speech processing.
     Journal of Neuroscience, 37(27), 6539-6557.
 
-.. [10] Lescroart, M. D., & Gallant, J. L. (2019).
+.. _les2019:
+
+[10] Lescroart, M. D., & Gallant, J. L. (2019).
     Human scene-selective areas represent 3D configurations of surfaces.
     Neuron, 101(1), 178-192.
 
-.. [11] Deniz, F., Nunez-Elizalde, A. O., Huth, A. G., & Gallant, J. L. (2019).
+.. _den2019:
+
+[11] Deniz, F., Nunez-Elizalde, A. O., Huth, A. G., & Gallant, J. L. (2019).
     The representation of semantic information across human cerebral cortex
     during listening versus reading is invariant to stimulus modality.
-    Journal of Neuroscience, 39(39), 7722-7736.
+    Journal of Neuroscience, 39(39), 7722-7736.
+
+.. _nun2019:
+
+[12] Nunez-Elizalde, A. O., Huth, A. G., & Gallant, J. L. (2019).
+    Voxelwise encoding models with non-spherical multivariate normal priors.
+    Neuroimage, 197, 482-492.
+
+Datasets
+--------
+.. _nis2011data:
+
+[3b] Nishimoto, S., Vu, A. T., Naselaris, T., Benjamini, Y., Yu,
+    B., & Gallant, J. L. (2014): Gallant Lab Natural Movie 4T fMRI Data.
+    CRCNS.org. http://dx.doi.org/10.6080/K00Z715X
+
+.. _hut2012data:
+
+[4b] Huth, A. G., Nishimoto, S., Vu, A. T., & Gallant, J. L. (2020):
+    Gallant Lab Natural Movie 3T fMRI Data. CRCNS.org.
+    http://dx.doi.org/10.6080/TBD
+