Note

Go to the end to download the full example code. or to run this example in your browser via Binder

First level analysis of a complete BIDS dataset from openneuro¶

Full step-by-step example of fitting a GLM to perform a first level analysis in an openneuro BIDS dataset. We demonstrate how BIDS derivatives can be exploited to perform a simple one subject analysis with minimal code. Details about the BIDS standard are available at https://bids.neuroimaging.io/. We also demonstrate how to download individual groups of files from the Openneuro s3 bucket.

More specifically:

Download an fMRI BIDS dataset with derivatives from openneuro.
Extract first level model objects automatically from the BIDS dataset.
Demonstrate Quality assurance of Nilearn estimation against available FSL. estimation in the openneuro dataset.
Display contrast plot and uncorrected first level statistics table report.

Fetch openneuro BIDS dataset¶

We download one subject from the stopsignal task in the ds000030 V4 BIDS dataset available in openneuro. This dataset contains the necessary information to run a statistical analysis using Nilearn. The dataset also contains statistical results from a previous FSL analysis that we can employ for comparison with the Nilearn estimation.

from nilearn.datasets import (
    fetch_ds000030_urls,
    fetch_openneuro_dataset,
    select_from_index,
)

_, urls = fetch_ds000030_urls()

exclusion_patterns = [
    "*group*",
    "*phenotype*",
    "*mriqc*",
    "*parameter_plots*",
    "*physio_plots*",
    "*space-fsaverage*",
    "*space-T1w*",
    "*dwi*",
    "*beh*",
    "*task-bart*",
    "*task-rest*",
    "*task-scap*",
    "*task-task*",
]
urls = select_from_index(
    urls, exclusion_filters=exclusion_patterns, n_subjects=1
)

data_dir, _ = fetch_openneuro_dataset(urls=urls)

[get_dataset_dir] Dataset found in
/home/runner/nilearn_data/ds000030/ds000030_R1.0.4/uncompressed
[get_dataset_dir] Dataset found in
/home/runner/nilearn_data/ds000030/ds000030_R1.0.4/uncompressed

Obtain FirstLevelModel objects automatically and fit arguments¶

From the dataset directory we automatically obtain FirstLevelModel objects with their subject_id filled from the BIDS dataset. Moreover we obtain, for each model, the list of run images and their respective events and confound regressors. Those are inferred from the confounds.tsv files available in the BIDS dataset. To get the first level models we have to specify the dataset directory, the task_label and the space_label as specified in the file names. We also have to provide the folder with the desired derivatives, that in this case were produced by the fMRIPrep BIDS app.

from nilearn.glm.first_level import first_level_from_bids

task_label = "stopsignal"
space_label = "MNI152NLin2009cAsym"
derivatives_folder = "derivatives/fmriprep"
(
    models,
    models_run_imgs,
    models_events,
    models_confounds,
) = first_level_from_bids(
    data_dir,
    task_label,
    space_label,
    smoothing_fwhm=5.0,
    derivatives_folder=derivatives_folder,
    n_jobs=2,
    verbose=1,
)

