Merge branch 'main' of github.com:gallantlab/voxelwise_tutorials into main

* 'main' of github.com:gallantlab/voxelwise_tutorials:
  FIX ngrok now requires authentication, remove it from tutorial for simplicity (#18)

Author: mvdoc

tutorials/notebooks/shortclips/00_download_shortclips.ipynb

@@ -15,7 +15,7 @@
       "cell_type": "markdown",
       "metadata": {},
       "source": [
-        "\n# Download the data set\n\nIn this script, we download the data set from Wasabi or GIN. No account is\nrequired.\n\n## Cite this data set\n\nThis tutorial is based on publicly available data [published on GIN](https://gin.g-node.org/gallantlab/shortclips). If you publish any work using\nthis data set, please cite the original publication [1]_, and the data set\n[2]_.\n"
+        "\n# Download the data set\n\nIn this script, we download the data set from Wasabi or GIN. No account is\nrequired.\n\n## Cite this data set\n\nThis tutorial is based on publicly available data `published on GIN\n<https://gin.g-node.org/gallantlab/shortclips>`_. If you publish any work using\nthis data set, please cite the original publication [1]_, and the data set\n[2]_.\n"
       ]
     },
     {

tutorials/notebooks/shortclips/00_setup_colab.ipynb

@@ -15,7 +15,7 @@
       "cell_type": "markdown",
       "metadata": {},
       "source": [
-        "\n# Setup Google Colab\n\nIn this script, we setup a Google Colab environment. This script will only work\nwhen run from [Google Colab](https://colab.research.google.com/)). You can\nskip it if you run the tutorials on your machine.\n"
+        "\n# Setup Google Colab\n\nIn this script, we setup a Google Colab environment. This script will only work\nwhen run from `Google Colab <https://colab.research.google.com/>`_). You can\nskip it if you run the tutorials on your machine.\n"
       ]
     },
     {
@@ -51,7 +51,7 @@
       },
       "outputs": [],
       "source": [
-        "#!git config --global user.email \"you@example.com\" && git config --global user.name \"Your Name\"\n#!wget -O- http://neuro.debian.net/lists/impish.us-ca.libre | sudo tee /etc/apt/sources.list.d/neurodebian.sources.list\n#!apt-key adv --recv-keys --keyserver hkps://keyserver.ubuntu.com 0xA5D32F012649A5A9 > /dev/null\n#!apt-get -qq update > /dev/null\n#!apt-get install -qq inkscape git-annex-standalone > /dev/null\n#!pip install -q voxelwise_tutorials\n#![ -f \"ngrok-stable-linux-amd64.zip\" ] || wget -q https://bin.equinox.io/c/4VmDzA7iaHb/ngrok-stable-linux-amd64.zip\n#![ -f \"ngrok\" ] || unzip ngrok-stable-linux-amd64.zip"
+        "#!git config --global user.email \"you@example.com\" && git config --global user.name \"Your Name\"\n#!wget -O- http://neuro.debian.net/lists/impish.us-ca.libre | sudo tee /etc/apt/sources.list.d/neurodebian.sources.list\n#!apt-key adv --recv-keys --keyserver hkps://keyserver.ubuntu.com 0xA5D32F012649A5A9 > /dev/null\n#!apt-get -qq update > /dev/null\n#!apt-get install -qq inkscape git-annex-standalone > /dev/null\n#!pip install -q voxelwise_tutorials"
       ]
     },
     {
@@ -69,7 +69,7 @@
       },
       "outputs": [],
       "source": [
-        "# - Set up an email and user name to use git, git-annex, and datalad (required to download the data)\n# - Add NeuroDebian to the package sources\n# - Update the gpg keys to use NeuroDebian\n# - Update the list of available packages\n# - Install Inkscape to use more features from Pycortex, and install git-annex to download the data\n# - Install the tutorial helper package, and all the required dependencies\n# - Download ngrok to create a tunnel for pycortex 3D brain viewer\n# - Extract the ngrok archive"
+        "# - Set up an email and username to use git, git-annex, and datalad (required to download the data)\n# - Add NeuroDebian to the package sources\n# - Update the gpg keys to use NeuroDebian\n# - Update the list of available packages\n# - Install Inkscape to use more features from Pycortex, and install git-annex to download the data\n# - Install the tutorial helper package, and all the required dependencies"
       ]
     },
     {

tutorials/notebooks/shortclips/01_plot_explainable_variance.ipynb

@@ -177,7 +177,7 @@
       "cell_type": "markdown",
       "metadata": {},
       "source": [
-        "## Map to subject flatmap\n\nTo better understand the distribution of explainable variance, we map the\nvalues to the subject brain. This can be done with [pycortex](https://gallantlab.github.io/pycortex/), which can create interactive 3D\nviewers to be displayed in any modern browser. ``pycortex`` can also display\nflattened maps of the cortical surface to visualize the entire cortical\nsurface at once.\n\nHere, we do not share the anatomical information of the subjects for privacy\nconcerns. Instead, we provide two mappers:\n\n- to map the voxels to a (subject-specific) flatmap\n- to map the voxels to the Freesurfer average cortical surface (\"fsaverage\")\n\nThe first mapper is 2D matrix of shape (n_pixels, n_voxels) that maps each\nvoxel to a set of pixel in a flatmap. The matrix is efficiently stored in a\n``scipy`` sparse CSR matrix. The function ``plot_flatmap_from_mapper``\nprovides an example of how to use the mapper and visualize the flatmap.\n\n"
+        "## Map to subject flatmap\n\nTo better understand the distribution of explainable variance, we map the\nvalues to the subject brain. This can be done with `pycortex\n<https://gallantlab.github.io/pycortex/>`_, which can create interactive 3D\nviewers to be displayed in any modern browser. ``pycortex`` can also display\nflattened maps of the cortical surface to visualize the entire cortical\nsurface at once.\n\nHere, we do not share the anatomical information of the subjects for privacy\nconcerns. Instead, we provide two mappers:\n\n- to map the voxels to a (subject-specific) flatmap\n- to map the voxels to the Freesurfer average cortical surface (\"fsaverage\")\n\nThe first mapper is 2D matrix of shape (n_pixels, n_voxels) that maps each\nvoxel to a set of pixel in a flatmap. The matrix is efficiently stored in a\n``scipy`` sparse CSR matrix. The function ``plot_flatmap_from_mapper``\nprovides an example of how to use the mapper and visualize the flatmap.\n\n"
       ]
     },
     {
@@ -195,7 +195,7 @@
       "cell_type": "markdown",
       "metadata": {},
       "source": [
-        "This figure is a flattened map of the cortical surface. A number of regions\nof interest (ROIs) have been labeled to ease interpretation. If you have\nnever seen such a flatmap, we recommend taking a look at a [pycortex brain\nviewer](https://www.gallantlab.org/brainviewer/Deniz2019), which displays\nthe brain in 3D. In this viewer, press \"I\" to inflate the brain, \"F\" to\nflatten the surface, and \"R\" to reset the view (or use the ``surface/unfold``\ncursor on the right menu). Press \"H\" for a list of all keyboard shortcuts.\nThis viewer should help you understand the correspondance between the flatten\nand the folded cortical surface of the brain.\n\n"
+        "This figure is a flattened map of the cortical surface. A number of regions\nof interest (ROIs) have been labeled to ease interpretation. If you have\nnever seen such a flatmap, we recommend taking a look at a `pycortex brain\nviewer <https://www.gallantlab.org/brainviewer/Deniz2019>`_, which displays\nthe brain in 3D. In this viewer, press \"I\" to inflate the brain, \"F\" to\nflatten the surface, and \"R\" to reset the view (or use the ``surface/unfold``\ncursor on the right menu). Press \"H\" for a list of all keyboard shortcuts.\nThis viewer should help you understand the correspondance between the flatten\nand the folded cortical surface of the brain.\n\n"
       ]
     },
     {
@@ -263,25 +263,7 @@
       "cell_type": "markdown",
       "metadata": {},
       "source": [
-        "To start an interactive 3D viewer in the browser, we can use the ``webshow``\nfunction in pycortex. If you are running the notebook on Colab, you first\nneed to tunnel the pycortex application out of Colab. To do so, use the\nfollowing cell to start a tunnel with ``ngrok`` and to get an address where\nthe pycortex viewer will be made accessible.\n\n"
-      ]
-    },
-    {
-      "cell_type": "code",
-      "execution_count": null,
-      "metadata": {
-        "collapsed": false
-      },
-      "outputs": [],
-      "source": [
-        "try:\n    import google.colab  # noqa\n    in_colab = True\nexcept ImportError:\n    in_colab = False\nprint(in_colab)\n\nif in_colab:\n    from IPython import get_ipython\n    get_ipython().system_raw('./ngrok http 8050 &')\n    plt.pause(1)\n\n    command = \"\"\"\n        curl -s http://localhost:4040/api/tunnels | python3 -c \\\n        \"import sys, json; print(json.load(sys.stdin)['tunnels'][0]['public_url'])\"\n        \"\"\"\n    result = get_ipython().getoutput(command, split=True)\n    print(\"Use the following address to connect to the brain viewer:\\n\"\n          f\"{result}\\n\"\n          \"and not the one proposed by pycortex ('Open viewer: ...')\\n\")"
-      ]
-    },
-    {
-      "cell_type": "markdown",
-      "metadata": {},
-      "source": [
-        "Now you can start an interactive 3D viewer by changing ``run_webshow`` to\n``True`` and running the following cell.  If you are using Colab, remember to\nuse the address returned by ngrok in the cell above rather than the address\nreturned by this cell.\n\n"
+        "To start an interactive 3D viewer in the browser, we can use the ``webshow``\nfunction in pycortex. (Note that this method works only if you are running the\nnotebooks locally.) You can start an interactive 3D viewer by changing\n``run_webshow`` to ``True`` and running the following cell.\n\n"
       ]
     },
     {

tutorials/notebooks/shortclips/07_extract_motion_energy.ipynb

@@ -15,7 +15,7 @@
       "cell_type": "markdown",
       "metadata": {},
       "source": [
-        "\n# Extract motion energy features from the stimuli\n\nThis script describes how to extract motion-energy features from the stimuli.\n\n.. Note:: The public data set already contains precomputed motion-energy.\n    Therefore, you do not need to run this script to fit motion-energy models\n    in other part of this tutorial.\n\n*Motion-energy features:* Motion-energy features result from filtering a video\nstimulus with spatio-temporal Gabor filters. A pyramid of filters is used to\ncompute the motion-energy features at multiple spatial and temporal scales.\nMotion-energy features were introduced in [1]_.\n\nThe motion-energy extraction is performed by the package [pymoten](https://github.com/gallantlab/pymoten). Check the pymoten [gallery of\nexamples](https://gallantlab.github.io/pymoten/auto_examples/index.html) for\nvisualizing motion-energy filters, and for pymoten API usage examples.\n\n## Running time\nExtracting motion energy is a bit longer than the other examples. It typically\ntakes a couple hours to run.\n"
+        "\n# Extract motion energy features from the stimuli\n\nThis script describes how to extract motion-energy features from the stimuli.\n\n.. Note:: The public data set already contains precomputed motion-energy.\n    Therefore, you do not need to run this script to fit motion-energy models\n    in other part of this tutorial.\n\n*Motion-energy features:* Motion-energy features result from filtering a video\nstimulus with spatio-temporal Gabor filters. A pyramid of filters is used to\ncompute the motion-energy features at multiple spatial and temporal scales.\nMotion-energy features were introduced in [1]_.\n\nThe motion-energy extraction is performed by the package `pymoten\n<https://github.com/gallantlab/pymoten>`_. Check the pymoten `gallery of\nexamples <https://gallantlab.github.io/pymoten/auto_examples/index.html>`_ for\nvisualizing motion-energy filters, and for pymoten API usage examples.\n\n## Running time\nExtracting motion energy is a bit longer than the other examples. It typically\ntakes a couple hours to run.\n"
       ]
     },
     {

tutorials/notebooks/shortclips/merged_for_colab.ipynb

@@ -27,7 +27,7 @@
     "# 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",
+    "when run from `Google Colab <https://colab.research.google.com/>`_). You can\n",
     "skip it if you run the tutorials on your machine.\n"
    ]
   },
