Enhancement request: ROI-wise labeling and coloring in connectivity plots

[hasibagen]

If your issue is a usage question, please consider asking on the
MNE Forum instead of opening an issue.

I’m currently visualizing functional connectivity using circular graphs, and I’d like to suggest a visualization enhancement related to labeling and coloring.

In many EEG or fMRI studies, we often group multiple channels or parcels into predefined regions of interest (ROIs). Currently, when plotting the connectivity matrix, each sub-node within an ROI (e.g., multiple parcels or channels) is displayed with its own label. This leads to duplicated or overly dense labels when all sub-nodes within an ROI are shown with the same name (e.g., "Frontal", "Temporal", etc.).

Suggestion:

Labeling: Allow the option to display one label per ROI rather than per sub-node, to avoid visual clutter.

Coloring: Similarly, enable coloring per ROI (i.e., all sub-nodes within a single ROI share the same color), similar to what is available in pyCirclize.

This feature would be very helpful for producing clean, interpretable plots, especially when working with large numbers of ROIs or densely connected matrices.

Example use case:

In fMRI data, an ROI like the left temporal lobe might be made up of several parcels (e.g., L_Temporal_1, L_Temporal_2, L_Temporal_3). Instead of showing all three as separate labels, it would be ideal to show a single label "L_Temporal" and have all three share the same color in the circular plot.

now figue is

A very helpful visual example is available here:
https://moshi4.github.io/pyCirclize/chord_diagram/
#262 (comment)

In this example, each group/ROI is annotated once, and the coloring is done by group.

Would you consider adding such functionality in a future release?

Thanks again for your excellent work!

[larsoner]

I think this is perhaps already supported by passing a properly set node_colors argument, can you check?

[ruuskas]

As noted by @larsoner, this can be done by using appropriate node_colors, node_names, and node_angles arguments. Data from multiple parcels can be combined by averaging before passing your connectivity matrix to plot_connectivity_circle.

[hasibagen]

@larsoner @ruuskas
Hi, thank you again for this great package!

I’ve carefully read through the plot_connectivity_circle API and documentation, but so far I haven’t found a way to achieve the following behavior:

Display only one label per ROI (region of interest), and assign colors by ROI, rather than per individual node/channel.

This is especially helpful in neuroimaging studies where many channels are grouped under the same anatomical or functional region. Showing every channel name (when they all belong to the same ROI) makes the circular graph quite cluttered.

To better explain what I’m aiming for, I’ve created a minimal working example below. It simulates 3 ROIs, each with 5 channels, and generates a connectivity matrix with strong intra-ROI and weak inter-ROI connections. Colors are assigned per ROI, but currently all node names are shown, leading to duplicate ROI labels:

import numpy as np
import matplotlib.pyplot as plt
from mne_connectivity.viz import plot_connectivity_circle

