DOC describe explainable variance

Author: TomDLT

tutorials/movies_3T/01_plot_explainable_variance.py

@@ -3,6 +3,19 @@
 Compute the explainable variance
 ================================
 
+Before fitting voxelwise models to the fMRI responses, we can compute the
+explainable variance on the test set repeats.
+
+The explainable variance is the part of the fMRI responses that can be
+explained by voxelwise modeling. It is thus the upper bound of voxelwise
+modeling performances.
+
+Indeed, we can decompose the signal into a sum of two components, one
+component that is repeated if we repeat the same experiment, and one component
+that changes for each repeat. Because voxelwise modeling would use the same
+features for each repeat, it can only model the component that is common to
+all repeats. This shared component can be estimated by taking the mean over
+repeats of the same experiment.
 """
 
 ###############################################################################
@@ -14,25 +27,39 @@
 subject = "S01"
 
 ###############################################################################
+# Compute the explainable variance
+# --------------------------------
 import os
 import numpy as np
 
 from voxelwise.io import load_hdf5_array
 
-# Load fMRI responses on the test set
+###############################################################################
+# First, we load the fMRI responses on the test set, which contains 10 repeats.
 file_name = os.path.join(directory, 'responses', f'{subject}_responses.hdf')
 Y_test = load_hdf5_array(file_name, "Y_test")
 
-# compute the explainable variance per voxel, based on the test set repeats
+###############################################################################
+# Then, we compute the explainable variance per voxel.
+# The variance of the signal is estimated by taking the average variance over
+# repeats (``mean_var``). The variance of the component shared across repeats
+# is estimated by taking the variance of the average response (``var_mean``).
+# Then, we can compute the explainable variance by dividing the two quantities.
+
 mean_var = np.mean(np.var(Y_test, axis=1), axis=0)
 var_mean = np.var(np.mean(Y_test, axis=0), axis=0)
 explainable_variance = var_mean / mean_var
 
 ###############################################################################
 # Map to subject flatmap
+# ----------------------
 import matplotlib.pyplot as plt
 from voxelwise.viz import plot_flatmap_from_mapper
 
 mapper_file = os.path.join(directory, 'mappers', f'{subject}_mappers.hdf')
 plot_flatmap_from_mapper(explainable_variance, mapper_file, vmin=0, vmax=0.7)
 plt.show()
+
+###############################################################################
+# We can see that the explainable variance is mainly located in the visual
+# cortex, which was expected since this is a purely visual experiment.

voxelwise/viz.py

@@ -120,6 +120,7 @@ def plot_flatmap_from_mapper(voxels, mapper_file, ax=None, alpha=0.7,
         figsize = np.array(flatmap_mask.shape) / 100.
         fig = plt.figure(figsize=figsize)
         ax = fig.add_axes((0, 0, 1, 1))
+        ax.axis('off')
 
     # process plotting parameters
     if vmin is None:
@@ -268,6 +269,7 @@ def plot_2d_flatmap_from_mapper(voxels_1, voxels_2, mapper_file, ax=None,
         figsize = np.array(flatmap_mask.shape) / 100.
         fig = plt.figure(figsize=figsize)
         ax = fig.add_axes((0, 0, 1, 1))
+        ax.axis('off')
 
     # process plotting parameters
     if vmin is None: