DOC update README

Author: TomDLT

README.rst

@@ -1,31 +1,44 @@
-.. raw:: html
+============================
+Voxelwise modeling tutorials
+============================
 
-   <h1>Voxelwise modeling tutorials</h1>
+|Github| |Python|
 
+Welcome to the voxelwise modeling tutorial from the
+`Gallantlab <https://gallantlab.org>`_.
 
-|Github| |Python|
+Tutorials
+=========
 
-.. raw:: html
+This repository contains tutorials describing how to use the voxelwise modeling
+framework. Voxelwise modeling is a framework to perform functional magnetic
+resonance imaging (fMRI) data analysis, fitting encoding models at the voxel
+level.
 
-   <h2>Tutorials</h2>
+To explore these tutorials, one can:
 
+- read the rendered examples in the tutorials
+  `website <https://gallantlab.github.io/voxelwise_tutorials/>`_ (recommended)
+- run the Python scripts located in the `tutorials <tutorials>`_ directory
+- run the ``jupyter`` notebooks located in the
+  `tutorials/notebooks <tutorials/notebooks>`_ directory
 
-This repository contains some tutorials describing how to perform voxelwise
-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/voxelwise_tutorials/>`_.
+To run the tutorials yourself, first download this repository, and install the
+dependencies (see below). Then, run either the Python scripts or the
+``jupyter`` notebooks located in the "tutorials" directory. The tutorials are
+best explored in order, starting with the "Movies 3T tutorial".
 
-The ``voxelwise_tutorials`` package
-=========================
+Helper Python package
+=====================
 
-On top of tutorials, this repository also contains a small Python package
-called ``voxelwise_tutorials``, which contains useful fonctions to download the
+To run the tutorials, this repository contains a small Python package
+called ``voxelwise_tutorials``, with useful fonctions to download the
 data sets, load the files, process the data, and visualize the results.
 
 Installation
 ------------
 
-To install this package, run
+To install the ``voxelwise_tutorials`` package, run
 
 .. code-block:: bash
 
@@ -44,24 +57,25 @@ Developers can also install the package in editable mode via:
 Requirements
 ------------
 
-The Python package ``voxelwise_tutorials`` requires the following dependencies:
+The package ``voxelwise_tutorials`` has the following dependencies:
 
 - `numpy <https://github.com/numpy/numpy>`_
 - `scipy <https://github.com/scipy/scipy>`_
+- `h5py <https://github.com/h5py/h5py>`_
 - `scikit-learn <https://github.com/scikit-learn/scikit-learn>`_
 - `matplotlib <https://github.com/matplotlib/matplotlib>`_
 
-Each tutorial requires additional dependencies, as listed in their respective
+Each tutorial requires additional packages, as listed in their respective
 documentations, such as:
 
-- `h5py <https://github.com/h5py/h5py>`_
+- `voxelwise_tutorials <https://github.com/gallantlab/voxelwise_tutorials>`_
+  (this repository)
 - `himalaya <https://github.com/gallantlab/himalaya>`_
 - `pymoten <https://github.com/gallantlab/pymoten>`_
-- `voxelwise_tutorials <https://github.com/gallantlab/voxelwise_tutorials>`_
-   (this repository)
+- `pycortex <https://github.com/gallantlab/pycortex>`_
 
 
-.. |Github| image:: https://img.shields.io/badge/github-tutorials-blue
+.. |Github| image:: https://img.shields.io/badge/github-voxelwise_tutorials-blue
    :target: https://github.com/gallantlab/voxelwise_tutorials
 
 .. |Python| image:: https://img.shields.io/badge/python-3.7%2B-blue

doc/index.rst

@@ -2,7 +2,7 @@ Voxelwise modeling tutorials
 ============================
 
 
-Welcome to the voxelwise modeling tutorial from the
+Welcome to the voxelwise modeling tutorials from the
 `Gallantlab <https://gallantlab.org>`_.
 
 Getting started