/home/runner/work/nilearn/nilearn/examples/04_glm_first_level/plot_bids_features.py:86: UserWarning:
No bold.json found in BIDS folder in:
 /home/runner/nilearn_data/ds000030/ds000030_R1.0.4/uncompressed/derivatives/fmriprep.
  ) = first_level_from_bids(
[first_level_from_bids]
Found the following 1 preprocessed BOLD files
- for subject 10159
- for filter: [('task', 'stopsignal'), ('space', 'MNI152NLin2009cAsym')]:
        -
/home/runner/nilearn_data/ds000030/ds000030_R1.0.4/uncompressed/derivatives/fmri
prep/sub-10159/func/sub-10159_task-stopsignal_space-MNI152NLin2009cAsym_desc-pre
proc_bold.nii.gz

[first_level_from_bids]
Found the following 1 events files
- for subject 10159
- for filter: [('task', 'stopsignal')]:
        -
/home/runner/nilearn_data/ds000030/ds000030_R1.0.4/uncompressed/sub-10159/func/s
ub-10159_task-stopsignal_events.tsv

[first_level_from_bids]
Found the following 1 confounds files
- for subject 10159
- for filter: [('task', 'stopsignal')]:
        -
/home/runner/nilearn_data/ds000030/ds000030_R1.0.4/uncompressed/derivatives/fmri
prep/sub-10159/func/sub-10159_task-stopsignal_desc-confounds_regressors.tsv

Access the model and model arguments of the subject and process events.

model, imgs, events, confounds = (
    models[0],
    models_run_imgs[0],
    models_events[0],
    models_confounds[0],
)
subject = f"sub-{model.subject_label}"
model.minimize_memory = False  # override default

from pathlib import Path

from nilearn.interfaces.fsl import get_design_from_fslmat

fsl_design_matrix_path = (
    Path(data_dir)
    / "derivatives"
    / "task"
    / subject
    / "stopsignal.feat"
    / "design.mat"
)
design_matrix = get_design_from_fslmat(
    fsl_design_matrix_path, column_names=None
)

We identify the columns of the Go and StopSuccess conditions of the design matrix inferred from the FSL file, to use them later for contrast definition.

design_columns = [
    f"cond_{int(i):02}" for i in range(len(design_matrix.columns))
]
design_columns[0] = "Go"
design_columns[4] = "StopSuccess"
design_matrix.columns = design_columns

First level model estimation (one subject)¶

We fit the first level model for one subject.

model.fit(imgs, design_matrices=[design_matrix])

[FirstLevelModel.fit] Computing run 1 out of 1 runs (go take a coffee, a big
one).
[FirstLevelModel.fit] Performing mask computation.
[FirstLevelModel.fit] Masking took 2 seconds.
[FirstLevelModel.fit] Performing GLM computation.
[FirstLevelModel.fit] GLM took 2 seconds.
[FirstLevelModel.fit] Computation of 1 runs done in 5 seconds.

First Level Model

In a Jupyter environment, please rerun this cell to show the HTML representation or trust the notebook.
On GitHub, the HTML representation is unable to render, please try loading this page with nbviewer.org.

Then we compute the StopSuccess - Go contrast. We can use the column names of the design matrix.

z_map = model.compute_contrast("StopSuccess - Go")

Visualize results¶

Let’s have a look at the Nilearn estimation and the FSL estimation available in the dataset.

import matplotlib.pyplot as plt
import nibabel as nib
from scipy.stats import norm

from nilearn.plotting import plot_glass_brain, show

fsl_z_map = nib.load(
    Path(data_dir)
    / "derivatives"
    / "task"
    / subject
    / "stopsignal.feat"
    / "stats"
    / "zstat12.nii.gz"
)

plot_glass_brain(
    z_map,
    threshold=norm.isf(0.001),
    title='Nilearn Z map of "StopSuccess - Go" (unc p<0.001)',
    plot_abs=False,
    display_mode="ortho",
)
plot_glass_brain(
    fsl_z_map,
    threshold=norm.isf(0.001),
    title='FSL Z map of "StopSuccess - Go" (unc p<0.001)',
    plot_abs=False,
    display_mode="ortho",
)

<nilearn.plotting.displays._projectors.OrthoProjector object at 0x7fcc570f3d60>

We show the agreement between the 2 estimations.

from nilearn.plotting import plot_bland_altman, plot_img_comparison

plot_img_comparison(
    z_map, fsl_z_map, model.masker_, ref_label="Nilearn", src_label="FSL"
)

plot_bland_altman(
    z_map, fsl_z_map, model.masker_, ref_label="Nilearn", src_label="FSL"
)

show()

Simple statistical report of thresholded contrast¶

We display the contrast plot and table with cluster information.

from nilearn.plotting import plot_contrast_matrix

plot_contrast_matrix("StopSuccess - Go", design_matrix)
plot_glass_brain(
    z_map,
    threshold=norm.isf(0.001),
    plot_abs=False,
    display_mode="z",
    figure=plt.figure(figsize=(4, 4)),
)
show()

We can get a latex table from a Pandas Dataframe for display and publication purposes

Saving model outputs to disk¶

We can now easily save the main results, the model metadata and an HTML report to the disk.

output_dir = Path.cwd() / "results" / "plot_bids_features"
output_dir.mkdir(exist_ok=True, parents=True)

from nilearn.interfaces.bids import save_glm_to_bids

save_glm_to_bids(
    model,
    contrasts="StopSuccess - Go",
    contrast_types={"StopSuccess - Go": "t"},
    out_dir=output_dir / "derivatives" / "nilearn_glm",
    prefix=f"{subject}_task-stopsignal",
)

/home/runner/work/nilearn/nilearn/.tox/doc/lib/python3.9/site-packages/nilearn/interfaces/bids/glm.py:203: UserWarning: Contrast name "StopSuccess - Go" changed to "stopsuccessMinusGo"
  model = model._generate_filenames_output(
/home/runner/work/nilearn/nilearn/examples/04_glm_first_level/plot_bids_features.py:243: UserWarning: Contrast name "StopSuccess - Go" changed to "stopsuccessMinusGo"
  save_glm_to_bids(
[save_glm_to_bids] Generating design matrices figures...
[save_glm_to_bids] Generating contrast matrices figures...
[save_glm_to_bids] Saving contrast-level statistical maps...
[save_glm_to_bids] Saving model level statistical maps...
[save_glm_to_bids] Generating HTML...

First Level Model

View the generated files

files = sorted((output_dir / "derivatives" / "nilearn_glm").glob("**/*"))
print("\n".join([str(x.relative_to(output_dir)) for x in files]))

derivatives/nilearn_glm/dataset_description.json
derivatives/nilearn_glm/sub-10159
derivatives/nilearn_glm/sub-10159/sub-10159_task-stopsignal_contrast-stopsuccessMinusGo_design.svg
derivatives/nilearn_glm/sub-10159/sub-10159_task-stopsignal_contrast-stopsuccessMinusGo_stat-effect_statmap.nii.gz
derivatives/nilearn_glm/sub-10159/sub-10159_task-stopsignal_contrast-stopsuccessMinusGo_stat-p_statmap.nii.gz
derivatives/nilearn_glm/sub-10159/sub-10159_task-stopsignal_contrast-stopsuccessMinusGo_stat-t_statmap.nii.gz
derivatives/nilearn_glm/sub-10159/sub-10159_task-stopsignal_contrast-stopsuccessMinusGo_stat-variance_statmap.nii.gz
derivatives/nilearn_glm/sub-10159/sub-10159_task-stopsignal_contrast-stopsuccessMinusGo_stat-z_statmap.nii.gz
derivatives/nilearn_glm/sub-10159/sub-10159_task-stopsignal_corrdesign.svg
derivatives/nilearn_glm/sub-10159/sub-10159_task-stopsignal_design.json
derivatives/nilearn_glm/sub-10159/sub-10159_task-stopsignal_design.svg
derivatives/nilearn_glm/sub-10159/sub-10159_task-stopsignal_design.tsv
derivatives/nilearn_glm/sub-10159/sub-10159_task-stopsignal_report.html
derivatives/nilearn_glm/sub-10159/sub-10159_task-stopsignal_stat-errorts_statmap.nii.gz
derivatives/nilearn_glm/sub-10159/sub-10159_task-stopsignal_stat-rsquared_statmap.nii.gz
derivatives/nilearn_glm/sub-10159/sub-10159_task-stopsignal_statmap.json

Total running time of the script: (0 minutes 39.018 seconds)

Estimated memory usage: 885 MB

Gallery generated by Sphinx-Gallery