Example of explicit fixed effects fMRI model fitting

This example illustrates how to run a fixed effects model based on pre-computed statistics. This is helpful when the initial models have to be fit separately.

For details on the data, please see:

Dehaene-Lambertz G, Dehaene S, Anton JL, Campagne A, Ciuciu P, Dehaene

G, Denghien I, Jobert A, LeBihan D, Sigman M, Pallier C, Poline JB. Functional segregation of cortical language areas by sentence repetition. Hum Brain Mapp. 2006: 27:360–371. http://www.pubmedcentral.nih.gov/articlerender.fcgi?artid=2653076#R11

Please see Simple example of two-session fMRI model fitting for details. The main difference is that the fixed-effects model is run explicitly here, after GLM fitting on two sessions.

Prepare data and analysis parameters

Inspecting ‘data’, we note that there are two sessions

from nilearn.datasets import func
data = func.fetch_fiac_first_level()
fmri_img = [data['func1'], data['func2']]

Dataset created in /home/alexis/nilearn_data/fiac_nilearn.glm

Missing functional scan for session 1.
Data absent, downloading...
Downloading data from http://nipy.sourceforge.net/data-packages/nipy-data-0.2.tar.gz ...

Downloaded 688128 of 81515168 bytes (0.8%,  2.0min remaining)
Downloaded 1826816 of 81515168 bytes (2.2%,  1.6min remaining)
Downloaded 2588672 of 81515168 bytes (3.2%,  1.7min remaining)
Downloaded 2629632 of 81515168 bytes (3.2%,  2.1min remaining)
Downloaded 3678208 of 81515168 bytes (4.5%,  2.0min remaining)
Downloaded 4726784 of 81515168 bytes (5.8%,  2.1min remaining)
Downloaded 5775360 of 81515168 bytes (7.1%,  2.1min remaining)
Downloaded 6823936 of 81515168 bytes (8.4%,  2.2min remaining)
Downloaded 7872512 of 81515168 bytes (9.7%,  2.1min remaining)
Downloaded 8921088 of 81515168 bytes (10.9%,  2.1min remaining)
Downloaded 9969664 of 81515168 bytes (12.2%,  2.1min remaining)
Downloaded 11018240 of 81515168 bytes (13.5%,  2.1min remaining)
Downloaded 12066816 of 81515168 bytes (14.8%,  2.1min remaining)
Downloaded 13115392 of 81515168 bytes (16.1%,  2.1min remaining)
Downloaded 14163968 of 81515168 bytes (17.4%,  2.0min remaining)
Downloaded 15212544 of 81515168 bytes (18.7%,  2.0min remaining)
Downloaded 16261120 of 81515168 bytes (19.9%,  2.0min remaining)
Downloaded 17309696 of 81515168 bytes (21.2%,  2.0min remaining)
Downloaded 18358272 of 81515168 bytes (22.5%,  1.9min remaining)
Downloaded 19406848 of 81515168 bytes (23.8%,  1.9min remaining)
Downloaded 20455424 of 81515168 bytes (25.1%,  1.9min remaining)
Downloaded 21504000 of 81515168 bytes (26.4%,  1.9min remaining)
Downloaded 22552576 of 81515168 bytes (27.7%,  1.8min remaining)
Downloaded 23601152 of 81515168 bytes (29.0%,  1.8min remaining)
Downloaded 24649728 of 81515168 bytes (30.2%,  1.8min remaining)
Downloaded 25698304 of 81515168 bytes (31.5%,  1.7min remaining)
Downloaded 26746880 of 81515168 bytes (32.8%,  1.7min remaining)
Downloaded 27795456 of 81515168 bytes (34.1%,  1.7min remaining)
Downloaded 28844032 of 81515168 bytes (35.4%,  1.6min remaining)
Downloaded 29892608 of 81515168 bytes (36.7%,  1.6min remaining)
Downloaded 30941184 of 81515168 bytes (38.0%,  1.6min remaining)
Downloaded 31989760 of 81515168 bytes (39.2%,  1.5min remaining)
Downloaded 33038336 of 81515168 bytes (40.5%,  1.5min remaining)
Downloaded 34086912 of 81515168 bytes (41.8%,  1.5min remaining)
Downloaded 35135488 of 81515168 bytes (43.1%,  1.5min remaining)
Downloaded 36184064 of 81515168 bytes (44.4%,  1.4min remaining)
Downloaded 37232640 of 81515168 bytes (45.7%,  1.4min remaining)
Downloaded 38281216 of 81515168 bytes (47.0%,  1.4min remaining)
Downloaded 39329792 of 81515168 bytes (48.2%,  1.3min remaining)
Downloaded 40378368 of 81515168 bytes (49.5%,  1.3min remaining)
Downloaded 41426944 of 81515168 bytes (50.8%,  1.3min remaining)
Downloaded 42475520 of 81515168 bytes (52.1%,  1.2min remaining)
Downloaded 43524096 of 81515168 bytes (53.4%,  1.2min remaining)
Downloaded 44572672 of 81515168 bytes (54.7%,  1.2min remaining)
Downloaded 45621248 of 81515168 bytes (56.0%,  1.1min remaining)
Downloaded 46669824 of 81515168 bytes (57.3%,  1.1min remaining)
Downloaded 47718400 of 81515168 bytes (58.5%,  1.1min remaining)
Downloaded 48766976 of 81515168 bytes (59.8%,  1.0min remaining)
Downloaded 49815552 of 81515168 bytes (61.1%,   59.7s remaining)
Downloaded 50864128 of 81515168 bytes (62.4%,   57.7s remaining)
Downloaded 51912704 of 81515168 bytes (63.7%,   55.7s remaining)
Downloaded 52961280 of 81515168 bytes (65.0%,   53.8s remaining)
Downloaded 54009856 of 81515168 bytes (66.3%,   51.9s remaining)
Downloaded 55058432 of 81515168 bytes (67.5%,   49.9s remaining)
Downloaded 56107008 of 81515168 bytes (68.8%,   47.9s remaining)
Downloaded 57155584 of 81515168 bytes (70.1%,   45.9s remaining)
Downloaded 58204160 of 81515168 bytes (71.4%,   44.0s remaining)
Downloaded 59252736 of 81515168 bytes (72.7%,   42.0s remaining)
Downloaded 60301312 of 81515168 bytes (74.0%,   40.1s remaining)
Downloaded 61349888 of 81515168 bytes (75.3%,   38.1s remaining)
Downloaded 62398464 of 81515168 bytes (76.5%,   36.1s remaining)
Downloaded 63447040 of 81515168 bytes (77.8%,   34.1s remaining)
Downloaded 64495616 of 81515168 bytes (79.1%,   32.2s remaining)
Downloaded 65544192 of 81515168 bytes (80.4%,   30.2s remaining)
Downloaded 66592768 of 81515168 bytes (81.7%,   28.2s remaining)
Downloaded 67641344 of 81515168 bytes (83.0%,   26.2s remaining)
Downloaded 68689920 of 81515168 bytes (84.3%,   24.2s remaining)
Downloaded 69738496 of 81515168 bytes (85.6%,   22.3s remaining)
Downloaded 70787072 of 81515168 bytes (86.8%,   20.3s remaining)
Downloaded 71835648 of 81515168 bytes (88.1%,   18.3s remaining)
Downloaded 72884224 of 81515168 bytes (89.4%,   16.3s remaining)
Downloaded 73932800 of 81515168 bytes (90.7%,   14.3s remaining)
Downloaded 74981376 of 81515168 bytes (92.0%,   12.4s remaining)
Downloaded 76029952 of 81515168 bytes (93.3%,   10.4s remaining)
Downloaded 77078528 of 81515168 bytes (94.6%,    8.4s remaining)
Downloaded 78127104 of 81515168 bytes (95.8%,    6.4s remaining)
Downloaded 79175680 of 81515168 bytes (97.1%,    4.4s remaining)
Downloaded 80224256 of 81515168 bytes (98.4%,    2.4s remaining)
Downloaded 81272832 of 81515168 bytes (99.7%,    0.5s remaining) ...done. (154 seconds, 2 min)
Extracting data from /home/alexis/nilearn_data/fiac_nilearn.glm/nipy-data-0.2.tar.gz..... done.