def plot_roi_connectivity(roi_names, n_channels_per_roi, figsize=(10, 10)):
	"""
	Plot simplified ROI connectivity circle graph

	Parameters:
	- roi_names: List of ROI names
	- n_channels_per_roi: Number of channels per ROI
	- figsize: Figure size
	"""
	# Generate channel-to-ROI mapping
	channel_names = []
	channel_to_roi = {}
	for roi_idx, roi in enumerate(roi_names):
		for ch_idx in range(n_channels_per_roi):
			ch_name = f'Ch_{roi}_{ch_idx+1}'
			channel_names.append(ch_name)
			channel_to_roi[ch_name] = roi

	# Generate connectivity matrix
	n_total_channels = len(channel_names)
	con_matrix = np.eye(n_total_channels)

	# Strong intra-ROI connections (0.6-0.9)
	for roi_idx, roi in enumerate(roi_names):
		start_idx = roi_idx * n_channels_per_roi
		end_idx = start_idx + n_channels_per_roi
		intra_con = np.random.uniform(0.6, 0.9, (n_channels_per_roi, n_channels_per_roi))
		intra_con = (intra_con + intra_con.T) / 2  # Ensure symmetry
		np.fill_diagonal(intra_con, 1)  # Keep diagonal as 1
		con_matrix[start_idx:end_idx, start_idx:end_idx] = intra_con

	# Weak inter-ROI connections (0-0.3)
	for i in range(len(roi_names)):
		for j in range(i+1, len(roi_names)):
			start_i = i * n_channels_per_roi
			end_i = start_i + n_channels_per_roi
			start_j = j * n_channels_per_roi
			end_j = start_j + n_channels_per_roi

			inter_con = np.random.uniform(0, 0.3, (n_channels_per_roi, n_channels_per_roi))
			con_matrix[start_i:end_i, start_j:end_j] = inter_con
			con_matrix[start_j:end_j, start_i:end_i] = inter_con.T

	# Assign colors to ROIs
	roi_colors = plt.cm.tab10.colors[:len(roi_names)]
	node_colors = [roi_colors[list(roi_names).index(channel_to_roi[ch])]
	               for ch in channel_names]

	# Create circular layout angles
	n_nodes = len(channel_names)
	node_angles = np.linspace(0, 360, n_nodes, endpoint=False)

	# Plot connectivity circle
	fig, ax = plt.subplots(figsize=figsize, subplot_kw={'polar': True})
	plot_connectivity_circle(
		con_matrix,
		node_names=channel_names,
		node_colors=node_colors,
		node_angles=node_angles,
		colormap="RdBu_r",
		facecolor="white",
		textcolor="black",
		vmin=-1, vmax=1,
		colorbar=False,
		fig=fig,
		ax=ax
	)

	plt.tight_layout()
	return fig, ax

# Minimal example usage
if __name__ == "__main__":
	# Define 3 ROIs with 5 channels each
	roi_names = ['Frontal', 'Temporal', 'Parietal']
	n_channels_per_roi = 5

	# Plot connectivity
	plot_roi_connectivity(roi_names, n_channels_per_roi, figsize=(10, 10))

I'd greatly appreciate any suggestions on how to:

Reduce node label clutter by showing one label per ROI

Group and color nodes by ROI, ideally similar to how pyCirclize allows grouping

If this is currently not supported, would you consider this as a potential feature for future versions?

Thanks again for your time and for maintaining this excellent tool!

I’m trying to achieve a similar effect—this is a figure I created using MATLAB.

[ruuskas]

Hi @hasibagen!

Do I understand correctly, that you would like to have a second level of labeling the regions?

It is already possible to have the same colors and only a single label for each ROI as show below.

[hasibagen]

Hi @hasibagen!

Do I understand correctly, that you would like to have a second level of labeling the regions?

It is already possible to have the same colors and only a single label for each ROI as show below.

Thank you for the great work! I’ve been trying to figure out how to implement this, but after going through the API documentation for quite a while, I still couldn’t find a clear way to achieve it. I’ve also tried asking AI to help write the implementation several times, but without success. Could you please help me understand how this can be done?

[ruuskas]

Hi @hasibagen! To do this, you need to use the group_boundaries parameter for mne.viz.circular_layout to create node_angles. To have only the group labels, you simply need to use empty strings for the nodes within a group, except for the middle one, where you put the group (or ROI) label.

[hasibagen]

Hi @hasibagen! To do this, you need to use the group_boundaries parameter for mne.viz.circular_layout to create node_angles. To have only the group labels, you simply need to use empty strings for the nodes within a group, except for the middle one, where you put the group (or ROI) label.

Hi @ruuskas , thanks again for your suggestion!

I followed your advice and used group_boundaries along with mne.viz.circular_layout. Below is a minimal reproducible demo I wrote based on that idea.

However, I encountered a couple of issues when applying it to my actual dataset:

The layout generated by circular_layout doesn't achieve the full left-right hemispheric symmetry I was aiming for (though I’m not sure if that’s due to how I implemented it).

The group separation appears much smaller than expected, and the functional connectivity result looks quite different from my previous version, which was surprising.

I’ve attached both the new demo code and the plot from my actual data for reference.

Also, it seems there’s very limited documentation or tutorials for mne.viz.circular_layout — I only found the API page and a small official demo. I’ve tried my best to understand it by reading the API and using AI tools to help with the implementation.

Thanks again for your input — I’d really appreciate any further clarification!

