Skip to content

Commit 8650d52

Browse files
Yifan YuCopilot
Yifan Yu
and
Copilot
committed
Clarify voxelwise CBMR terminology
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
1 parent dd890b3 commit 8650d52

5 files changed

Lines changed: 277 additions & 146 deletions

File tree

‎docs/sg_execution_times.rst‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
2+
:orphan:
3+
4+
.. _sphx_glr_sg_execution_times:
5+
6+
7+
Computation times
8+
=================
9+
**00:00.000** total execution time for 23 files **from all galleries**:
10+
11+
.. container::
12+
13+
.. raw:: html
14+
15+
<style scoped>
16+
<link href="https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/5.3.0/css/bootstrap.min.css" rel="stylesheet" />
17+
<link href="https://cdn.datatables.net/1.13.6/css/dataTables.bootstrap5.min.css" rel="stylesheet" />
18+
</style>
19+
<script src="https://code.jquery.com/jquery-3.7.0.js"></script>
20+
<script src="https://cdn.datatables.net/1.13.6/js/jquery.dataTables.min.js"></script>
21+
<script src="https://cdn.datatables.net/1.13.6/js/dataTables.bootstrap5.min.js"></script>
22+
<script type="text/javascript" class="init">
23+
$(document).ready( function () {
24+
$('table.sg-datatable').DataTable({order: [[1, 'desc']]});
25+
} );
26+
</script>
27+
28+
.. list-table::
29+
:header-rows: 1
30+
:class: table table-striped sg-datatable
31+
32+
* - Example
33+
- Time
34+
- Mem (MB)
35+
* - :ref:`sphx_glr_auto_examples_01_datasets_01_plot_dataset_io.py` (``../examples/01_datasets/01_plot_dataset_io.py``)
36+
- 00:00.000
37+
- 0.0
38+
* - :ref:`sphx_glr_auto_examples_01_datasets_02_download_neurosynth.py` (``../examples/01_datasets/02_download_neurosynth.py``)
39+
- 00:00.000
40+
- 0.0
41+
* - :ref:`sphx_glr_auto_examples_01_datasets_03_plot_neurovault_io.py` (``../examples/01_datasets/03_plot_neurovault_io.py``)
42+
- 00:00.000
43+
- 0.0
44+
* - :ref:`sphx_glr_auto_examples_01_datasets_04_transform_images_to_coordinates.py` (``../examples/01_datasets/04_transform_images_to_coordinates.py``)
45+
- 00:00.000
46+
- 0.0
47+
* - :ref:`sphx_glr_auto_examples_01_datasets_05_plot_nimads.py` (``../examples/01_datasets/05_plot_nimads.py``)
48+
- 00:00.000
49+
- 0.0
50+
* - :ref:`sphx_glr_auto_examples_01_datasets_06_plot_dataset_json.py` (``../examples/01_datasets/06_plot_dataset_json.py``)
51+
- 00:00.000
52+
- 0.0
53+
* - :ref:`sphx_glr_auto_examples_02_meta-analyses_01_plot_cbma.py` (``../examples/02_meta-analyses/01_plot_cbma.py``)
54+
- 00:00.000
55+
- 0.0
56+
* - :ref:`sphx_glr_auto_examples_02_meta-analyses_02_plot_ibma.py` (``../examples/02_meta-analyses/02_plot_ibma.py``)
57+
- 00:00.000
58+
- 0.0
59+
* - :ref:`sphx_glr_auto_examples_02_meta-analyses_03_plot_kernel_transformers.py` (``../examples/02_meta-analyses/03_plot_kernel_transformers.py``)
60+
- 00:00.000
61+
- 0.0
62+
* - :ref:`sphx_glr_auto_examples_02_meta-analyses_04_plot_estimators.py` (``../examples/02_meta-analyses/04_plot_estimators.py``)
63+
- 00:00.000
64+
- 0.0
65+
* - :ref:`sphx_glr_auto_examples_02_meta-analyses_05_plot_correctors.py` (``../examples/02_meta-analyses/05_plot_correctors.py``)
66+
- 00:00.000
67+
- 0.0
68+
* - :ref:`sphx_glr_auto_examples_02_meta-analyses_06_plot_compare_ibma_and_cbma.py` (``../examples/02_meta-analyses/06_plot_compare_ibma_and_cbma.py``)
69+
- 00:00.000
70+
- 0.0
71+
* - :ref:`sphx_glr_auto_examples_02_meta-analyses_07_macm.py` (``../examples/02_meta-analyses/07_macm.py``)
72+
- 00:00.000
73+
- 0.0
74+
* - :ref:`sphx_glr_auto_examples_02_meta-analyses_08_plot_cbma_subtraction_conjunction.py` (``../examples/02_meta-analyses/08_plot_cbma_subtraction_conjunction.py``)
75+
- 00:00.000
76+
- 0.0
77+
* - :ref:`sphx_glr_auto_examples_02_meta-analyses_09_plot_simulated_data.py` (``../examples/02_meta-analyses/09_plot_simulated_data.py``)
78+
- 00:00.000
79+
- 0.0
80+
* - :ref:`sphx_glr_auto_examples_02_meta-analyses_10_plot_cbma_workflow.py` (``../examples/02_meta-analyses/10_plot_cbma_workflow.py``)
81+
- 00:00.000
82+
- 0.0
83+
* - :ref:`sphx_glr_auto_examples_02_meta-analyses_11_plot_cbmr.py` (``../examples/02_meta-analyses/11_plot_cbmr.py``)
84+
- 00:00.000
85+
- 0.0
86+
* - :ref:`sphx_glr_auto_examples_02_meta-analyses_12_plot_ibma_workflow.py` (``../examples/02_meta-analyses/12_plot_ibma_workflow.py``)
87+
- 00:00.000
88+
- 0.0
89+
* - :ref:`sphx_glr_auto_examples_03_annotation_01_plot_tfidf.py` (``../examples/03_annotation/01_plot_tfidf.py``)
90+
- 00:00.000
91+
- 0.0
92+
* - :ref:`sphx_glr_auto_examples_03_annotation_02_plot_cognitive_atlas.py` (``../examples/03_annotation/02_plot_cognitive_atlas.py``)
93+
- 00:00.000
94+
- 0.0
95+
* - :ref:`sphx_glr_auto_examples_03_annotation_03_plot_lda.py` (``../examples/03_annotation/03_plot_lda.py``)
96+
- 00:00.000
97+
- 0.0
98+
* - :ref:`sphx_glr_auto_examples_03_annotation_04_plot_gclda.py` (``../examples/03_annotation/04_plot_gclda.py``)
99+
- 00:00.000
100+
- 0.0
101+
* - :ref:`sphx_glr_auto_examples_04_decoding_01_plot_discrete_decoders.py` (``../examples/04_decoding/01_plot_discrete_decoders.py``)
102+
- 00:00.000
103+
- 0.0

‎examples/02_meta-analyses/11_plot_cbmr.py‎

Lines changed: 45 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
r"""
22
.. _metas_cbmr:
3-
.. _metas_spatial_cbmr:
3+
.. _metas_voxelwise_cbmr:
44
55
============================================================
66
Coordinate-based meta-regression with moderator-effect modes
@@ -10,15 +10,14 @@
1010
1111
CBMR is a generative framework for estimating smooth activation intensity
1212
functions from coordinate-based meta-analytic data. The same
13-
:class:`~nimare.meta.cbmr.CBMREstimator` can parameterize study-level moderator
14-
effects in two ways:
13+
:class:`~nimare.meta.cbmr.CBMREstimator` can parameterize moderator effects in
14+
two ways:
1515
1616
* ``moderator_effect="global"`` estimates one scalar coefficient per moderator.
17-
This is the classic CBMR model and answers whether a study-level covariate has
18-
an overall effect on the spatial intensity function.
19-
* ``moderator_effect="voxelwise"`` estimates a smooth map for each moderator.
20-
This spatially varying model asks where the study-level covariate effect is
21-
stronger or weaker over voxels.
17+
This assumes the effect of the moderator has a global effect across the entire brain.
18+
* ``moderator_effect="voxelwise"`` estimates a scalar coefficient _per voxel_ per moderator.
19+
This assumes the effect of the moderator differentially impacts voxels throughout the brain.
20+
This is likely a more accurate assumption, but requires a lot more data for estimation.
2221
2322
This tutorial fits both versions to the same simulated Studyset with the same
2423
groups and the same standardized moderators, then compares their outputs.
@@ -37,7 +36,7 @@
3736
# Load Studyset-compatible data
3837
# -----------------------------------------------------------------------------
3938
# We simulate a coordinate-based Studyset with reported foci, sample sizes,
40-
# diagnosis labels, drug-status labels, and continuous study-level moderators.
39+
# diagnosis labels, drug-status labels, and continuous moderators.
4140
# The example uses a moderate number of studies and coarse B-spline spacing so
4241
# that both global and voxelwise CBMR fits run quickly.
4342

@@ -67,9 +66,9 @@
6766
# Option 1: global moderator effects
6867
# -----------------------------------------------------------------------------
6968
# With ``moderator_effect="global"``, CBMR estimates group-specific baseline
70-
# spatial intensity functions plus one scalar effect for each study-level
71-
# moderator. Here, ``standardized_sample_sizes`` and ``standardized_avg_age``
72-
# each receive one global coefficient shared over voxels.
69+
# spatial intensity functions plus one scalar effect for each moderator.
70+
# Here, ``standardized_sample_sizes`` and ``standardized_avg_age`` each receive
71+
# one global coefficient shared over voxels.
7372

7473
global_cbmr = CBMREstimator(
7574
moderator_effect="global",
@@ -207,10 +206,10 @@
207206
###############################################################################
208207
# Option 2: voxelwise moderator effects
209208
# -----------------------------------------------------------------------------
210-
# The same estimator exposes spatially varying CBMR through
209+
# The same estimator exposes voxelwise moderator-effect maps through
211210
# ``moderator_effect="voxelwise"``. This option uses the same groups and the same
212-
# standardized moderators as above, but estimates a smooth map for each moderator
213-
# within each group. The approximate backend is used here for speed.
211+
# standardized moderators as above, but estimates a smooth effect map for each
212+
# moderator within each group. The approximate backend is used here for speed.
214213

215214
voxelwise_cbmr = CBMREstimator(
216215
moderator_effect="voxelwise",
@@ -228,8 +227,8 @@
228227
voxelwise_results = voxelwise_cbmr.fit(dataset=studyset)
229228

230229
print(voxelwise_results.describe_inference_inputs())
231-
print(voxelwise_results.sv_moderator_names)
232-
print(voxelwise_results.describe_sv_effects())
230+
print(voxelwise_results.voxelwise_moderator_effect_map_names)
231+
print(voxelwise_results.describe_voxelwise_moderator_effect_maps())
233232

234233
###############################################################################
235234
# Plot voxelwise moderator-effect maps
@@ -239,15 +238,19 @@
239238
# scalar tables.
240239

241240
plot_stat_map(
242-
voxelwise_results.get_map("svModerator_standardized_sample_sizes_group-SchizophreniaYes"),
241+
voxelwise_results.get_map(
242+
"voxelwiseModeratorEffect_standardized_sample_sizes_group-SchizophreniaYes"
243+
),
243244
cut_coords=[0, 0, -8],
244245
draw_cross=False,
245246
cmap="RdBu_r",
246247
symmetric_cbar=True,
247248
title="Voxelwise sample-size effect: SchizophreniaYes",
248249
)
249250
plot_stat_map(
250-
voxelwise_results.get_map("svModerator_standardized_avg_age_group-SchizophreniaYes"),
251+
voxelwise_results.get_map(
252+
"voxelwiseModeratorEffect_standardized_avg_age_group-SchizophreniaYes"
253+
),
251254
cut_coords=[0, 0, -8],
252255
draw_cross=False,
253256
cmap="RdBu_r",
@@ -264,11 +267,11 @@
264267
# Fisher information standard errors can be requested with ``method="FI"``.
265268

266269
voxelwise_moderator_result = voxelwise_results.test_moderators(method="sandwich")
267-
print(voxelwise_moderator_result.metadata["spatial_cbmr_inference_method"])
270+
print(voxelwise_moderator_result.metadata["voxelwise_cbmr_inference_method"])
268271

269272
plot_stat_map(
270273
voxelwise_moderator_result.get_map(
271-
"z_svModerator_standardized_sample_sizes_group-SchizophreniaYes"
274+
"z_voxelwiseModeratorEffect_standardized_sample_sizes_group-SchizophreniaYes"
272275
),
273276
cut_coords=[0, 0, -8],
274277
draw_cross=False,
@@ -285,7 +288,8 @@
285288

286289
plot_stat_map(
287290
voxelwise_moderator_comparison.get_map(
288-
"z_svModerator_standardized_sample_sizes-standardized_avg_age_group-SchizophreniaYes"
291+
"z_voxelwiseModeratorEffect_standardized_sample_sizes-standardized_avg_age_group-"
292+
"SchizophreniaYes"
289293
),
290294
cut_coords=[0, 0, -8],
291295
draw_cross=False,
@@ -299,17 +303,29 @@
299303
###############################################################################
300304
# Optional inverse-Fisher standard errors for voxelwise CBMR
301305
# -----------------------------------------------------------------------------
302-
# The same voxelwise inference helpers can use inverse Fisher information rather
303-
# than the sandwich estimator.
306+
# The same voxelwise inference helpers can use inverse Fisher information, but
307+
# the sandwich estimator is usually the safer default for applied CBMR analyses.
308+
# Inverse-Fisher standard errors are model-based: they are efficient when the
309+
# likelihood, mean-variance relationship, and independence assumptions are
310+
# correctly specified, but can be too optimistic when those assumptions are only
311+
# approximate. Coordinate-based meta-analytic data often have study-level
312+
# clustering, heterogeneous reporting practices, and other departures from the
313+
# idealized Poisson model. Sandwich standard errors use the fitted model for the
314+
# mean structure while estimating covariance from empirical residual variation,
315+
# making inference more robust to this kind of model misspecification.
316+
#
317+
# For that reason, we recommend keeping ``method="sandwich"`` as the default for
318+
# primary voxelwise CBMR inference. ``method="FI"`` can still be useful for
319+
# sensitivity analyses, simulations where the model is known to be correct, or
320+
# comparisons with fully model-based standard errors.
304321

305322
voxelwise_fi_result = voxelwise_results.test_groups(method="FI")
306-
print(voxelwise_fi_result.metadata["spatial_cbmr_inference_method"])
323+
print(voxelwise_fi_result.metadata["voxelwise_cbmr_inference_method"])
307324

308325
###############################################################################
309326
# Summary
310327
# -----------------------------------------------------------------------------
311328
# Use ``moderator_effect="global"`` when the scientific question is whether a
312-
# study-level covariate has an overall effect on activation intensity. Use
313-
# ``moderator_effect="voxelwise"`` when the scientific question is where that
314-
# covariate effect varies across the brain. Both options share the same
315-
# preprocessing, grouping, and result-centered inference interface.
329+
# moderator has an overall effect on activation intensity. Use ``moderator_effect="voxelwise"``
330+
# when the scientific question is where that moderator effect varies across the brain.
331+
# Both options share the same preprocessing, grouping, and result-centered inference interface.

0 commit comments

Comments
 (0)