MNT add jupyter notebooks generated from the tutorials

Author: TomDLT

doc/Makefile

@@ -28,3 +28,6 @@ html-noplot:
 	@echo
 	@echo "Build finished (noplot). The HTML pages are in $(BUILDDIR)/html."
 
+notebooks:
+	rm -f ../tutorials/notebooks/*/*.ipynb
+	python create_notebooks.py

doc/README.md

@@ -13,5 +13,6 @@ sphinx_gallery
 ```bash
 cd doc
 make html
+make notebooks
 firefox _build/html/index.html
 ```

doc/create_notebooks.py

@@ -0,0 +1,13 @@
+
+if __name__ == "__main__":
+    import os
+    import shutil
+
+    archive_name = "auto_examples/auto_examples_jupyter.zip"
+    if not os.path.exists(archive_name):
+        raise RuntimeError(
+            f"{archive_name} does not exist, please run `make html` first.")
+
+    extract_dir = "../tutorials/notebooks/"
+    shutil.unpack_archive(archive_name, extract_dir=extract_dir)
+    print(f'Extracted {archive_name} to {extract_dir}')

tutorials/movies_3T/README.rst

@@ -27,7 +27,7 @@ This tutorial requires the following Python packages:
 - scipy
 - h5py
 - scikit-learn
-- voxelwise  (this repository)
+- voxelwise_tutorials  (this repository)
 - himalaya
 - pymoten  (optional, for extracting motion energy)
 - cupy/pytorch (optional, to use GPU in himalaya)

tutorials/movies_4T/README.rst

@@ -30,7 +30,7 @@ This tutorial requires the following Python packages:
 - scipy
 - h5py
 - scikit-learn
-- voxelwise  (this repository)
+- voxelwise_tutorials  (this repository)
 - himalaya
 - pymoten  (optional, for extracting motion energy)
 - cupy/pytorch (optional, to use GPU in himalaya)

tutorials/notebooks/README.md

@@ -0,0 +1,32 @@
+# Jupyter notebooks
+
+This directory contains a copy of each python script as a jupyter notebook.
+These notebooks are generated automatically by `sphinx-gallery`, and do not
+render any content. To see rendered versions of the tutorials, go to the
+[tutorials website](https://gallantlab.github.io/voxelwise_tutorials)
+
+## Run the notebooks
+To run the notebooks yourself, you first need to download this repository and
+install the `voxelwise_tutorials` package:
+
+```bash
+    git clone https://github.com/gallantlab/voxelwise_tutorials.git
+    cd voxelwise_tutorials
+    pip install .
+```
+
+You also need the following dependencies:
+
+- numpy
+- scipy
+- h5py
+- scikit-learn
+- jupyter
+- matplotlib
+- himalaya
+- pycortex  (optional, for using 3D brain viewers)
+- pymoten  (optional, for extracting motion energy)
+- cupy/pytorch (optional, to use a GPU backend in himalaya)
+
+For more info about how to run jupyter notebooks, see
+[the official documentation](https://jupyter-notebook.readthedocs.io/en/stable/).

tutorials/notebooks/movies_3T/00_download_vim4.ipynb

@@ -0,0 +1,101 @@
+{
+  "cells": [
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "%matplotlib inline"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "\n# Download the data set from CRCNS\n\n\nIn this script, we download the data set from CRCNS.\nA (free) account is required.\n\nCite this data set\n------------------\n\nThis tutorial is based on publicly available data\n`published on CRCNS <https://crcns.org/data-sets/vc/TBD>`_.\nIf you publish any work using this data set, please cite the original\npublication [1]_, and the data set [2]_.\n\n.. [1] Huth, A. G., Nishimoto, S., Vu, A. T., & Gallant, J. L. (2012). A\n    continuous semantic space describes the representation of thousands of\n    object and action categories across the human brain. Neuron, 76(6),\n    1210-1224.\n\n.. [2] Huth, A. G., Nishimoto, S., Vu, A. T., & Gallant, J. L. (2020):\n    Gallant Lab Natural Movie 3T fMRI Data. CRCNS.org.\n    http://dx.doi.org/10.6080/TBD\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        ""
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "Download\n--------\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "# path of the data directory\nimport os\nfrom voxelwise_tutorials.io import get_data_home\ndirectory = os.path.join(get_data_home(), \"vim-4\")\nprint(directory)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "We will only use the first subject in this tutorial, but you can run the same\nanalysis on the four other subjects. Uncomment the lines in ``DATAFILES``` to\ndownload more subjects.\n\nWe also skip the stimuli files, since the dataset provides two preprocessed\nfeature spaces to perform voxelwise modeling without requiring the original\nstimuli.\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "import getpass\n\nfrom voxelwise_tutorials.io import download_crcns\n\nDATAFILES = [\n    \"TBD/features/motion_energy.hdf\",\n    \"TBD/features/wordnet.hdf\",\n    \"TBD/mappers/S01_mappers.hdf\",\n    # \"TBD/mappers/S02_mappers.hdf\",\n    # \"TBD/mappers/S03_mappers.hdf\",\n    # \"TBD/mappers/S04_mappers.hdf\",\n    # \"TBD/mappers/S05_mappers.hdf\",\n    \"TBD/responses/S01_responses.hdf\",\n    # \"TBD/responses/S02_responses.hdf\",\n    # \"TBD/responses/S03_responses.hdf\",\n    # \"TBD/responses/S04_responses.hdf\",\n    # \"TBD/responses/S05_responses.hdf\",\n    # \"TBD/stimuli/test.hdf\",\n    # \"TBD/stimuli/train_00.hdf\",\n    # \"TBD/stimuli/train_01.hdf\",\n    # \"TBD/stimuli/train_02.hdf\",\n    # \"TBD/stimuli/train_03.hdf\",\n    # \"TBD/stimuli/train_04.hdf\",\n    # \"TBD/stimuli/train_05.hdf\",\n    # \"TBD/stimuli/train_06.hdf\",\n    # \"TBD/stimuli/train_07.hdf\",\n    # \"TBD/stimuli/train_08.hdf\",\n    # \"TBD/stimuli/train_09.hdf\",\n    # \"TBD/stimuli/train_10.hdf\",\n    # \"TBD/stimuli/train_11.hdf\",\n]"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "username = input(\"CRCNS username: \")\npassword = getpass.getpass(\"CRCNS password: \")\n\nfor datafile in DATAFILES:\n    local_filename = download_crcns(datafile, username, password,\n                                    destination=directory)"
+      ]
+    }
+  ],
+  "metadata": {
+    "kernelspec": {
+      "display_name": "Python 3",
+      "language": "python",
+      "name": "python3"
+    },
+    "language_info": {
+      "codemirror_mode": {
+        "name": "ipython",
+        "version": 3
+      },
+      "file_extension": ".py",
+      "mimetype": "text/x-python",
+      "name": "python",
+      "nbconvert_exporter": "python",
+      "pygments_lexer": "ipython3",
+      "version": "3.7.3"
+    }
+  },
+  "nbformat": 4,
+  "nbformat_minor": 0
+}