:orphan:

(If you are looking for some Jupyter notebooks, check the `notebooks
<https://github.com/gallantlab/voxelwise_tutorials/tree/main/tutorials/notebooks>`_
directory.)



.. raw:: html

    <div class="sphx-glr-thumbnails">


.. raw:: html

    </div>

Shortclips tutorial
===================

This tutorial describes how to perform voxelwise modeling on a visual
imaging experiment.

**Data set:** This tutorial is based on publicly available data `published on
GIN <https://gin.g-node.org/gallantlab/shortclips>`_ :ref:`[4b]<hut2012data>`.
This data set contains BOLD fMRI responses in human subjects viewing a set of
natural short movie clips. The functional data were collected in five subjects,
in three sessions over three separate days for each subject. Details of the
experiment are described in the original publication :ref:`[4]<hut2012>`. If
you publish work using this data set, please cite the original publications
:ref:`[4]<hut2012>`, and the GIN data set :ref:`[4b]<hut2012data>`.

**Models:**
This tutorial implements different voxelwise encoding models:

- a ridge model with wordnet semantic features as described in :ref:`[4]<hut2012>`.
- a ridge model with motion-energy features as described in :ref:`[3]<nis2011>`.
- a banded-ridge model with both feature spaces as described in :ref:`[12]<nun2019>`.

**Scikit-learn API:** These tutorials use `scikit-learn
<https://github.com/scikit-learn/scikit-learn>`_ to define the preprocessing
steps, the modeling pipeline, and the cross-validation scheme. If you are not
familiar with the scikit-learn API, we recommend the `getting started guide
<https://scikit-learn.org/stable/getting_started.html>`_. We also use a lot of
the scikit-learn terminology, which is explained in great details in the
`glossary of common terms and API elements
<https://scikit-learn.org/stable/glossary.html#glossary>`_.

**Running time:** Most of these tutorials can be run in a reasonable time
(under 1 minute for most examples, ~7 minutes for the banded ridge example)
with a GPU backend in `himalaya <https://github.com/gallantlab/himalaya>`_.
Using a CPU backend is slower (typically 10 times slower).

**Requirements:**
This tutorial requires the following Python packages:

- voxelwise_tutorials  (this repository) and its dependencies
- cupy or pytorch  (optional, to use a GPU backend in himalaya)

**Gallery of scripts:**
Click on each thumbnail below to open the corresponding page:



.. raw:: html

    <div class="sphx-glr-thumbnails">


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="In this script, we download the data set from Wasabi or GIN. No account is required.">

.. only:: html

  .. image:: /_auto_examples/shortclips/images/thumb/sphx_glr_00_download_shortclips_thumb.png
    :alt:

  :ref:`sphx_glr__auto_examples_shortclips_00_download_shortclips.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Download the data set</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="In this script, we setup a Google Colab environment. This script will only work when run from G...">

.. only:: html

  .. image:: /_auto_examples/shortclips/images/thumb/sphx_glr_00_setup_colab_thumb.png
    :alt:

  :ref:`sphx_glr__auto_examples_shortclips_00_setup_colab.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Setup Google Colab</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Before fitting any voxelwise model to fMRI responses, it is good practice to quantify the amoun...">

.. only:: html

  .. image:: /_auto_examples/shortclips/images/thumb/sphx_glr_01_plot_explainable_variance_thumb.png
    :alt:

  :ref:`sphx_glr__auto_examples_shortclips_01_plot_explainable_variance.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Compute the explainable variance</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="In future examples, we will model the fMRI responses using a regularized linear regression know...">

.. only:: html

  .. image:: /_auto_examples/shortclips/images/thumb/sphx_glr_02_plot_ridge_regression_thumb.png
    :alt:

  :ref:`sphx_glr__auto_examples_shortclips_02_plot_ridge_regression.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Understand ridge regression and cross-validation</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="In this example, we model the fMRI responses with semantic &quot;wordnet&quot; features, manually annotat...">

.. only:: html

  .. image:: /_auto_examples/shortclips/images/thumb/sphx_glr_03_plot_wordnet_model_thumb.png
    :alt:

  :ref:`sphx_glr__auto_examples_shortclips_03_plot_wordnet_model.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Fit a ridge model with wordnet features</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="In this example, we describe how the hemodynamic response function was estimated in the previou...">

.. only:: html

  .. image:: /_auto_examples/shortclips/images/thumb/sphx_glr_04_plot_hemodynamic_response_thumb.png
    :alt:

  :ref:`sphx_glr__auto_examples_shortclips_04_plot_hemodynamic_response.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Visualize the hemodynamic response</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="In this example, we model the fMRI responses with motion-energy features extracted from the mov...">