Create a mean image for plotting purpose

from nilearn.image import mean_img
mean_img_ = mean_img(fmri_img[0])

The design matrices were pre-computed, we simply put them in a list of DataFrames

design_files = [data['design_matrix1'], data['design_matrix2']]
import pandas as pd
import numpy as np
design_matrices = [pd.DataFrame(np.load(df)['X']) for df in design_files]

GLM estimation

GLM specification. Note that the mask was provided in the dataset. So we use it.

from nilearn.glm.first_level import FirstLevelModel
fmri_glm = FirstLevelModel(mask_img=data['mask'], smoothing_fwhm=5,
                           minimize_memory=True)

Compute fixed effects of the two runs and compute related images For this, we first define the contrasts as we would do for a single session

n_columns = design_matrices[0].shape[1]
contrast_val = np.hstack(([-1, -1, 1, 1], np.zeros(n_columns - 4)))

Statistics for the first session

from nilearn import plotting
cut_coords = [-129, -126, 49]
contrast_id = 'DSt_minus_SSt'

fmri_glm = fmri_glm.fit(fmri_img[0], design_matrices=design_matrices[0])
summary_statistics_session1 = fmri_glm.compute_contrast(
    contrast_val, output_type='all')
plotting.plot_stat_map(
    summary_statistics_session1['z_score'],
    bg_img=mean_img_, threshold=3.0, cut_coords=cut_coords,
    title='{0}, first session'.format(contrast_id))

<nilearn.plotting.displays._slicers.OrthoSlicer object at 0x7ff8f2fad360>

Statistics for the second session

fmri_glm = fmri_glm.fit(fmri_img[1], design_matrices=design_matrices[1])
summary_statistics_session2 = fmri_glm.compute_contrast(
    contrast_val, output_type='all')
plotting.plot_stat_map(
    summary_statistics_session2['z_score'],
    bg_img=mean_img_, threshold=3.0, cut_coords=cut_coords,
    title='{0}, second session'.format(contrast_id))

<nilearn.plotting.displays._slicers.OrthoSlicer object at 0x7ff8ed2edc90>

Fixed effects statistics

from nilearn.glm.contrasts import compute_fixed_effects

contrast_imgs = [summary_statistics_session1['effect_size'],
                 summary_statistics_session2['effect_size']]
variance_imgs = [summary_statistics_session1['effect_variance'],
                 summary_statistics_session2['effect_variance']]

fixed_fx_contrast, fixed_fx_variance, fixed_fx_stat = compute_fixed_effects(
    contrast_imgs, variance_imgs, data['mask'])
plotting.plot_stat_map(
    fixed_fx_stat, bg_img=mean_img_, threshold=3.0, cut_coords=cut_coords,
    title='{0}, fixed effects'.format(contrast_id))

<nilearn.plotting.displays._slicers.OrthoSlicer object at 0x7ff8f2faee00>

Not unexpectedly, the fixed effects version displays higher peaks than the input sessions. Computing fixed effects enhances the signal-to-noise ratio of the resulting brain maps Note however that, technically, the output maps of the fixed effects map is a t statistic (not a z statistic)

plotting.show()

Estimated memory usage: 546 MB