.. _sphx_glr__auto_examples_shortclips:

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>


.. toctree::
   :hidden:

   /_auto_examples/shortclips/00_download_shortclips
   /_auto_examples/shortclips/00_setup_colab
   /_auto_examples/shortclips/01_plot_explainable_variance
   /_auto_examples/shortclips/02_plot_ridge_regression
   /_auto_examples/shortclips/03_plot_wordnet_model
   /_auto_examples/shortclips/04_plot_hemodynamic_response
   /_auto_examples/shortclips/05_plot_motion_energy_model
   /_auto_examples/shortclips/06_plot_banded_ridge_model
   /_auto_examples/shortclips/07_extract_motion_energy