.. only:: html

  .. image:: /_auto_examples/shortclips/images/thumb/sphx_glr_05_plot_motion_energy_model_thumb.png
    :alt:

  :ref:`sphx_glr__auto_examples_shortclips_05_plot_motion_energy_model.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Fit a ridge model with motion energy features</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="In this example, we model the fMRI responses with a banded ridge regression, with two different...">

.. only:: html

  .. image:: /_auto_examples/shortclips/images/thumb/sphx_glr_06_plot_banded_ridge_model_thumb.png
    :alt:

  :ref:`sphx_glr__auto_examples_shortclips_06_plot_banded_ridge_model.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Fit a banded ridge model with both wordnet and motion energy features</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This script describes how to extract motion-energy features from the stimuli.">

.. only:: html

  .. image:: /_auto_examples/shortclips/images/thumb/sphx_glr_07_extract_motion_energy_thumb.png
    :alt:

  :ref:`sphx_glr__auto_examples_shortclips_07_extract_motion_energy.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Extract motion energy features from the stimuli</div>
    </div>


.. raw:: html

    </div>

|
|

Vim-2 tutorial
==============

.. Note::
    This tutorial is redundant with the "Shortclips tutorial". It uses the
    "vim-2" data set, a data set with brain responses limited to the occipital
    lobe, and with no mappers to plot the data on flatmaps.
    Using the "Shortclips tutorial" with full brain responses is recommended.

This tutorial describes how to perform voxelwise modeling on a visual
imaging experiment.

**Data set:**
This tutorial is based on publicly available data published on
`CRCNS <https://crcns.org/data-sets/vc/vim-2/about-vim-2>`_ :ref:`[3b]<nis2011data>`.
The data is briefly described in the dataset description
`PDF <https://crcns.org/files/data/vim-2/crcns-vim-2-data-description.pdf>`_,
and in more details in the original publication :ref:`[3]<nis2011>`.
If you publish work using this data set, please cite the original
publication :ref:`[3]<nis2011>`, and the CRCNS data set :ref:`[3b]<nis2011data>`.


**Requirements:**
This tutorial requires the following Python packages:

- voxelwise_tutorials  (this repository) and its dependencies
- cupy or pytorch  (optional, to use a GPU backend in himalaya)

**Gallery of scripts:**
Click on each thumbnail below to open the corresponding page:



.. raw:: html

    <div class="sphx-glr-thumbnails">


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="In this script, we download the data set from CRCNS. A (free) account is required.">

.. only:: html

  .. image:: /_auto_examples/vim2/images/thumb/sphx_glr_00_download_vim2_thumb.png
    :alt:

  :ref:`sphx_glr__auto_examples_vim2_00_download_vim2.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Download the data set from CRCNS</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This script describes how to extract motion-energy features from the stimuli.">

.. only:: html

  .. image:: /_auto_examples/vim2/images/thumb/sphx_glr_01_extract_motion_energy_thumb.png
    :alt:

  :ref:`sphx_glr__auto_examples_vim2_01_extract_motion_energy.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Extract motion energy features from the stimuli</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="In this example, we model the fMRI responses with motion-energy features extracted from the mov...">

.. only:: html

  .. image:: /_auto_examples/vim2/images/thumb/sphx_glr_02_plot_ridge_model_thumb.png
    :alt:

  :ref:`sphx_glr__auto_examples_vim2_02_plot_ridge_model.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Fit a ridge model with motion energy features</div>
    </div>


.. raw:: html

    </div>


.. toctree::
   :hidden:
   :includehidden:


   /_auto_examples/shortclips/index.rst
   /_auto_examples/vim2/index.rst


.. only:: html

  .. container:: sphx-glr-footer sphx-glr-footer-gallery

    .. container:: sphx-glr-download sphx-glr-download-python

      :download:`Download all examples in Python source code: _auto_examples_python.zip </_auto_examples/_auto_examples_python.zip>`

    .. container:: sphx-glr-download sphx-glr-download-jupyter

      :download:`Download all examples in Jupyter notebooks: _auto_examples_jupyter.zip </_auto_examples/_auto_examples_jupyter.zip>`


.. only:: html

 .. rst-class:: sphx-glr-signature

    `Gallery generated by Sphinx-Gallery <https://sphinx-gallery.github.io>`_