import numpy as np
import seaborn as sns
import matplotlib.pyplot as plt
from mne_connectivity.viz import plot_connectivity_circle
from mne.viz import circular_layout
import random

def rest_chord_grouped(channel_to_roi, con_value, figsize=(10, 10)):
    """
    Creates a chord plot based on given ROI-channel mapping and connectivity values.

    Parameters:
    - channel_to_roi (dict): Mapping of channel names to ROI labels.
    - con_value (array): Connectivity values between channels (corresponding to the number of channels).
    - figsize (tuple): Figure size (default (10, 10)).

    Returns:
    - fig: The matplotlib figure object.
    - ax: The matplotlib axes object.
    """

    # Set font and Unicode minus for matplotlib
    plt.rcParams["font.sans-serif"] = ["Microsoft YaHei"]
    plt.rcParams["axes.unicode_minus"] = False

    # Extract label names and prepare node angles
    label_names = list(channel_to_roi.values())
    num_labels = len(label_names)

    # Create node order and group boundaries
    roi_names = sorted(set(label_names))
    node_order = []
    group_boundaries = []
    boundary_index = 0
    for roi in roi_names:
        roi_channels = [i for i, l in enumerate(label_names) if l == roi]
        node_order.extend(roi_channels)
        boundary_index += len(roi_channels)
        group_boundaries.append(boundary_index)
    group_boundaries = group_boundaries[:-1]  # Remove the last boundary

    # Convert node_order to strings to match the expected input of circular_layout
    node_order_str = [str(i) for i in node_order]
    node_names_str = [str(i) for i in range(num_labels)]

    # Create circular layout
    node_angles = circular_layout(
        node_names_str, node_order_str, start_pos=0, group_boundaries=group_boundaries
    )

    # Base region colors
    base_regions = sorted(set([roi_name[2:] for roi_name in label_names]))
    random.seed(42)  # seed for consistency
    color_palette = sns.color_palette("Set1", len(base_regions)).as_hex()
    base_region_to_color = {base_regions[i]: color_palette[i] for i in range(len(base_regions))}

    # Map each label to its color
    color_list = [base_region_to_color[label[2:]] for label in label_names]

    # Create new label names with empty strings for non - middle nodes in each group
    new_label_names = []
    for roi in roi_names:
        roi_channels = [i for i, l in enumerate(label_names) if l == roi]
        for i, channel_idx in enumerate(roi_channels):
            if i == len(roi_channels) // 2:
                new_label_names.append(roi)
            else:
                new_label_names.append("")

    # Create the chord plot with the given parameters
    fig, ax = plt.subplots(subplot_kw={"polar": True})
    rest_chord = plot_connectivity_circle(
        con=con_value,
        node_names=new_label_names,
        colormap="RdBu_r",
        facecolor="white",
        textcolor="black",
        node_angles=node_angles,
        node_colors=color_list,
        node_edgecolor=color_list,
        vmax=1,
        vmin=-1,
        linewidth=1,
        colorbar=False,
        padding=0.1,
        colorbar_pos=(0.1, 0.1),
        fig=fig,
        ax=ax,
    )

    # Adjust figure size and display
    fig.set_size_inches(figsize)
    plt.show()

    return fig, ax


import numpy as np

import numpy as np

if __name__ == "__main__":
    np.random.seed(42)

    # Regions and channels count (both hemispheres)
    region_base_names = [
        "FP", "FEF", "DLPFC", "Broca", "PreMotor",
        "M1", "S1", "Temporal", "Visual"
    ]

    region_channel_counts = {
        "FP": 4, "FEF": 3, "DLPFC": 7, "Broca": 5,
        "PreMotor": 10, "M1": 4, "S1": 5, "Temporal": 4, "Visual": 8
    }

    channel_to_roi = {}
    channel_index = 0
    for region in region_base_names:
        for hemi in ["L", "R"]:
            full_region = f"{hemi}_{region}"
            n_channels = region_channel_counts[region]
            for _ in range(n_channels):
                channel_to_roi[f"C{channel_index + 1}"] = full_region
                channel_index += 1

    n_channels = len(channel_to_roi)

    # Initialize connectivity matrix
    con_value = np.zeros((n_channels, n_channels))

    # Fill upper triangle with random values between -1 and 1
    upper_tri_indices = np.triu_indices(n_channels, k=1)
    con_value[upper_tri_indices] = np.random.uniform(-1, 1, size=len(upper_tri_indices[0]))

    # Make the matrix symmetric
    con_value = con_value + con_value.T

    # Set diagonal to 1
    np.fill_diagonal(con_value, 1)

    # Now call the plotting function with channel_to_roi and con_value
    rest_chord_grouped(channel_to_roi, con_value, (16, 16))

