.. DO NOT EDIT. .. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY. .. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE: .. "auto_examples/04_glm_first_level/plot_predictions_residuals.py" .. LINE NUMBERS ARE GIVEN BELOW. .. only:: html .. note:: :class: sphx-glr-download-link-note :ref:`Go to the end ` to download the full example code. or to run this example in your browser via Binder .. rst-class:: sphx-glr-example-title .. _sphx_glr_auto_examples_04_glm_first_level_plot_predictions_residuals.py: Predicted time series and residuals =================================== Here we fit a First Level :term:`GLM` with the `minimize_memory`-argument set to `False`. By doing so, the `FirstLevelModel`-object stores the residuals, which we can then inspect. Also, the predicted time series can be extracted, which is useful to assess the quality of the model fit. .. include:: ../../../examples/masker_note.rst .. GENERATED FROM PYTHON SOURCE LINES 17-19 Import modules -------------- .. GENERATED FROM PYTHON SOURCE LINES 19-41 .. code-block:: Python import pandas as pd from nilearn import image, masking from nilearn.datasets import fetch_spm_auditory from nilearn.plotting import plot_stat_map, show # load fMRI data subject_data = fetch_spm_auditory() fmri_img = subject_data.func[0] # Make an average mean_img = image.mean_img(fmri_img, copy_header=True) mask = masking.compute_epi_mask(mean_img) # Clean and smooth data fmri_img = image.clean_img(fmri_img, standardize=False) fmri_img = image.smooth_img(fmri_img, 5.0) # load events events = pd.read_csv(subject_data.events, sep="\t") .. rst-class:: sphx-glr-script-out .. code-block:: none [wrapper] Dataset found in /home/runner/nilearn_data/spm_auditory .. GENERATED FROM PYTHON SOURCE LINES 42-48 Fit model --------- Note that `minimize_memory` is set to `False` so that `FirstLevelModel` stores the residuals. `signal_scaling` is set to False, so we keep the same scaling as the original data in `fmri_img`. .. GENERATED FROM PYTHON SOURCE LINES 48-61 .. code-block:: Python from nilearn.glm.first_level import FirstLevelModel fmri_glm = FirstLevelModel( t_r=7, drift_model="cosine", signal_scaling=False, mask_img=mask, minimize_memory=False, ) fmri_glm = fmri_glm.fit(fmri_img, events) .. rst-class:: sphx-glr-script-out .. code-block:: none /home/runner/work/nilearn/nilearn/examples/04_glm_first_level/plot_predictions_residuals.py:58: UserWarning: [NiftiMasker.fit] Generation of a mask has been requested (imgs != None) while a mask was given at masker creation. Given mask will be used. fmri_glm = fmri_glm.fit(fmri_img, events) .. GENERATED FROM PYTHON SOURCE LINES 62-64 Calculate and plot contrast --------------------------- .. GENERATED FROM PYTHON SOURCE LINES 64-77 .. code-block:: Python z_map = fmri_glm.compute_contrast("listening") threshold = 3.1 plot_stat_map( z_map, bg_img=mean_img, threshold=threshold, title=f"listening > rest (t-test; |Z|>{threshold})", ) show() .. image-sg:: /auto_examples/04_glm_first_level/images/sphx_glr_plot_predictions_residuals_001.png :alt: plot predictions residuals :srcset: /auto_examples/04_glm_first_level/images/sphx_glr_plot_predictions_residuals_001.png :class: sphx-glr-single-img .. GENERATED FROM PYTHON SOURCE LINES 78-80 Extract the largest clusters ---------------------------- .. GENERATED FROM PYTHON SOURCE LINES 80-98 .. code-block:: Python from nilearn.maskers import NiftiSpheresMasker from nilearn.reporting import get_clusters_table table = get_clusters_table( z_map, stat_threshold=threshold, cluster_threshold=20 ) table.set_index("Cluster ID", drop=True) table.head() # get the 6 largest clusters' max x, y, and z coordinates coords = table.loc[range(1, 7), ["X", "Y", "Z"]].to_numpy() # extract time series from each coordinate masker = NiftiSpheresMasker(coords) real_timeseries = masker.fit_transform(fmri_img) predicted_timeseries = masker.fit_transform(fmri_glm.predicted[0]) .. GENERATED FROM PYTHON SOURCE LINES 99-101 Plot predicted and actual time series for 6 most significant clusters --------------------------------------------------------------------- .. GENERATED FROM PYTHON SOURCE LINES 101-131 .. code-block:: Python import matplotlib.pyplot as plt # colors for each of the clusters colors = ["blue", "navy", "purple", "magenta", "olive", "teal"] # plot the time series and corresponding locations fig1, axs1 = plt.subplots(2, 6) for i in range(6): # plotting time series axs1[0, i].set_title(f"Cluster peak {coords[i]}\n") axs1[0, i].plot(real_timeseries[:, i], c=colors[i], lw=2) axs1[0, i].plot(predicted_timeseries[:, i], c="r", ls="--", lw=2) axs1[0, i].set_xlabel("Time") axs1[0, i].set_ylabel("Signal intensity", labelpad=0) # plotting image below the time series roi_img = plot_stat_map( z_map, cut_coords=[coords[i][2]], threshold=3.1, figure=fig1, axes=axs1[1, i], display_mode="z", colorbar=False, bg_img=mean_img, ) roi_img.add_markers([coords[i]], colors[i], 300) fig1.set_size_inches(24, 14) show() .. image-sg:: /auto_examples/04_glm_first_level/images/sphx_glr_plot_predictions_residuals_002.png :alt: Cluster peak [-51. -12. 39.] , Cluster peak [-39. -12. 39.] , Cluster peak [-63. 12. 33.] , Cluster peak [60. 0. 36.] , Cluster peak [66. 12. 27.] , Cluster peak [ 60. -18. 30.] :srcset: /auto_examples/04_glm_first_level/images/sphx_glr_plot_predictions_residuals_002.png :class: sphx-glr-single-img .. GENERATED FROM PYTHON SOURCE LINES 132-134 Get residuals ------------- .. GENERATED FROM PYTHON SOURCE LINES 134-138 .. code-block:: Python resid = masker.fit_transform(fmri_glm.residuals[0]) .. GENERATED FROM PYTHON SOURCE LINES 139-142 Plot distribution of residuals ------------------------------ Note that residuals are not really distributed normally. .. GENERATED FROM PYTHON SOURCE LINES 142-155 .. code-block:: Python fig2, axs2 = plt.subplots(2, 3, constrained_layout=True) axs2 = axs2.flatten() for i in range(6): axs2[i].set_title(f"Cluster peak {coords[i]}\n") axs2[i].hist(resid[:, i], color=colors[i]) print(f"Mean residuals: {resid[:, i].mean()}") fig2.set_size_inches(12, 7) show() .. image-sg:: /auto_examples/04_glm_first_level/images/sphx_glr_plot_predictions_residuals_003.png :alt: Cluster peak [-51. -12. 39.] , Cluster peak [-39. -12. 39.] , Cluster peak [-63. 12. 33.] , Cluster peak [60. 0. 36.] , Cluster peak [66. 12. 27.] , Cluster peak [ 60. -18. 30.] :srcset: /auto_examples/04_glm_first_level/images/sphx_glr_plot_predictions_residuals_003.png :class: sphx-glr-single-img .. rst-class:: sphx-glr-script-out .. code-block:: none Mean residuals: 0.018869405610297586 Mean residuals: 0.04575602612203437 Mean residuals: -6.005777885591323e-15 Mean residuals: -0.1304239304725877 Mean residuals: -0.01499899481932693 Mean residuals: 0.04955626049962088 .. GENERATED FROM PYTHON SOURCE LINES 156-172 Plot R-squared -------------- Because we stored the residuals, we can plot the R-squared: the proportion of explained variance of the :term:`GLM` as a whole. Note that the R-squared is markedly lower deep down the brain, where there is more physiological noise and we are further away from the receive coils. However, R-Squared should be interpreted with a grain of salt. The R-squared value will necessarily increase with the addition of more factors (such as rest, active, drift, motion) into the GLM. Additionally, we are looking at the overall fit of the model, so we are unable to say whether a voxel/region has a large R-squared value because the voxel/region is responsive to the experiment (such as active or rest) or because the voxel/region fits the noise factors (such as drift or motion) that could be present in the :term:`GLM`. To isolate the influence of the experiment, we can use an F-test as shown in the next section. .. GENERATED FROM PYTHON SOURCE LINES 172-186 .. code-block:: Python plot_stat_map( fmri_glm.r_square[0], bg_img=mean_img, threshold=0.1, display_mode="z", cut_coords=7, cmap="inferno", title="R-squared", vmin=0, symmetric_cbar=False, ) .. image-sg:: /auto_examples/04_glm_first_level/images/sphx_glr_plot_predictions_residuals_004.png :alt: plot predictions residuals :srcset: /auto_examples/04_glm_first_level/images/sphx_glr_plot_predictions_residuals_004.png :class: sphx-glr-single-img .. rst-class:: sphx-glr-script-out .. code-block:: none .. GENERATED FROM PYTHON SOURCE LINES 187-195 Calculate and Plot F-test ------------------------- The F-test tells you how well the :term:`GLM` fits effects of interest such as the active and rest conditions together. This is different from R-squared, which tells you how well the overall :term:`GLM` fits the data, including active, rest and all the other columns in the design matrix such as drift and motion. .. GENERATED FROM PYTHON SOURCE LINES 195-215 .. code-block:: Python # f-test for 'listening' z_map_ftest = fmri_glm.compute_contrast( "listening", stat_type="F", output_type="z_score" ) plot_stat_map( z_map_ftest, bg_img=mean_img, threshold=threshold, display_mode="z", cut_coords=7, cmap="inferno", title=f"listening > rest (F-test; Z>{threshold})", symmetric_cbar=False, vmin=0, ) show() .. image-sg:: /auto_examples/04_glm_first_level/images/sphx_glr_plot_predictions_residuals_005.png :alt: plot predictions residuals :srcset: /auto_examples/04_glm_first_level/images/sphx_glr_plot_predictions_residuals_005.png :class: sphx-glr-single-img .. rst-class:: sphx-glr-timing **Total running time of the script:** (0 minutes 23.085 seconds) **Estimated memory usage:** 651 MB .. _sphx_glr_download_auto_examples_04_glm_first_level_plot_predictions_residuals.py: .. only:: html .. container:: sphx-glr-footer sphx-glr-footer-example .. container:: binder-badge .. image:: images/binder_badge_logo.svg :target: https://mybinder.org/v2/gh/nilearn/nilearn/0.12.0?urlpath=lab/tree/notebooks/auto_examples/04_glm_first_level/plot_predictions_residuals.ipynb :alt: Launch binder :width: 150 px .. container:: sphx-glr-download sphx-glr-download-jupyter :download:`Download Jupyter notebook: plot_predictions_residuals.ipynb ` .. container:: sphx-glr-download sphx-glr-download-python :download:`Download Python source code: plot_predictions_residuals.py ` .. container:: sphx-glr-download sphx-glr-download-zip :download:`Download zipped: plot_predictions_residuals.zip ` .. only:: html .. rst-class:: sphx-glr-signature `Gallery generated by Sphinx-Gallery `_