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 Studyset
from nimare.nimads import Studyset
from nimare.utils import get_resource_path
studyset_file = os.path.join(get_resource_path(), "nidm_pain_studyset.json")
studyset = Studyset(studyset_file, target="mni152_2mm")
studyset.update_path(dset_dir)
'<Studyset: nimads_from_dataset>'
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(studyset)
/home/docs/checkouts/readthedocs.org/user_builds/nimare/checkouts/latest/nimare/transforms.py:310: 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.
t = masker.transform(available_data["t"])
/home/docs/checkouts/readthedocs.org/user_builds/nimare/envs/latest/lib/python3.13/site-packages/nilearn/image/image.py:540: RuntimeWarning: overflow encountered in scalar negative
infinity_norm = max(-data.min(), data.max())
/home/docs/checkouts/readthedocs.org/user_builds/nimare/checkouts/latest/nimare/transforms.py:310: 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.
t = masker.transform(available_data["t"])
/home/docs/checkouts/readthedocs.org/user_builds/nimare/envs/latest/lib/python3.13/site-packages/nilearn/image/image.py:540: RuntimeWarning: overflow encountered in scalar negative
infinity_norm = max(-data.min(), data.max())
/home/docs/checkouts/readthedocs.org/user_builds/nimare/checkouts/latest/nimare/transforms.py:310: 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.
t = masker.transform(available_data["t"])
/home/docs/checkouts/readthedocs.org/user_builds/nimare/envs/latest/lib/python3.13/site-packages/nilearn/image/image.py:540: RuntimeWarning: overflow encountered in scalar negative
infinity_norm = max(-data.min(), data.max())
/home/docs/checkouts/readthedocs.org/user_builds/nimare/checkouts/latest/nimare/transforms.py:310: 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.
t = masker.transform(available_data["t"])
/home/docs/checkouts/readthedocs.org/user_builds/nimare/envs/latest/lib/python3.13/site-packages/nilearn/image/image.py:540: RuntimeWarning: overflow encountered in scalar negative
infinity_norm = max(-data.min(), data.max())
/home/docs/checkouts/readthedocs.org/user_builds/nimare/checkouts/latest/nimare/transforms.py:310: 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.
t = masker.transform(available_data["t"])
/home/docs/checkouts/readthedocs.org/user_builds/nimare/envs/latest/lib/python3.13/site-packages/nilearn/image/image.py:540: RuntimeWarning: overflow encountered in scalar negative
infinity_norm = max(-data.min(), data.max())
/home/docs/checkouts/readthedocs.org/user_builds/nimare/checkouts/latest/nimare/transforms.py:310: 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.
t = masker.transform(available_data["t"])
/home/docs/checkouts/readthedocs.org/user_builds/nimare/envs/latest/lib/python3.13/site-packages/nilearn/image/image.py:540: RuntimeWarning: overflow encountered in scalar negative
infinity_norm = max(-data.min(), data.max())
/home/docs/checkouts/readthedocs.org/user_builds/nimare/checkouts/latest/nimare/transforms.py:310: 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.
t = masker.transform(available_data["t"])
/home/docs/checkouts/readthedocs.org/user_builds/nimare/envs/latest/lib/python3.13/site-packages/nilearn/image/image.py:540: RuntimeWarning: overflow encountered in scalar negative
infinity_norm = max(-data.min(), data.max())
/home/docs/checkouts/readthedocs.org/user_builds/nimare/checkouts/latest/nimare/transforms.py:310: 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.
t = masker.transform(available_data["t"])
/home/docs/checkouts/readthedocs.org/user_builds/nimare/envs/latest/lib/python3.13/site-packages/nilearn/image/image.py:540: RuntimeWarning: overflow encountered in scalar negative
infinity_norm = max(-data.min(), data.max())
/home/docs/checkouts/readthedocs.org/user_builds/nimare/checkouts/latest/nimare/transforms.py:310: 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.
t = masker.transform(available_data["t"])
/home/docs/checkouts/readthedocs.org/user_builds/nimare/envs/latest/lib/python3.13/site-packages/nilearn/image/image.py:540: RuntimeWarning: overflow encountered in scalar negative
infinity_norm = max(-data.min(), data.max())
/home/docs/checkouts/readthedocs.org/user_builds/nimare/checkouts/latest/nimare/transforms.py:310: 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.
t = masker.transform(available_data["t"])
/home/docs/checkouts/readthedocs.org/user_builds/nimare/envs/latest/lib/python3.13/site-packages/nilearn/image/image.py:540: RuntimeWarning: overflow encountered in scalar negative
infinity_norm = max(-data.min(), data.max())
/home/docs/checkouts/readthedocs.org/user_builds/nimare/envs/latest/lib/python3.13/site-packages/numpy/_core/numeric.py:386: RuntimeWarning: invalid value encountered in cast
multiarray.copyto(a, fill_value, casting='unsafe')
/home/docs/checkouts/readthedocs.org/user_builds/nimare/checkouts/latest/nimare/diagnostics.py:324: UserWarning: Attention: At least one of the (sub)peaks falls outside of the cluster body. Identifying the nearest in-cluster voxel.
clusters_table, label_maps = get_clusters_table(
0%| | 0/21 [00:00<?, ?it/s]/home/docs/checkouts/readthedocs.org/user_builds/nimare/envs/latest/lib/python3.13/site-packages/numpy/_core/numeric.py:386: RuntimeWarning: invalid value encountered in cast
multiarray.copyto(a, fill_value, casting='unsafe')
5%|▍ | 1/21 [00:00<00:17, 1.13it/s]/home/docs/checkouts/readthedocs.org/user_builds/nimare/envs/latest/lib/python3.13/site-packages/numpy/_core/numeric.py:386: RuntimeWarning: invalid value encountered in cast
multiarray.copyto(a, fill_value, casting='unsafe')
10%|▉ | 2/21 [00:01<00:16, 1.13it/s]/home/docs/checkouts/readthedocs.org/user_builds/nimare/envs/latest/lib/python3.13/site-packages/numpy/_core/numeric.py:386: RuntimeWarning: invalid value encountered in cast
multiarray.copyto(a, fill_value, casting='unsafe')
14%|█▍ | 3/21 [00:02<00:16, 1.12it/s]/home/docs/checkouts/readthedocs.org/user_builds/nimare/envs/latest/lib/python3.13/site-packages/numpy/_core/numeric.py:386: RuntimeWarning: invalid value encountered in cast
multiarray.copyto(a, fill_value, casting='unsafe')
19%|█▉ | 4/21 [00:03<00:15, 1.12it/s]/home/docs/checkouts/readthedocs.org/user_builds/nimare/envs/latest/lib/python3.13/site-packages/numpy/_core/numeric.py:386: RuntimeWarning: invalid value encountered in cast
multiarray.copyto(a, fill_value, casting='unsafe')
24%|██▍ | 5/21 [00:04<00:14, 1.12it/s]/home/docs/checkouts/readthedocs.org/user_builds/nimare/envs/latest/lib/python3.13/site-packages/numpy/_core/numeric.py:386: RuntimeWarning: invalid value encountered in cast
multiarray.copyto(a, fill_value, casting='unsafe')
29%|██▊ | 6/21 [00:05<00:13, 1.12it/s]/home/docs/checkouts/readthedocs.org/user_builds/nimare/envs/latest/lib/python3.13/site-packages/numpy/_core/numeric.py:386: RuntimeWarning: invalid value encountered in cast
multiarray.copyto(a, fill_value, casting='unsafe')
33%|███▎ | 7/21 [00:06<00:12, 1.12it/s]/home/docs/checkouts/readthedocs.org/user_builds/nimare/envs/latest/lib/python3.13/site-packages/numpy/_core/numeric.py:386: RuntimeWarning: invalid value encountered in cast
multiarray.copyto(a, fill_value, casting='unsafe')
38%|███▊ | 8/21 [00:07<00:11, 1.11it/s]/home/docs/checkouts/readthedocs.org/user_builds/nimare/envs/latest/lib/python3.13/site-packages/numpy/_core/numeric.py:386: RuntimeWarning: invalid value encountered in cast
multiarray.copyto(a, fill_value, casting='unsafe')
43%|████▎ | 9/21 [00:08<00:10, 1.11it/s]/home/docs/checkouts/readthedocs.org/user_builds/nimare/envs/latest/lib/python3.13/site-packages/numpy/_core/numeric.py:386: RuntimeWarning: invalid value encountered in cast
multiarray.copyto(a, fill_value, casting='unsafe')
48%|████▊ | 10/21 [00:08<00:09, 1.12it/s]/home/docs/checkouts/readthedocs.org/user_builds/nimare/envs/latest/lib/python3.13/site-packages/numpy/_core/numeric.py:386: RuntimeWarning: invalid value encountered in cast
multiarray.copyto(a, fill_value, casting='unsafe')
52%|█████▏ | 11/21 [00:09<00:08, 1.14it/s]/home/docs/checkouts/readthedocs.org/user_builds/nimare/envs/latest/lib/python3.13/site-packages/numpy/_core/numeric.py:386: RuntimeWarning: invalid value encountered in cast
multiarray.copyto(a, fill_value, casting='unsafe')
57%|█████▋ | 12/21 [00:10<00:07, 1.16it/s]/home/docs/checkouts/readthedocs.org/user_builds/nimare/envs/latest/lib/python3.13/site-packages/numpy/_core/numeric.py:386: RuntimeWarning: invalid value encountered in cast
multiarray.copyto(a, fill_value, casting='unsafe')
62%|██████▏ | 13/21 [00:11<00:06, 1.18it/s]/home/docs/checkouts/readthedocs.org/user_builds/nimare/envs/latest/lib/python3.13/site-packages/numpy/_core/numeric.py:386: RuntimeWarning: invalid value encountered in cast
multiarray.copyto(a, fill_value, casting='unsafe')
67%|██████▋ | 14/21 [00:12<00:05, 1.19it/s]/home/docs/checkouts/readthedocs.org/user_builds/nimare/envs/latest/lib/python3.13/site-packages/numpy/_core/numeric.py:386: RuntimeWarning: invalid value encountered in cast
multiarray.copyto(a, fill_value, casting='unsafe')
71%|███████▏ | 15/21 [00:13<00:05, 1.19it/s]/home/docs/checkouts/readthedocs.org/user_builds/nimare/envs/latest/lib/python3.13/site-packages/numpy/_core/numeric.py:386: RuntimeWarning: invalid value encountered in cast
multiarray.copyto(a, fill_value, casting='unsafe')
76%|███████▌ | 16/21 [00:13<00:04, 1.20it/s]/home/docs/checkouts/readthedocs.org/user_builds/nimare/envs/latest/lib/python3.13/site-packages/numpy/_core/numeric.py:386: RuntimeWarning: invalid value encountered in cast
multiarray.copyto(a, fill_value, casting='unsafe')
81%|████████ | 17/21 [00:14<00:03, 1.20it/s]/home/docs/checkouts/readthedocs.org/user_builds/nimare/envs/latest/lib/python3.13/site-packages/numpy/_core/numeric.py:386: RuntimeWarning: invalid value encountered in cast
multiarray.copyto(a, fill_value, casting='unsafe')
86%|████████▌ | 18/21 [00:15<00:02, 1.20it/s]/home/docs/checkouts/readthedocs.org/user_builds/nimare/envs/latest/lib/python3.13/site-packages/numpy/_core/numeric.py:386: RuntimeWarning: invalid value encountered in cast
multiarray.copyto(a, fill_value, casting='unsafe')
90%|█████████ | 19/21 [00:16<00:01, 1.20it/s]/home/docs/checkouts/readthedocs.org/user_builds/nimare/envs/latest/lib/python3.13/site-packages/numpy/_core/numeric.py:386: RuntimeWarning: invalid value encountered in cast
multiarray.copyto(a, fill_value, casting='unsafe')
95%|█████████▌| 20/21 [00:17<00:00, 1.20it/s]/home/docs/checkouts/readthedocs.org/user_builds/nimare/envs/latest/lib/python3.13/site-packages/numpy/_core/numeric.py:386: RuntimeWarning: invalid value encountered in cast
multiarray.copyto(a, fill_value, casting='unsafe')
100%|██████████| 21/21 [00:18<00:00, 1.21it/s]
100%|██████████| 21/21 [00:18<00:00, 1.16it/s]
0%| | 0/21 [00:00<?, ?it/s]/home/docs/checkouts/readthedocs.org/user_builds/nimare/envs/latest/lib/python3.13/site-packages/numpy/_core/numeric.py:386: RuntimeWarning: invalid value encountered in cast
multiarray.copyto(a, fill_value, casting='unsafe')
5%|▍ | 1/21 [00:00<00:17, 1.14it/s]/home/docs/checkouts/readthedocs.org/user_builds/nimare/envs/latest/lib/python3.13/site-packages/numpy/_core/numeric.py:386: RuntimeWarning: invalid value encountered in cast
multiarray.copyto(a, fill_value, casting='unsafe')
10%|▉ | 2/21 [00:01<00:16, 1.14it/s]/home/docs/checkouts/readthedocs.org/user_builds/nimare/envs/latest/lib/python3.13/site-packages/numpy/_core/numeric.py:386: RuntimeWarning: invalid value encountered in cast
multiarray.copyto(a, fill_value, casting='unsafe')
14%|█▍ | 3/21 [00:02<00:15, 1.13it/s]/home/docs/checkouts/readthedocs.org/user_builds/nimare/envs/latest/lib/python3.13/site-packages/numpy/_core/numeric.py:386: RuntimeWarning: invalid value encountered in cast
multiarray.copyto(a, fill_value, casting='unsafe')
19%|█▉ | 4/21 [00:03<00:15, 1.13it/s]/home/docs/checkouts/readthedocs.org/user_builds/nimare/envs/latest/lib/python3.13/site-packages/numpy/_core/numeric.py:386: RuntimeWarning: invalid value encountered in cast
multiarray.copyto(a, fill_value, casting='unsafe')
24%|██▍ | 5/21 [00:04<00:14, 1.12it/s]/home/docs/checkouts/readthedocs.org/user_builds/nimare/envs/latest/lib/python3.13/site-packages/numpy/_core/numeric.py:386: RuntimeWarning: invalid value encountered in cast
multiarray.copyto(a, fill_value, casting='unsafe')
29%|██▊ | 6/21 [00:05<00:13, 1.11it/s]/home/docs/checkouts/readthedocs.org/user_builds/nimare/envs/latest/lib/python3.13/site-packages/numpy/_core/numeric.py:386: RuntimeWarning: invalid value encountered in cast
multiarray.copyto(a, fill_value, casting='unsafe')
33%|███▎ | 7/21 [00:06<00:12, 1.11it/s]/home/docs/checkouts/readthedocs.org/user_builds/nimare/envs/latest/lib/python3.13/site-packages/numpy/_core/numeric.py:386: RuntimeWarning: invalid value encountered in cast
multiarray.copyto(a, fill_value, casting='unsafe')
38%|███▊ | 8/21 [00:07<00:11, 1.12it/s]/home/docs/checkouts/readthedocs.org/user_builds/nimare/envs/latest/lib/python3.13/site-packages/numpy/_core/numeric.py:386: RuntimeWarning: invalid value encountered in cast
multiarray.copyto(a, fill_value, casting='unsafe')
43%|████▎ | 9/21 [00:08<00:10, 1.13it/s]/home/docs/checkouts/readthedocs.org/user_builds/nimare/envs/latest/lib/python3.13/site-packages/numpy/_core/numeric.py:386: RuntimeWarning: invalid value encountered in cast
multiarray.copyto(a, fill_value, casting='unsafe')
48%|████▊ | 10/21 [00:08<00:09, 1.13it/s]/home/docs/checkouts/readthedocs.org/user_builds/nimare/envs/latest/lib/python3.13/site-packages/numpy/_core/numeric.py:386: RuntimeWarning: invalid value encountered in cast
multiarray.copyto(a, fill_value, casting='unsafe')
52%|█████▏ | 11/21 [00:09<00:08, 1.15it/s]/home/docs/checkouts/readthedocs.org/user_builds/nimare/envs/latest/lib/python3.13/site-packages/numpy/_core/numeric.py:386: RuntimeWarning: invalid value encountered in cast
multiarray.copyto(a, fill_value, casting='unsafe')
57%|█████▋ | 12/21 [00:10<00:07, 1.17it/s]/home/docs/checkouts/readthedocs.org/user_builds/nimare/envs/latest/lib/python3.13/site-packages/numpy/_core/numeric.py:386: RuntimeWarning: invalid value encountered in cast
multiarray.copyto(a, fill_value, casting='unsafe')
62%|██████▏ | 13/21 [00:11<00:06, 1.18it/s]/home/docs/checkouts/readthedocs.org/user_builds/nimare/envs/latest/lib/python3.13/site-packages/numpy/_core/numeric.py:386: RuntimeWarning: invalid value encountered in cast
multiarray.copyto(a, fill_value, casting='unsafe')
67%|██████▋ | 14/21 [00:12<00:05, 1.18it/s]/home/docs/checkouts/readthedocs.org/user_builds/nimare/envs/latest/lib/python3.13/site-packages/numpy/_core/numeric.py:386: RuntimeWarning: invalid value encountered in cast
multiarray.copyto(a, fill_value, casting='unsafe')
71%|███████▏ | 15/21 [00:13<00:05, 1.19it/s]/home/docs/checkouts/readthedocs.org/user_builds/nimare/envs/latest/lib/python3.13/site-packages/numpy/_core/numeric.py:386: RuntimeWarning: invalid value encountered in cast
multiarray.copyto(a, fill_value, casting='unsafe')
76%|███████▌ | 16/21 [00:13<00:04, 1.19it/s]/home/docs/checkouts/readthedocs.org/user_builds/nimare/envs/latest/lib/python3.13/site-packages/numpy/_core/numeric.py:386: RuntimeWarning: invalid value encountered in cast
multiarray.copyto(a, fill_value, casting='unsafe')
81%|████████ | 17/21 [00:14<00:03, 1.19it/s]/home/docs/checkouts/readthedocs.org/user_builds/nimare/envs/latest/lib/python3.13/site-packages/numpy/_core/numeric.py:386: RuntimeWarning: invalid value encountered in cast
multiarray.copyto(a, fill_value, casting='unsafe')
86%|████████▌ | 18/21 [00:15<00:02, 1.19it/s]/home/docs/checkouts/readthedocs.org/user_builds/nimare/envs/latest/lib/python3.13/site-packages/numpy/_core/numeric.py:386: RuntimeWarning: invalid value encountered in cast
multiarray.copyto(a, fill_value, casting='unsafe')
90%|█████████ | 19/21 [00:16<00:01, 1.19it/s]/home/docs/checkouts/readthedocs.org/user_builds/nimare/envs/latest/lib/python3.13/site-packages/numpy/_core/numeric.py:386: RuntimeWarning: invalid value encountered in cast
multiarray.copyto(a, fill_value, casting='unsafe')
95%|█████████▌| 20/21 [00:17<00:00, 1.18it/s]/home/docs/checkouts/readthedocs.org/user_builds/nimare/envs/latest/lib/python3.13/site-packages/numpy/_core/numeric.py:386: RuntimeWarning: invalid value encountered in cast
multiarray.copyto(a, fill_value, casting='unsafe')
100%|██████████| 21/21 [00:18<00:00, 1.18it/s]
100%|██████████| 21/21 [00:18<00:00, 1.16it/s]
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()
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/checkouts/latest/nimare/reports/figures.py:659: UserWarning: kwargs['alpha']=0.7 detected in parameters.
Overriding with transparency=None.
To suppress this warning pass your 'alpha' value via the 'transparency' parameter.
fig = plot_img(
Total running time of the script: (0 minutes 54.423 seconds)