[ruuskas]

The layout generated by circular_layout doesn't achieve the full left-right hemispheric symmetry I was aiming for (though I’m not sure if that’s due to how I implemented it).

To achieve this, you need to flip the second half of node_order.

The group separation appears much smaller than expected, and the functional connectivity result looks quite different from my previous version, which was surprising.

You can adjust the separation between groups by using the group_sep parameter for circular_layout.

Also, it seems there’s very limited documentation or tutorials for mne.viz.circular_layout — I only found the API page and a small official demo. I’ve tried my best to understand it by reading the API and using AI tools to help with the implementation.

I agree that the documentation could perhaps be extended. Let us know if there are some specific suggestions you would like to add.

[hasibagen]

The layout generated by circular_layout doesn't achieve the full left-right hemispheric symmetry I was aiming for (though I’m not sure if that’s due to how I implemented it).

To achieve this, you need to flip the second half of node_order.

The group separation appears much smaller than expected, and the functional connectivity result looks quite different from my previous version, which was surprising.

You can adjust the separation between groups by using the group_sep parameter for circular_layout.

Also, it seems there’s very limited documentation or tutorials for mne.viz.circular_layout — I only found the API page and a small official demo. I’ve tried my best to understand it by reading the API and using AI tools to help with the implementation.

I agree that the documentation could perhaps be extended. Let us know if there are some specific suggestions you would like to add.

Hi @ruuskas ,

Thanks for your earlier pointers on using circular_layout—I’ve got the basic angle calculation working now. I’m stuck on one last hurdle and would appreciate your advice.

In my dataset, a single ROI can be measured by several fNIRS channels, so my dataframe (and the list I pass to circular_layout) includes duplicate entries, e.g.

node_order = ['Left Motor', 'Left Motor', 'Right Motor']
When I run
from mne.viz import circular_layout
node_angles = circular_layout(node_names=node_order,
                              node_order=node_order)
I receive:

ValueError: node_order has repeated entries

ChatGPT suggested appending an index (Left Motor_1, Left Motor_2, …), but for the final chord plot I’d like all channels that belong to the same anatomical ROI to share exactly the same label—one name per ROI—so the legend remains concise.

I could bypass circular_layout and compute angles manually, but that defeats the convenience of letting MNE handle the layout.

Question
Is there a recommended way in MNE to:

1 Keep identical labels for channels that map to the same ROI, and Still let circular_layout handle the angles automatically?

2 Maybe there’s a way to provide a mapping from channels → ROIs or to tell circular_layout to ignore duplicates?

Minimal example (reproducible)

import numpy as np
import pandas as pd
import matplotlib.pyplot as plt
import seaborn as sns
from mne_connectivity.viz import plot_connectivity_circle
from mne.viz import circular_layout

