Note
Go to the end to download the full example code.
Run an image-based meta-analysis (IBMA) workflow
NiMARE provides a plethora of tools for performing meta-analyses on neuroimaging data. Sometimes it’s difficult to know where to start, especially if you’re new to meta-analysis. This tutorial will walk you through using a IBMA workflow function which puts together the fundamental steps of a IBMA meta-analysis.
import os
from pathlib import Path
import matplotlib.pyplot as plt
from nilearn.plotting import plot_stat_map
from nimare.extract import download_nidm_pain
Download data
Load Dataset
from nimare.dataset import Dataset
from nimare.utils import get_resource_path
dset_file = os.path.join(get_resource_path(), "nidm_pain_dset.json")
dset = Dataset(dset_file)
dset.update_path(dset_dir)
Run IBMA Workflow
The fit method of a IBMA workflow class runs the following steps:
Runs a meta-analysis using the specified method (default: Stouffers)
Applies a corrector to the meta-analysis results (default: FDRCorrector, indep)
Generates cluster tables and runs diagnostics on the corrected results (default: Jackknife)
All in one call!
from nimare.workflows.ibma import IBMAWorkflow
workflow = IBMAWorkflow()
result = workflow.fit(dset)
/home/docs/checkouts/readthedocs.org/user_builds/nimare/envs/stable/lib/python3.9/site-packages/nilearn/maskers/nifti_masker.py:110: UserWarning:
imgs are being resampled to the mask_img resolution. This process is memory intensive. You might want to provide a target_affine that is equal to the affine of the imgs or resample the mask beforehand to save memory and computation time.
/home/docs/checkouts/readthedocs.org/user_builds/nimare/envs/stable/lib/python3.9/site-packages/nilearn/maskers/nifti_masker.py:110: UserWarning:
imgs are being resampled to the mask_img resolution. This process is memory intensive. You might want to provide a target_affine that is equal to the affine of the imgs or resample the mask beforehand to save memory and computation time.
/home/docs/checkouts/readthedocs.org/user_builds/nimare/envs/stable/lib/python3.9/site-packages/nilearn/maskers/nifti_masker.py:110: UserWarning:
imgs are being resampled to the mask_img resolution. This process is memory intensive. You might want to provide a target_affine that is equal to the affine of the imgs or resample the mask beforehand to save memory and computation time.
/home/docs/checkouts/readthedocs.org/user_builds/nimare/envs/stable/lib/python3.9/site-packages/nilearn/maskers/nifti_masker.py:110: UserWarning:
imgs are being resampled to the mask_img resolution. This process is memory intensive. You might want to provide a target_affine that is equal to the affine of the imgs or resample the mask beforehand to save memory and computation time.
/home/docs/checkouts/readthedocs.org/user_builds/nimare/envs/stable/lib/python3.9/site-packages/nilearn/maskers/nifti_masker.py:110: UserWarning:
imgs are being resampled to the mask_img resolution. This process is memory intensive. You might want to provide a target_affine that is equal to the affine of the imgs or resample the mask beforehand to save memory and computation time.
/home/docs/checkouts/readthedocs.org/user_builds/nimare/envs/stable/lib/python3.9/site-packages/nilearn/maskers/nifti_masker.py:110: UserWarning:
imgs are being resampled to the mask_img resolution. This process is memory intensive. You might want to provide a target_affine that is equal to the affine of the imgs or resample the mask beforehand to save memory and computation time.
/home/docs/checkouts/readthedocs.org/user_builds/nimare/envs/stable/lib/python3.9/site-packages/nilearn/maskers/nifti_masker.py:110: UserWarning:
imgs are being resampled to the mask_img resolution. This process is memory intensive. You might want to provide a target_affine that is equal to the affine of the imgs or resample the mask beforehand to save memory and computation time.
/home/docs/checkouts/readthedocs.org/user_builds/nimare/envs/stable/lib/python3.9/site-packages/nilearn/maskers/nifti_masker.py:110: UserWarning:
imgs are being resampled to the mask_img resolution. This process is memory intensive. You might want to provide a target_affine that is equal to the affine of the imgs or resample the mask beforehand to save memory and computation time.
/home/docs/checkouts/readthedocs.org/user_builds/nimare/envs/stable/lib/python3.9/site-packages/nilearn/maskers/nifti_masker.py:110: UserWarning:
imgs are being resampled to the mask_img resolution. This process is memory intensive. You might want to provide a target_affine that is equal to the affine of the imgs or resample the mask beforehand to save memory and computation time.
/home/docs/checkouts/readthedocs.org/user_builds/nimare/envs/stable/lib/python3.9/site-packages/nilearn/maskers/nifti_masker.py:110: UserWarning:
imgs are being resampled to the mask_img resolution. This process is memory intensive. You might want to provide a target_affine that is equal to the affine of the imgs or resample the mask beforehand to save memory and computation time.
/home/docs/checkouts/readthedocs.org/user_builds/nimare/envs/stable/lib/python3.9/site-packages/nilearn/image/image.py:939: UserWarning:
Non-finite values detected. These values will be replaced with zeros.
0%| | 0/21 [00:00<?, ?it/s]
5%|▍ | 1/21 [00:05<01:40, 5.04s/it]
10%|▉ | 2/21 [00:10<01:35, 5.03s/it]
14%|█▍ | 3/21 [00:15<01:30, 5.03s/it]
19%|█▉ | 4/21 [00:20<01:25, 5.03s/it]
24%|██▍ | 5/21 [00:25<01:20, 5.04s/it]
29%|██▊ | 6/21 [00:30<01:15, 5.03s/it]
33%|███▎ | 7/21 [00:35<01:10, 5.03s/it]
38%|███▊ | 8/21 [00:40<01:05, 5.03s/it]
43%|████▎ | 9/21 [00:45<01:00, 5.03s/it]
48%|████▊ | 10/21 [00:50<00:55, 5.02s/it]
52%|█████▏ | 11/21 [00:55<00:49, 4.98s/it]
57%|█████▋ | 12/21 [01:00<00:44, 4.94s/it]
62%|██████▏ | 13/21 [01:04<00:39, 4.93s/it]
67%|██████▋ | 14/21 [01:09<00:34, 4.92s/it]
71%|███████▏ | 15/21 [01:14<00:29, 4.91s/it]
76%|███████▌ | 16/21 [01:19<00:24, 4.90s/it]
81%|████████ | 17/21 [01:24<00:19, 4.89s/it]
86%|████████▌ | 18/21 [01:29<00:14, 4.89s/it]
90%|█████████ | 19/21 [01:34<00:09, 4.88s/it]
95%|█████████▌| 20/21 [01:39<00:04, 4.88s/it]
100%|██████████| 21/21 [01:43<00:00, 4.88s/it]
100%|██████████| 21/21 [01:43<00:00, 4.95s/it]
0%| | 0/21 [00:00<?, ?it/s]
5%|▍ | 1/21 [00:05<01:40, 5.03s/it]
10%|▉ | 2/21 [00:10<01:35, 5.04s/it]
14%|█▍ | 3/21 [00:15<01:31, 5.07s/it]
19%|█▉ | 4/21 [00:20<01:26, 5.07s/it]
24%|██▍ | 5/21 [00:25<01:21, 5.08s/it]
29%|██▊ | 6/21 [00:30<01:16, 5.08s/it]
33%|███▎ | 7/21 [00:35<01:10, 5.06s/it]
38%|███▊ | 8/21 [00:40<01:05, 5.05s/it]
43%|████▎ | 9/21 [00:45<01:00, 5.05s/it]
48%|████▊ | 10/21 [00:50<00:55, 5.05s/it]
52%|█████▏ | 11/21 [00:55<00:50, 5.00s/it]
57%|█████▋ | 12/21 [01:00<00:44, 4.96s/it]
62%|██████▏ | 13/21 [01:05<00:39, 4.94s/it]
67%|██████▋ | 14/21 [01:10<00:34, 4.93s/it]
71%|███████▏ | 15/21 [01:15<00:29, 4.91s/it]
76%|███████▌ | 16/21 [01:19<00:24, 4.90s/it]
81%|████████ | 17/21 [01:24<00:19, 4.90s/it]
86%|████████▌ | 18/21 [01:29<00:14, 4.90s/it]
90%|█████████ | 19/21 [01:34<00:09, 4.90s/it]
95%|█████████▌| 20/21 [01:39<00:04, 4.91s/it]
100%|██████████| 21/21 [01:44<00:00, 4.91s/it]
100%|██████████| 21/21 [01:44<00:00, 4.97s/it]
/home/docs/checkouts/readthedocs.org/user_builds/nimare/checkouts/stable/nimare/diagnostics.py:249: FutureWarning:
Downcasting object dtype arrays on .fillna, .ffill, .bfill is deprecated and will change in a future version. Call result.infer_objects(copy=False) instead. To opt-in to the future behavior, set `pd.set_option('future.no_silent_downcasting', True)`
Plot Results
The fit method of the IBMA workflow class returns a MetaResult object,
where you can access the corrected results of the meta-analysis and diagnostics tables.
Corrected map:
img = result.get_map("z_corr-FDR_method-indep")
plot_stat_map(
img,
cut_coords=4,
display_mode="z",
threshold=1.65, # voxel_thresh p < .05, one-tailed
cmap="RdBu_r",
symmetric_cbar=True,
vmax=4,
)
plt.show()
/home/docs/checkouts/readthedocs.org/user_builds/nimare/envs/stable/lib/python3.9/site-packages/nilearn/plotting/img_plotting.py:1317: UserWarning:
Non-finite values detected. These values will be replaced with zeros.
Clusters table
result.tables["z_corr-FDR_method-indep_tab-clust"]
Contribution table
result.tables["z_corr-FDR_method-indep_diag-Jackknife_tab-counts"]
Report
Finally, a NiMARE report is generated from the MetaResult.
from nimare.reports.base import run_reports
# root_dir = Path(os.getcwd()).parents[1] / "docs" / "_build"
# Use the previous root to run the documentation locally.
root_dir = Path(os.getcwd()).parents[1] / "_readthedocs"
html_dir = root_dir / "html" / "auto_examples" / "02_meta-analyses" / "12_plot_ibma_workflow"
html_dir.mkdir(parents=True, exist_ok=True)
run_reports(result, html_dir)
/home/docs/checkouts/readthedocs.org/user_builds/nimare/envs/stable/lib/python3.9/site-packages/nilearn/plotting/html_stat_map.py:198: UserWarning:
Non-finite values detected. These values will be replaced with zeros.
/home/docs/checkouts/readthedocs.org/user_builds/nimare/envs/stable/lib/python3.9/site-packages/nilearn/plotting/img_plotting.py:1317: UserWarning:
Non-finite values detected. These values will be replaced with zeros.
Total running time of the script: (4 minutes 35.747 seconds)