@@ -77,9 +77,7 @@
     "#!apt-key adv --recv-keys --keyserver hkps://keyserver.ubuntu.com 0xA5D32F012649A5A9 > /dev/null\n",
     "#!apt-get -qq update > /dev/null\n",
     "#!apt-get install -qq inkscape git-annex-standalone > /dev/null\n",
-    "#!pip install -q voxelwise_tutorials\n",
-    "#![ -f \"ngrok-stable-linux-amd64.zip\" ] || wget -q https://bin.equinox.io/c/4VmDzA7iaHb/ngrok-stable-linux-amd64.zip\n",
-    "#![ -f \"ngrok\" ] || unzip ngrok-stable-linux-amd64.zip"
+    "#!pip install -q voxelwise_tutorials"
    ]
   },
   {
@@ -98,14 +96,12 @@
    },
    "outputs": [],
    "source": [
-    "# - Set up an email and user name to use git, git-annex, and datalad (required to download the data)\n",
+    "# - Set up an email and username to use git, git-annex, and datalad (required to download the data)\n",
     "# - Add NeuroDebian to the package sources\n",
     "# - Update the gpg keys to use NeuroDebian\n",
     "# - Update the list of available packages\n",
     "# - Install Inkscape to use more features from Pycortex, and install git-annex to download the data\n",
-    "# - Install the tutorial helper package, and all the required dependencies\n",
-    "# - Download ngrok to create a tunnel for pycortex 3D brain viewer\n",
-    "# - Extract the ngrok archive"
+    "# - Install the tutorial helper package, and all the required dependencies"
    ]
   },
   {
@@ -458,7 +454,8 @@
     "## Map to subject flatmap\n",
     "\n",
     "To better understand the distribution of explainable variance, we map the\n",
-    "values to the subject brain. This can be done with [pycortex](https://gallantlab.github.io/pycortex/), which can create interactive 3D\n",
+    "values to the subject brain. This can be done with `pycortex\n",
+    "<https://gallantlab.github.io/pycortex/>`_, which can create interactive 3D\n",
     "viewers to be displayed in any modern browser. ``pycortex`` can also display\n",
     "flattened maps of the cortical surface to visualize the entire cortical\n",
     "surface at once.\n",
@@ -497,8 +494,8 @@
    "source": [
     "This figure is a flattened map of the cortical surface. A number of regions\n",
     "of interest (ROIs) have been labeled to ease interpretation. If you have\n",
-    "never seen such a flatmap, we recommend taking a look at a [pycortex brain\n",
-    "viewer](https://www.gallantlab.org/brainviewer/Deniz2019), which displays\n",
+    "never seen such a flatmap, we recommend taking a look at a `pycortex brain\n",
+    "viewer <https://www.gallantlab.org/brainviewer/Deniz2019>`_, which displays\n",
     "the brain in 3D. In this viewer, press \"I\" to inflate the brain, \"F\" to\n",
     "flatten the surface, and \"R\" to reset the view (or use the ``surface/unfold``\n",
     "cursor on the right menu). Press \"H\" for a list of all keyboard shortcuts.\n",
@@ -603,51 +600,9 @@
    "metadata": {},
    "source": [
     "To start an interactive 3D viewer in the browser, we can use the ``webshow``\n",
-    "function in pycortex. If you are running the notebook on Colab, you first\n",
-    "need to tunnel the pycortex application out of Colab. To do so, use the\n",
-    "following cell to start a tunnel with ``ngrok`` and to get an address where\n",
-    "the pycortex viewer will be made accessible.\n",
-    "\n"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {
-    "collapsed": false
-   },
-   "outputs": [],
-   "source": [
-    "try:\n",
-    "    import google.colab  # noqa\n",
-    "    in_colab = True\n",
-    "except ImportError:\n",
-    "    in_colab = False\n",
-    "print(in_colab)\n",
-    "\n",
-    "if in_colab:\n",
-    "    from IPython import get_ipython\n",
-    "    get_ipython().system_raw('./ngrok http 8050 &')\n",
-    "    plt.pause(1)\n",
-    "\n",
-    "    command = \"\"\"\n",
-    "        curl -s http://localhost:4040/api/tunnels | python3 -c \\\n",
-    "        \"import sys, json; print(json.load(sys.stdin)['tunnels'][0]['public_url'])\"\n",
-    "        \"\"\"\n",
-    "    result = get_ipython().getoutput(command, split=True)\n",
-    "    print(\"Use the following address to connect to the brain viewer:\\n\"\n",
-    "          f\"{result}\\n\"\n",
-    "          \"and not the one proposed by pycortex ('Open viewer: ...')\\n\")"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "Now you can start an interactive 3D viewer by changing ``run_webshow`` to\n",
-    "``True`` and running the following cell.  If you are using Colab, remember to\n",
-    "use the address returned by ngrok in the cell above rather than the address\n",
-    "returned by this cell.\n",
+    "function in pycortex. (Note that this method works only if you are running the\n",
+    "notebooks locally.) You can start an interactive 3D viewer by changing\n",
+    "``run_webshow`` to ``True`` and running the following cell.\n",
     "\n"
    ]
   },