@@ -11,18 +11,19 @@ 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".
+The tutorials consist of Python scripts, which are rendered in a `gallery of
+examples <auto_examples/index.html>`_. Each Python script is also available as a
+``Jupyter`` notebook (non-rendered). 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
+To run the tutorials yourself, we recommend to download the project 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``,
+the GitHub repository contains a Python package called ``voxelwise_tutorials``,
 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>`_.
+`here <voxelwise_package.html>`_. Then, run either the Python scripts or the
+``jupyter`` notebooks located in the "tutorials" directory.
 
 Tutorials
 ---------

doc/voxelwise_package.rst

@@ -1 +1,55 @@
-.. include:: ../README.rst
+Helper Python package
+=====================
+
+|Github| |Python|
+
+To run the tutorials, the `gallantlab/voxelwise_tutorials
+<https://github.com/gallantlab/voxelwise_tutorials>`_ repository contains a
+Python package called ``voxelwise_tutorials``, with useful fonctions to
+download the data sets, load the files, process the data, and visualize the
+results.
+
+Installation
+------------
+
+To install the ``voxelwise_tutorials`` package, run
+
+.. code-block:: bash
+
+   git clone https://github.com/gallantlab/voxelwise_tutorials.git
+   cd voxelwise_tutorials
+   pip install .
+
+
+Developers can also install the package in editable mode via:
+
+.. code-block:: bash
+
+   pip install --editable .
+
+
+Requirements
+------------
+
+The package ``voxelwise_tutorials`` has the following dependencies:
+
+- `numpy <https://github.com/numpy/numpy>`_
+- `scipy <https://github.com/scipy/scipy>`_
+- `h5py <https://github.com/h5py/h5py>`_
+- `scikit-learn <https://github.com/scikit-learn/scikit-learn>`_
+- `matplotlib <https://github.com/matplotlib/matplotlib>`_
+
+Each tutorial requires additional packages, as listed in their respective
+documentations, such as:
+
+- `voxelwise_tutorials <https://github.com/gallantlab/voxelwise_tutorials>`_
+- `himalaya <https://github.com/gallantlab/himalaya>`_
+- `pymoten <https://github.com/gallantlab/pymoten>`_
+- `pycortex <https://github.com/gallantlab/pycortex>`_
+
+
+.. |Github| image:: https://img.shields.io/badge/github-voxelwise_tutorials-blue
+   :target: https://github.com/gallantlab/voxelwise_tutorials
+
+.. |Python| image:: https://img.shields.io/badge/python-3.7%2B-blue
+   :target: https://www.python.org/downloads/release/python-370

tutorials/movies_3T/README.rst

@@ -23,15 +23,17 @@ This tutorial implements different voxelwise models:
 **Requirements:**
 This tutorial requires the following Python packages:
 
+- voxelwise_tutorials  (this repository)
 - numpy
 - scipy
 - h5py
 - scikit-learn
-- voxelwise_tutorials  (this repository)
+- jupyter
+- matplotlib
 - himalaya
+- pycortex  (optional, for using 3D brain viewers)
 - pymoten  (optional, for extracting motion energy)
-- cupy/pytorch (optional, to use GPU in himalaya)
-
+- cupy/pytorch (optional, to use a GPU backend in himalaya)
 
 **References:**
 

tutorials/movies_4T/README.rst

@@ -26,14 +26,15 @@ publication [5]_, and the CRCNS data set [6]_.
 **Requirements:**
 This tutorial requires the following Python packages:
 
+- voxelwise_tutorials  (this repository)
 - numpy
 - scipy
 - h5py
 - scikit-learn
-- voxelwise_tutorials  (this repository)
+- matplotlib
 - himalaya
-- pymoten  (optional, for extracting motion energy)
-- cupy/pytorch (optional, to use GPU in himalaya)
+- pymoten
+- cupy/pytorch (optional, to use a GPU backend in himalaya)
 
 **References:**