DOC add documentation on the VM framework

Author: TomDLT

README.rst

@@ -15,8 +15,8 @@ modeling, based for instance on visual imaging experiments.
 The best way to explore these tutorials is to go to the
 `website <https://gallantlab.github.io/tutorials/>`_.
 
-Voxelwise package
-=================
+The ``voxelwise`` package
+=========================
 
 On top of tutorials, this repository also contains a small Python package
 called ``voxelwise``, which contains useful fonctions to download the data sets,

doc/index.rst

@@ -4,6 +4,23 @@ Voxelwise modeling tutorials
 
 Welcome to the voxelwise modeling tutorial from the Gallant lab.
 
+Getting started
+---------------
+
+This website contains tutorials describing how to use the
+`voxelwise modeling framework <voxelwise_modeling.html>`_.
+
+The tutorials consist of Python scripts, which are rendered in a
+`gallery of examples <auto_examples/index.html>`_.
+The tutorials are best explored in order, starting with the
+"Movies 3T tutorial".
+
+To run the tutorials yourself, we recommend to download the project on
+github at `gallantlab/tutorials <https://github.com/gallantlab/tutorials>`_.
+On top of the tutorials, the github repository contains a Python package
+called ``voxelwise``, which contains useful fonctions to download the data
+sets, load the files, process the data, and visualize the results.
+Install instructions are available `here <voxelwise_package.html>`_.
 
 Tutorials
 ---------
@@ -14,10 +31,15 @@ Tutorials
 
    auto_examples/index
 
-Voxelwise package
------------------
+Documentation
+-------------
+.. toctree::
+   :maxdepth: 2
+
+   voxelwise_modeling
+
 .. toctree::
    :maxdepth: 2
 
-   voxelwise
+   voxelwise_package
 

doc/voxelwise_modeling.rst

@@ -0,0 +1,103 @@
+The voxelwise modeling framework
+================================
+
+VM 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]_.
+
+[...]
+
+Critical improvements
+---------------------
+
+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]_.
+
+#.
+    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.
+
+#.
+    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 recovers stable and interpretable functional parcellations, which
+    respect individual variability in anatomy [8]_. 
+
+
+References
+----------
+
+.. [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).
+    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).
+    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).
+    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).
+    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).
+    Functional subdomains within human FFA.
+    Journal of Neuroscience, 33(42), 16748-16766.
+
+.. [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).
+    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).
+    The hierarchical cortical organization of human speech processing.
+    Journal of Neuroscience, 37(27), 6539-6557.
+
+.. [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).
+    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.

doc/voxelwise.rst doc/voxelwise_package.rstdoc/voxelwise.rst renamed to doc/voxelwise_package.rst

@@ -254,6 +254,7 @@
        ylabel='motion energy model')
 plt.show()
 
+
 ###############################################################################
 # Interestingly, the well predicted voxels are different in the two models.
 # To further describe these differences, we can plot the performances on a

tutorials/movies_3T/03_plot_motion_energy_model.py

@@ -298,6 +298,7 @@ def plot_2d_flatmap_from_mapper(voxels_1, voxels_2, mapper_file, ax=None,
         cbar.imshow(cmap_image, aspect='equal',
                     extent=(vmin, vmax, vmin2, vmax2))
         cbar.set(xlabel=label_1, ylabel=label_2)
+        cbar.set(xticks=[vmin, vmax], yticks=[vmin2, vmax2])
 
     # plot additional layers if present
     with h5py.File(mapper_file, mode='r') as hf: