ENH: Add function to plot statistical clusters on brain surface #13366

shristibaral · 2025-08-10T11:07:13Z

What does this implement/fix?

I improved the existing statistical cluster plot by adding a new function that plots the cluster boundary to its spatial extent on top of the brain.

Comments rearranged Docstring updated Code cleanup

drammock · 2025-08-11T20:51:41Z

Thanks for the contribution! For a big change like this, it's usually best to open an issue first to discuss the API. We'll discuss this one at our next maintainer meeting and report back. Meanwhile: if I view the last image in the rendered tutorial (https://output.circle-artifacts.com/output/job/77fa0002-c504-4110-a95d-0a57460ffe05/artifacts/0/html/auto_tutorials/stats-source-space/20_cluster_1samp_spatiotemporal.html#visualize-the-clusters), there doesn't appear to be any magenta-colored boundary on the brain? So not clear that this function is actually working as intended.

shristibaral · 2025-08-12T06:17:01Z

Thanks for the contribution! For a big change like this, it's usually best to open an issue first to discuss the API. We'll discuss this one at our next maintainer meeting and report back.

Apologies. I will open issue next time. :)

Meanwhile: if I view the last image in the rendered tutorial (https://output.circle-artifacts.com/output/job/77fa0002-c504-4110-a95d-0a57460ffe05/artifacts/0/html/auto_tutorials/stats-source-space/20_cluster_1samp_spatiotemporal.html#visualize-the-clusters), there doesn't appear to be any magenta-colored boundary on the brain? So not clear that this function is actually working as intended.

I have updated this part with a new cluster index, the boundary is visible now.

wmvanvliet

A good start! Now we need the unit test to test different scenarios:

Explicitly check that the proper vertices are included in the label
Plotting multiple clusters and checking the auto-generated names
Selecting different time points and checking that the cluster boundaries change

wmvanvliet · 2025-08-13T07:05:51Z

doc/changes/dev/13366.newfeature.rst

@@ -0,0 +1 @@
+Make :func:`~mne.viz.plot_stat_cluster` that plots spatial extent of a cluster on top of a brain by `Shristi Baral`_.


Suggested change

Make :func:`~mne.viz.plot_stat_cluster` that plots spatial extent of a cluster on top of a brain by `Shristi Baral`_.

Add :func:`~mne.viz.plot_stat_cluster` that plots the spatial extent of a cluster on top of a brain by `Shristi Baral`_.

wmvanvliet · 2025-08-13T07:07:52Z

mne/viz/_3d.py

+            "A cluster is a tuple of two elements,  a list time indices "
+            "and list of vertex indices."


Suggested change

"A cluster is a tuple of two elements, a list time indices "

"and list of vertex indices."

"A cluster is a tuple of two elements: an array of time indices "

"and an array of vertex indices."

wmvanvliet · 2025-08-13T07:09:08Z

mne/viz/_3d.py

+    # Let's create an anatomical label containing these vertex indices.
+    # Problem 1): a label must be defined for either the left or right hemisphere. It
+    # cannot span both hemispheres. So we must filter the vertices based on their
+    # hemisphere.


Suggested change

# Let's create an anatomical label containing these vertex indices.

# Problem 1): a label must be defined for either the left or right hemisphere. It

# cannot span both hemispheres. So we must filter the vertices based on their

# hemisphere.

# Create the anatomical label containing the vertex indices belonging to the cluster.

# A label cannot span both hemispheres. So we must filter the vertices based on their

# hemisphere.

wmvanvliet · 2025-08-13T07:10:08Z

mne/viz/_3d.py

+    # Problem 2): We have vertex *indices* that need to be transformed into proper
+    # vertex numbers. Not every vertex in the original high-resolution brain mesh is a
+    # source point in the source estimate. Do draw nice smooth curves, we need to
+    # interpolate the vertex indices.


Suggested change

# Problem 2): We have vertex *indices* that need to be transformed into proper

# vertex numbers. Not every vertex in the original high-resolution brain mesh is a

# source point in the source estimate. Do draw nice smooth curves, we need to

# interpolate the vertex indices.

# Transform vertex indices into proper vertex numbers.

# Not every vertex in the original high-resolution brain mesh is a

# source point in the source estimate. Do draw nice smooth curves, we need to

# interpolate the vertex indices.

wmvanvliet · 2025-08-13T07:12:58Z

mne/viz/tests/test_3d.py

+@testing.requires_testing_data
+def test_plot_stat_cluster(renderer_interactive):
+    """Test plotting clusters on brain in static and interactive mode."""
+    pytest.importorskip("nibabel")


Why is nibabel necessary?

wmvanvliet · 2025-08-13T07:25:03Z

mne/viz/tests/test_3d.py

+    for key in ("lh", "rh"):
+        for attr, desc in [
+            ("labels", "brain.labels"),
+            ("_hemis", "brain._hemis"),
+            ("_layered_meshes", "brain._layered_meshes"),
+        ]:
+            if key not in getattr(brain, attr):
+                missing.append(f"{key} is missing from '{desc}'")
+    if not brain._subject:
+        missing.append("Subject name is missing from brain._subject")
+    if not brain._subjects_dir:
+        missing.append("Subject directory path is missing from brain._subjects_dir")
+    if brain._times is None or brain._times.size == 0:
+        missing.append("Time is missing from brain._times")


Suggested change

for key in ("lh", "rh"):

for attr, desc in [

("labels", "brain.labels"),

("_hemis", "brain._hemis"),

("_layered_meshes", "brain._layered_meshes"),

]:

if key not in getattr(brain, attr):

missing.append(f"{key} is missing from '{desc}'")

if not brain._subject:

missing.append("Subject name is missing from brain._subject")

if not brain._subjects_dir:

missing.append("Subject directory path is missing from brain._subjects_dir")

if brain._times is None or brain._times.size == 0:

missing.append("Time is missing from brain._times")

# Check that the proper anatomical label has been constructed.

assert len(brain.labels["lh"] == 1

assert len(brain.labels["rh"] == 0

assert brain.labels["lh"][0].name == "cluster-0"

In unit tests, it is not necessary to produce user-friendly error messages and you can just assert. Also, I think we can get away with just verifying the label is there and not bother with checking other Brain related functionality such as the presence of _hemis and _layered_meshes as those things are tested in other unit tests.

wmvanvliet · 2025-08-13T07:27:58Z

mne/viz/tests/test_3d.py

+    n_time = 5
+    n_verts = sum(len(v) for v in vertices)
+
+    # simulate stc data


For this test, I don't think it's actually needed to have STC data, we could just do:

brain = Brain("sample", subjects_dir=subjects_dir, surface="white")

wmvanvliet · 2025-08-13T07:29:48Z

tutorials/stats-source-space/20_cluster_1samp_spatiotemporal.py

+# Alternatively, you may wish to observe clusters are considered statistically
+# significant under the permutation distribution with resect all the source estimates.
+# This can easily be done by plotting the cluster boundary on top of the source
+# estimates using the code snippet below.


Suggested change

# Alternatively, you may wish to observe clusters are considered statistically

# significant under the permutation distribution with resect all the source estimates.

# This can easily be done by plotting the cluster boundary on top of the source

# estimates using the code snippet below.

# Alternatively, you may wish to observe the spatial and temporal extent of

# single clusters. The code below demonstrates how to plot the cluster

# boundary on top of an existing source estimate.

wmvanvliet · 2025-08-13T07:30:41Z

tutorials/stats-source-space/20_cluster_1samp_spatiotemporal.py

+    initial_time=0.1,
+)
+
+# We are plotting only one clusters here for illustration purpose.


Suggested change

# We are plotting only one clusters here for illustration purpose.

# Plot one cluster at the time of maximal spatial extent of that cluster.

wmvanvliet · 2025-08-13T07:31:27Z

tutorials/stats-source-space/20_cluster_1samp_spatiotemporal.py

+    good_clusters[2], src, difference_plot, time="max-extent", color="magenta", width=1
+)
+
+# Plotting the same cluster on the interactive mode for illustration purpose.


Suggested change

# Plotting the same cluster on the interactive mode for illustration purpose.

# %%

Plotting the cluster in interactive mode allows scrolling through time.

wmvanvliet · 2025-08-13T07:35:41Z

Apologies. I will open issue next time. :)

Why wait? You can do so now :)

shristibaral · 2025-08-13T08:09:23Z

A good start! Now we need the unit test to test different scenarios:

Explicitly check that the proper vertices are included in the label

Plotting multiple clusters and checking the auto-generated names

Selecting different time points and checking that the cluster boundaries change

WIP

Add function to plot statistical clusters on brain surface

0c31c92

shristibaral changed the title ~~ENH: Add function to plot statistical clusters on brain surface~~ ENH: Add function to plot statistical clusters on brain surface (#13366) Aug 10, 2025

shristibaral changed the title ~~ENH: Add function to plot statistical clusters on brain surface (#13366)~~ ENH: Add function to plot statistical clusters on brain surface Aug 10, 2025

shristibaral added 8 commits August 10, 2025 14:38

Added enhancement PR with number

990f08e

Added newfeature PR with number

7ccd14f

Fix Error type

8e840df

change function reference

1b8edc1

Unit test update

90b77cf

Comments rearranged Docstring updated Code cleanup

Update brain plot

2caecf1

Merge branch 'main' into plot-clusters

ec2a2ca

Merge branch 'main' into plot-clusters

45dc971

shristibaral marked this pull request as ready for review August 11, 2025 18:54

shristibaral requested review from larsoner, drammock, agramfort and dengemann as code owners August 11, 2025 18:54

shristibaral added 2 commits August 12, 2025 09:13

Updated cluster index for visualization

f40aab4

Merge branch 'main' into plot-clusters

6378319

wmvanvliet reviewed Aug 13, 2025

View reviewed changes

Addressed suggestion by @wmvanvliet

8c913a4

Removed cell magic

49be698

		@@ -0,0 +1 @@
		Make :func:`~mne.viz.plot_stat_cluster` that plots spatial extent of a cluster on top of a brain by `Shristi Baral`_.

	Make :func:`~mne.viz.plot_stat_cluster` that plots spatial extent of a cluster on top of a brain by `Shristi Baral`_.
	Add :func:`~mne.viz.plot_stat_cluster` that plots the spatial extent of a cluster on top of a brain by `Shristi Baral`_.

		"A cluster is a tuple of two elements, a list time indices "
		"and list of vertex indices."

	# We are plotting only one clusters here for illustration purpose.
	# Plot one cluster at the time of maximal spatial extent of that cluster.

Uh oh!

ENH: Add function to plot statistical clusters on brain surface #13366

Are you sure you want to change the base?

ENH: Add function to plot statistical clusters on brain surface #13366

Uh oh!

Conversation

shristibaral commented Aug 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What does this implement/fix?

Uh oh!

drammock commented Aug 11, 2025

Uh oh!

shristibaral commented Aug 12, 2025

Uh oh!

wmvanvliet left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

wmvanvliet commented Aug 13, 2025

Uh oh!

shristibaral commented Aug 13, 2025

Uh oh!

Uh oh!

shristibaral commented Aug 10, 2025 •

edited

Loading