def plot_brain_connectivity_circle(df, figsize=(12, 12), title=None):
    """
    Plot a circular graph showing brain region connections.
    Uses mne.viz.circular_layout to calculate node positions
    Supports symmetrical left-right brain arrangement and same color for same region types

    Parameters:
    df: pandas DataFrame, an x*x correlation matrix with brain region names as index and columns
    figsize: tuple, figure size
    title: string, plot title

    Returns:
    fig, ax: matplotlib figure and axis objects
    """
    # Ensure proper display of English text
    plt.rcParams["font.family"] = ["Arial", "sans-serif"]
    plt.rcParams["axes.unicode_minus"] = False

    # Get list of brain region names
    node_names = df.index.tolist()

    # Extract region type (remove "Left" or "Right" prefix)
    roi_types = [name[4:] for name in node_names]
    unique_roi_types = sorted(list(set(roi_types)))

    # Assign colors to each region type
    colors = sns.color_palette("husl", len(unique_roi_types))
    roi_color_map = {roi_type: colors[i] for i, roi_type in enumerate(unique_roi_types)}

    # Assign colors to each node
    node_colors = [roi_color_map[roi_type] for roi_type in roi_types]

    # Use mne.viz.circular_layout to calculate node angles
    # Extract left and right hemisphere region names
    left_nodes = [name for name in node_names if name.startswith('Left')]
    right_nodes = [name for name in node_names if name.startswith('Right')]

    # Create node order: left regions in original order, then right regions in mirrored order
    node_order = left_nodes + right_nodes[::-1]

    # Calculate node angles with separation between left and right hemispheres
    group_boundaries = [0, len(left_nodes)]  # Separate left and right hemispheres
    node_angles = circular_layout(
        node_names, node_order, start_pos=90,
        group_boundaries=group_boundaries, group_sep=10
    )

    # Create connectivity matrix
    con = df.values

    # Create and configure figure
    fig, ax = plt.subplots(figsize=figsize, subplot_kw=dict(polar=True))

    # Plot connectivity circle
    plot_connectivity_circle(
        con=con,
        node_names=node_names,
        colormap="RdBu_r",
        facecolor="white",
        textcolor="black",
        node_angles=node_angles,
        node_colors=node_colors,
        node_edgecolor=node_colors,
        vmax=1,
        vmin=-1,
        linewidth=1,
        colorbar=False,
        padding=0.1,
        colorbar_pos=(0.1, 0.1),
        fig=fig,
        ax=ax,
    )

    plt.tight_layout()
    return fig, ax

# Test code
if __name__ == "__main__":
    # Create example data
    np.random.seed(42)

    # Define brain region names
    brain_regions = [
        'Left Motor', 'Left Broca', 'Left Dorsolateral', 'Left Ventrolateral', 'Left Frontopolar',
        'Right Motor', 'Right Broca', 'Right Dorsolateral', 'Right Ventrolateral', 'Right Frontopolar'
    ]

    # Create random correlation matrix
    n = len(brain_regions)
    corr_matrix = np.random.rand(n, n) * 2 - 1  # Random values between -1 and 1
    corr_matrix = (corr_matrix + corr_matrix.T) / 2  # Ensure symmetry
    np.fill_diagonal(corr_matrix, 0)  # Set diagonal to 0

    # Create DataFrame
    df = pd.DataFrame(corr_matrix, index=brain_regions, columns=brain_regions)

    # Plot circle graph
    fig, ax = plot_brain_connectivity_circle(df, figsize=(10, 10), title="Brain Connectivity Circle Plot")    

Environment
MNE-Python: 1.7.1
Python: 3.12
OS: Ubuntu 22.04

Any guidance or workaround would be greatly appreciated.

Thanks in advance!

Best,
Jade

[ruuskas]

ChatGPT suggested appending an index (Left Motor_1, Left Motor_2, …), but for the final chord plot I’d >like all channels that belong to the same anatomical ROI to share exactly the same label—one name per ROI—so the legend remains concise.

@hasibagen, I think you can do this when you create node_order, but pass a different node_names without the indices when you plot using plot_connectivity_circle?

Sorry for the delay, I forgot to reply last week.

[hasibagen]

ChatGPT suggested appending an index (Left Motor_1, Left Motor_2, …), but for the final chord plot I’d >like all channels that belong to the same anatomical ROI to share exactly the same label—one name per ROI—so the legend remains concise.

@hasibagen, I think you can do this when you create node_order, but pass a different node_names without the indices when you plot using plot_connectivity_circle?

Sorry for the delay, I forgot to reply last week.

@agramfort

Thanks for the update! This version can run, but it still produces a lot of node names—similar to my previous version where I manually defined the node angles. It doesn't quite achieve the goal of merging node names and assigning angles based on each large ROI.

From what I've seen, this kind of need—merging nodes by ROI and organizing their angles accordingly—is quite common in EEG/fNIRS analyses. Looking forward to seeing if there could be a more elegant or built-in way to implement this in the future.

# Get the list of brain region names
node_names = hbo_cor_sorted.index.tolist()

# Extract the region type (remove the "Left" or "Right" prefix)
roi_types = [name[1:] for name in node_names]
unique_roi_types = sorted(list(set(roi_types)))

# Assign colors to each ROI type
colors = sns.color_palette("husl", len(unique_roi_types))
roi_color_map = {roi_type: colors[i] for i, roi_type in enumerate(unique_roi_types)}

# Assign colors to each node
node_colors = [roi_color_map[roi_type] for roi_type in roi_types]

# Use mne.viz.circular_layout to calculate node angles

# Generate the node order list
def generate_node_order(names):
    """Generate a list of node names with suffixes to handle duplicates"""
    name_counts = defaultdict(int)
    node_order = []

    for name in names:
        count = name_counts[name]
        if count == 0:
            # First occurrence, no suffix
            node_order.append(name)
        else:
            # Duplicate name, add suffix (a, b, c...)
            suffix = chr(ord('a') + count - 1)
            node_order.append(f"{name}{suffix}")
        name_counts[name] += 1

    return node_order

# Generate the node order
node_order = generate_node_order(node_names)

# Verify there are no duplicate entries in node_order
if len(node_order) != len(set(node_order)):
    print("Warning: Duplicate entries found in node_order!")
else:
    print("All entries in node_order are unique")

# Calculate node angles with a separation between left and right hemispheres
group_boundaries = [0, len(left_nodes)]  # Separate left and right hemispheres
node_angles = circular_layout(
    node_order,
    node_order,
    start_pos=90,
    group_boundaries=group_boundaries,
    group_sep=10,
)

# Create the connectivity matrix
con = hbo_cor_sorted.values

# Create and configure the figure
fig, ax = plt.subplots(figsize=[10,10], subplot_kw=dict(polar=True))

# Plot the connectivity circle graph
rest_chord_grouped = plot_connectivity_circle(
    con=con,
    node_names=node_names,
    colormap="RdBu_r",
    facecolor="white",
    textcolor="black",
    node_angles=node_angles,
    node_colors=node_colors,
    node_edgecolor=node_colors,
    vmax=1,
    vmin=-1,
    linewidth=1,
    colorbar=False,
    padding=0.1,
    colorbar_pos=(0.1, 0.1),
    fig=fig,
    ax=ax,
)    

[ruuskas]

@hasibagen

Could you share a working example including some toy data? It seems to me that in your code the original node_names, which presumably contains the ROI labels with duplicates for each parcel, is left untouched. Instead, you should only keep the middle labels for each ROI and replace the rest with empty strings.

[hasibagen]

@hasibagen

Could you share a working example including some toy data? It seems to me that in your code the original node_names, which presumably contains the ROI labels with duplicates for each parcel, is left untouched. Instead, you should only keep the middle labels for each ROI and replace the rest with empty strings.

@ruuskas
Sorry for the delayed response — I was occupied the past two weeks and missed your earlier message.

Here is my sample data: a 53x53 channel matrix.
Below is the mapping between each channel and its corresponding ROI:

{
  "Left Motor Area": [10, 4, 1],
  "Left Broca's Area": [5, 3, 2, 13, 8, 7],
  "Left Dorsolateral Prefrontal Cortex": [11, 12, 18, 6, 17, 20],
  "Left Ventrolateral Prefrontal Cortex": [9, 21],
  "Left Frontal Pole": [19, 16, 27, 15, 22, 23],
  "Right Motor Area": [52, 47, 40],
  "Right Broca's Area": [50, 49, 44, 53, 51, 46],
  "Right Dorsolateral Prefrontal Cortex": [42, 31, 34, 45, 32, 39],
  "Right Ventrolateral Prefrontal Cortex": [37, 48],
  "Right Frontal Pole": [35, 36, 43, 30, 41, 33]
}

mean_matrix_demo.txt

Feel free to generate random data if that's more convenient for testing.
Looking forward to a better solution — thank you!

[ruuskas]

Hi @hasibagen
I couldn't make the example work with reasonable effort, but perhaps you could try doing what I suggested previously?

It seems to me that in your code the original node_names, which presumably contains the ROI labels with duplicates for each parcel, is left untouched. Instead, you should only keep the middle labels for each ROI and replace the rest with empty strings.