Skip to content

Visualisation

Basic visualization functions

Option Description
title viz.py
authors Guillaume Dumas, Amir Djalovski, Anaël Ayrolles, Florence Brun
date 2020-03-18

bezier_interpolation(t, p0, p1, c0, c1=None)

Calculate points on a cubic Bezier curve for smooth connection visualization.

This function implements cubic Bezier curve interpolation to create smooth curves for visualizing connectivity between electrodes. It's especially useful for creating aesthetically pleasing inter-brain connectivity visualizations.

Parameters

t : float Interpolation parameter between 0 and 1 0 represents the start point, 1 represents the end point

array-like

Starting point coordinates

array-like

Ending point coordinates

array-like

Control point for the starting point

array-like, optional

Control point for the ending point If None, c0 is used for both control points (for intra-brain curves) (default=None)

Returns

array-like Point coordinates on the Bezier curve at parameter t

Notes

The function implements the cubic Bezier formula: B(t) = (1-t)³P₀ + 3(1-t)²t(2P₀-C₀) + 3(1-t)t²(2P₁-C₁) + t³P₁

When visualizing intra-brain connectivity (within one brain), typically c1 is set to None, which makes the curve symmetric.

For inter-brain connectivity, different control points are used to create a curve that properly arcs between the two head models.

Examples

Calculate 10 points along a Bezier curve for smooth connection

points = [] for i in range(10): ... t = i / 9 # 0 to 1 ... point = bezier_interpolation( ... t, ... [0, 0, 0], # start point ... [1, 1, 0], # end point ... [0.5, 0, 0] # control point ... ) ... points.append(point)

get_3d_heads_inter(children=False, child_head=False)

Get vertices and faces for 3D head models in inter-brain configuration.

This function returns the vertices and faces defining two 3D head models positioned facing each other, as needed for inter-brain connectivity visualization.

Parameters

children : bool, optional Whether to use child head model scaling (default=False)

bool, optional

If True and children=True, scales the second head to child size If False and children=True, scales the first head to child size (default=False)

Returns

vertices : np.ndarray Array of shape (n_vertices, 3) containing the 3D coordinates of all vertices from both head models

np.ndarray

Array of shape (n_faces, 4) containing the vertex indices for each face from both head models

Notes

The function: 1. Loads a base head model from an OBJ file included in the package 2. Creates two copies of the model with appropriate scaling 3. Rotates and translates the models to position them facing each other 4. If children=True and child_head=True, applies scaling to make the second head smaller 5. Combines vertices and faces into unified arrays

For the faces array in the second head, vertex indices are offset by the number of vertices in the first head to maintain correct indexing in the combined array.

This function is typically used to provide head models for the viz_3D_inter() visualization function.

Examples

Get vertices and faces for two adult heads

vertices, faces = get_3d_heads_inter() print(f"Number of vertices: {len(vertices)}") print(f"Number of faces: {len(faces)}")

Get vertices and faces for adult and child heads

vertices, faces = get_3d_heads_inter(children=True, child_head=True)

get_3d_heads_intra(children=False, child_head=False)

Get vertices and faces for 3D head models in intra-brain configuration.

This function returns the vertices and faces defining two 3D head models positioned side by side, as needed for intra-brain connectivity visualization.

Parameters

children : bool, optional Whether to use child head model scaling (default=False)

bool, optional

If True and children=True, scales the second head to child size If False and children=True, scales the first head to child size (default=False)

Returns

vertices : np.ndarray Array of shape (n_vertices, 3) containing the 3D coordinates of all vertices from both head models

np.ndarray

Array of shape (n_faces, 4) containing the vertex indices for each face from both head models

Notes

The function: 1. Loads a base head model from an OBJ file included in the package 2. Creates two copies of the model with appropriate scaling 3. Translates the models to position them side by side along the X-axis 4. If children=True and child_head=True, applies scaling to make the second head smaller 5. Combines vertices and faces into unified arrays

Unlike get_3d_heads_inter() which rotates one head to face the other, this function simply positions the heads side by side without rotation. This configuration is appropriate for comparing intra-brain connectivity between participants.

For the faces array in the second head, vertex indices are offset by the number of vertices in the first head to maintain correct indexing in the combined array.

This function is typically used to provide head models for the viz_3D_intra() visualization function.

Examples

Get vertices and faces for two adult heads side by side

vertices, faces = get_3d_heads_intra() print(f"Number of vertices: {len(vertices)}") print(f"Number of faces: {len(faces)}")

Get vertices and faces for adult and child heads side by side

vertices, faces = get_3d_heads_intra(children=True, child_head=True)

plot_2d_topomap_inter(ax, children=False)

Plot 2D head topomap outlines for inter-brain visualizations.

This function draws the head outlines for two participants facing each other in a 2D representation. It creates the basic head shapes including circles for the heads, ellipses for the ears, and polygons for the noses.

Parameters

ax : matplotlib.axes.Axes Matplotlib axis where the topomap will be plotted

bool, optional

Whether to use child head model proportions (default=False) If True, one head will be scaled to child size

Returns

None Plots the head outlines in the provided matplotlib Axes

Notes

The function: 1. Creates head outlines for two facing participants 2. Adds ears and nose features to each head 3. If children=True, scales one head (right side) to child proportions 4. Removes axis ticks and spines for cleaner visualization

This function handles only the head outlines - it does not plot sensors or connectivity. It is typically used as part of a larger visualization function like viz_2D_topomap_inter() which then adds sensors and links.

Key coordinates: - Head centers: [-0.178, 0] and [0.178, 0] - Adult head radius: 0.1 - Child head radius (when children=True): 0.065

Examples

import matplotlib.pyplot as plt

Create a figure

fig, ax = plt.subplots(figsize=(8, 6))

Plot head outlines

plot_2d_topomap_inter(ax, children=False) plt.show()

Plot adult-child head outlines

fig, ax = plt.subplots(figsize=(8, 6)) plot_2d_topomap_inter(ax, children=True) plt.show()

plot_2d_topomap_intra(ax, children=False)

Plot 2D head topomap outlines for intra-brain visualizations.

This function draws the head outlines for two participants positioned side by side in a 2D representation. It creates the basic head shapes including circles for the heads, ellipses for the ears, and polygons for the noses.

Parameters

ax : matplotlib.axes.Axes Matplotlib axis where the topomap will be plotted

bool, optional

Whether to use child head model proportions (default=False) If True, one head will be scaled to child size

Returns

None Plots the head outlines in the provided matplotlib Axes

Notes

The function: 1. Creates head outlines for two participants positioned side by side 2. Adds ears and nose features to each head 3. If children=True, scales one head (right side) to child proportions 4. Removes axis ticks and spines for cleaner visualization

Unlike plot_2d_topomap_inter() which positions heads facing each other, this function positions heads side by side with noses pointing upward. This orientation is appropriate for intra-brain connectivity visualization where each participant's brain connectivity is analyzed separately.

Key coordinates: - Head centers: [-0.178, 0] and [0.178, 0] - Adult head radius: 0.1 - Child head radius (when children=True): 0.065

Examples

import matplotlib.pyplot as plt

Create a figure

fig, ax = plt.subplots(figsize=(8, 6))

Plot head outlines for intra-brain visualization

plot_2d_topomap_intra(ax, children=False) plt.show()

Plot adult-child head outlines

fig, ax = plt.subplots(figsize=(8, 6)) plot_2d_topomap_intra(ax, children=True) plt.show()

plot_3d_heads(ax, vertices, faces)

Plot 3D head models using vertices and faces.

This function draws 3D head models defined by vertices and faces in a wireframe representation. It plots the edges between vertices that define the faces of the 3D model.

Parameters

ax : matplotlib.axes.Axes Matplotlib 3D axis (created with projection='3d')

np.ndarray

Array of shape (n_vertices, 3) containing the 3D coordinates of vertices

np.ndarray

Array of shape (n_faces, 4) containing the vertex indices for each face Each face is defined by 4 vertex indices

Returns

None Plots the 3D head model wireframe in the provided matplotlib 3D Axes

Notes

The function: 1. Extracts vertex coordinates (with some reordering of x, y, z for correct orientation) 2. For each face, plots lines connecting its vertices 3. Uses a thin gray line style for the wireframe

This function creates a lightweight wireframe representation rather than a fully shaded 3D model, which is sufficient for visualization purposes while maintaining good performance.

The wireframe approach allows electrode and connectivity visualization to be clearly visible in front of or behind the head model.

Examples

import matplotlib.pyplot as plt from mpl_toolkits.mplot3d import Axes3D

Create a 3D figure

fig = plt.figure(figsize=(10, 8)) ax = fig.add_subplot(111, projection='3d')

Get vertices and faces for head models

vertices, faces = get_3d_heads_inter()

Plot 3D heads

plot_3d_heads(ax, vertices, faces) plt.show()

Plot inter-brain connectivity links between two participants in 2D.

This function visualizes the connectivity between electrodes of two participants using bezier curves. Only connections above a specified threshold are displayed, with line color and thickness indicating the strength and sign of the connection.

Parameters

epo1 : mne.Epochs Epochs object for participant 1, containing channel information

mne.Epochs

Epochs object for participant 2, containing channel information

np.ndarray

Connectivity matrix with shape (n_channels_1, n_channels_2) containing connectivity values between all pairs of electrodes across participants

float or str, optional

Threshold for displaying connections (default='auto') - If float: Only connections with absolute value above this threshold are displayed - If 'auto': Threshold is set to the maximum median by column plus the maximum standard error by column

int, optional

Number of steps for bezier curve interpolation (default=10) - If steps < 3: Straight lines are drawn instead of curves

bool, optional

Whether to apply transformations for child head models (default=False)

bool, optional

If True and children=True, treats participant 2 as a child If False and children=True, treats participant 1 as a child (default=False)

Returns

None Plots the connectivity links in the current matplotlib Axes

Notes

The function: 1. Transforms electrode coordinates for proper visualization 2. Calculates control points for bezier curves based on head centers 3. Determines connectivity threshold (automatically or from parameter) 4. Plots connections with: - Red color scale for positive connectivity values - Blue color scale for negative connectivity values - Line thickness proportional to connection strength

This function is typically used as part of a larger visualization function like viz_2D_topomap_inter() rather than called directly.

Examples

import matplotlib.pyplot as plt import numpy as np

Create random connectivity matrix

n_channels = len(epochs_subj1.ch_names) connectivity = np.random.rand(n_channels, n_channels) * 2 - 1 # Values between -1 and 1

Create a figure

fig, ax = plt.subplots(figsize=(10, 8))

Plot 2D connectivity links

plot_links_2d_inter( ... epochs_subj1, ... epochs_subj2, ... connectivity, ... threshold=0.5, ... steps=15 ... ) plt.show()

Plot intra-brain connectivity links for two participants in 2D.

This function visualizes the connectivity within each participant's brain separately using bezier curves. Only connections above a specified threshold are displayed, with line color and thickness indicating the strength and sign of the connection.

Parameters

epo1 : mne.Epochs Epochs object for participant 1, containing channel information

mne.Epochs

Epochs object for participant 2, containing channel information

np.ndarray

Connectivity matrix with shape (n_channels_1, n_channels_1) containing connectivity values between all pairs of electrodes for participant 1

np.ndarray

Connectivity matrix with shape (n_channels_2, n_channels_2) containing connectivity values between all pairs of electrodes for participant 2

float or str, optional

Threshold for displaying connections (default='auto') - If float: Only connections with absolute value above this threshold are displayed - If 'auto': Threshold is set to the maximum of the median values plus the maximum of standard errors across both participants

int, optional

Number of steps for bezier curve interpolation (default=10) - If steps < 3: Straight lines are drawn instead of curves

bool, optional

Whether to apply transformations for child head models (default=False)

bool, optional

If True and children=True, treats participant 2 as a child If False and children=True, treats participant 1 as a child (default=False)

Returns

None Plots the connectivity links in the current matplotlib Axes

Notes

The function: 1. Transforms electrode coordinates for side-by-side visualization 2. Calculates control points for bezier curves based on each head's center 3. Determines connectivity threshold (automatically or from parameter) 4. Plots connections with: - Red color scale for positive connectivity values - Blue color scale for negative connectivity values - Line thickness proportional to connection strength

Unlike plot_links_2d_inter(), this function: - Handles two separate connectivity matrices (one per participant) - Uses the same color scale for both participants for consistent visualization - Uses separate control points for each participant's connectivity curves

This function is typically used as part of a larger visualization function like viz_2D_topomap_intra() rather than called directly.

Examples

import matplotlib.pyplot as plt import numpy as np

Create random connectivity matrices

n_channels_1 = len(epochs_subj1.ch_names) n_channels_2 = len(epochs_subj2.ch_names) connectivity_1 = np.random.rand(n_channels_1, n_channels_1) * 2 - 1 # Values between -1 and 1 connectivity_2 = np.random.rand(n_channels_2, n_channels_2) * 2 - 1 # Values between -1 and 1

Create a figure

fig, ax = plt.subplots(figsize=(10, 8))

Plot 2D intra-brain connectivity links

plot_links_2d_intra( ... epochs_subj1, ... epochs_subj2, ... connectivity_1, ... connectivity_2, ... threshold=0.5, ... steps=15 ... ) plt.show()

Plot inter-brain connectivity links between two participants in 3D.

This function visualizes the connectivity between electrodes of two participants using 3D bezier curves. Only connections above a specified threshold are displayed, with line color and thickness indicating the strength and sign of the connection.

Parameters

ax : matplotlib.axes.Axes Matplotlib 3D axis (created with projection='3d')

mne.Epochs

Epochs object for participant 1, containing channel information

mne.Epochs

Epochs object for participant 2, containing channel information

np.ndarray

Connectivity matrix with shape (n_channels_1, n_channels_2) containing connectivity values between all pairs of electrodes across participants

float or str, optional

Threshold for displaying connections (default='auto') - If float: Only connections with absolute value above this threshold are displayed - If 'auto': Threshold is set to the maximum median by column plus the maximum standard error by column

int, optional

Number of steps for bezier curve interpolation (default=10) - If steps < 3: Straight lines are drawn instead of curves

bool, optional

Whether to apply transformations for child head models (default=False)

bool, optional

If True and children=True, treats participant 2 as a child If False and children=True, treats participant 1 as a child (default=False)

Returns

None Plots the connectivity links in the provided matplotlib 3D Axes

Notes

The function: 1. Transforms electrode coordinates for proper 3D visualization 2. Calculates 3D control points for bezier curves (offset from head centers) 3. Determines connectivity threshold (automatically or from parameter) 4. Plots 3D connections with: - Red color scale for positive connectivity values - Blue color scale for negative connectivity values - Line thickness proportional to connection strength

This function is similar to plot_links_2d_inter() but works in 3D space. It is typically used as part of a larger visualization function like viz_3D_inter() rather than called directly.

Examples

import matplotlib.pyplot as plt from mpl_toolkits.mplot3d import Axes3D import numpy as np

Create random connectivity matrix

n_channels = len(epochs_subj1.ch_names) connectivity = np.random.rand(n_channels, n_channels) * 2 - 1 # Values between -1 and 1

Create a 3D figure

fig = plt.figure(figsize=(10, 8)) ax = fig.add_subplot(111, projection='3d')

Plot 3D connectivity links

plot_links_3d_inter( ... ax, ... epochs_subj1, ... epochs_subj2, ... connectivity, ... threshold=0.5, ... steps=15 ... ) plt.show()

Plot intra-brain connectivity links for two participants in 3D.

This function visualizes the connectivity within each participant's brain separately using 3D bezier curves. Only connections above a specified threshold are displayed, with line color and thickness indicating the strength and sign of the connection.

Parameters

ax : matplotlib.axes.Axes Matplotlib 3D axis (created with projection='3d')

mne.Epochs

Epochs object for participant 1, containing channel information

mne.Epochs

Epochs object for participant 2, containing channel information

np.ndarray

Connectivity matrix with shape (n_channels_1, n_channels_1) containing connectivity values between all pairs of electrodes for participant 1

np.ndarray

Connectivity matrix with shape (n_channels_2, n_channels_2) containing connectivity values between all pairs of electrodes for participant 2

float or str, optional

Threshold for displaying connections (default='auto') - If float: Only connections with absolute value above this threshold are displayed - If 'auto': Threshold is set to the maximum of the median values plus the maximum of standard errors across both participants

int, optional

Number of steps for bezier curve interpolation (default=10) - If steps < 3: Straight lines are drawn instead of curves

bool, optional

Whether to apply transformations for child head models (default=False)

bool, optional

If True and children=True, treats participant 2 as a child If False and children=True, treats participant 1 as a child (default=False)

Returns

None Plots the connectivity links in the provided matplotlib 3D Axes

Notes

The function: 1. Transforms electrode coordinates for side-by-side 3D visualization 2. Calculates 3D control points for bezier curves (offset vertically from head centers) 3. Determines connectivity threshold (automatically or from parameter) 4. Plots 3D connections with: - Red color scale for positive connectivity values - Blue color scale for negative connectivity values - Line thickness proportional to connection strength

Unlike plot_links_3d_inter(), this function: - Handles two separate connectivity matrices (one per participant) - Uses the same color scale for both participants for consistent visualization - Uses separate control points for each participant's connectivity curves

This function is typically used as part of a larger visualization function like viz_3D_intra() rather than called directly.

Examples

import matplotlib.pyplot as plt from mpl_toolkits.mplot3d import Axes3D import numpy as np

Create random connectivity matrices

n_channels_1 = len(epochs_subj1.ch_names) n_channels_2 = len(epochs_subj2.ch_names) connectivity_1 = np.random.rand(n_channels_1, n_channels_1) * 2 - 1 # Values between -1 and 1 connectivity_2 = np.random.rand(n_channels_2, n_channels_2) * 2 - 1 # Values between -1 and 1

Create a 3D figure

fig = plt.figure(figsize=(10, 8)) ax = fig.add_subplot(111, projection='3d')

Plot 3D intra-brain connectivity links

plot_links_3d_intra( ... ax, ... epochs_subj1, ... epochs_subj2, ... connectivity_1, ... connectivity_2, ... threshold=0.5, ... steps=15 ... ) plt.show()

plot_sensors_2d_inter(epo1, epo2, lab=True, children=False, child_head=False)

Plot sensors from two participants in 2D for inter-brain visualizations.

This function plots the sensor positions from two participants in a 2D view, with special markers for bad channels. It's typically used as part of inter-brain connectivity visualizations.

Parameters

epo1 : mne.Epochs Epochs object for participant 1, containing channel information

mne.Epochs

Epochs object for participant 2, containing channel information

bool, optional

Whether to plot channel labels (default=True)

bool, optional

Whether to apply transformations for child head models (default=False)

bool, optional

If True and children=True, treats participant 2 as a child If False and children=True, treats participant 1 as a child (default=False)

Returns

None Plots the sensors in the current matplotlib Axes

Notes

The function: 1. Extracts electrode coordinates from the Epochs objects 2. Transforms them for proper visualization using transform() 3. Plots each sensor with: - Circle markers for good channels - X markers for bad channels (those in info['bads']) 4. Optionally adds channel labels

This function is typically used as part of a larger visualization function like viz_2D_topomap_inter() rather than called directly.

Examples

import matplotlib.pyplot as plt

Create a figure

fig, ax = plt.subplots()

Plot sensors

plot_sensors_2d_inter(epochs_subj1, epochs_subj2, lab=True) plt.show()

plot_sensors_2d_intra(epo1, epo2, lab=False, children=False, child_head=False)

Plot sensors from two participants in 2D for intra-brain visualizations.

This function plots the sensor positions from two participants for visualizing intra-brain connectivity (connectivity within each brain separately). The sensors are positioned side by side rather than facing each other as in inter-brain plots.

Parameters

epo1 : mne.Epochs Epochs object for participant 1, containing channel information

mne.Epochs

Epochs object for participant 2, containing channel information

bool, optional

Whether to plot channel labels (default=False)

bool, optional

Whether to apply transformations for child head models (default=False)

bool, optional

If True and children=True, treats participant 2 as a child If False and children=True, treats participant 1 as a child (default=False)

Returns

None Plots the sensors in the current matplotlib Axes

Notes

The function: 1. Extracts electrode coordinates from the Epochs objects 2. Transforms them for side-by-side visualization using transform_2d_intra() 3. Plots each sensor with: - Circle markers for good channels - X markers for bad channels (those in info['bads']) 4. Optionally adds channel labels

Unlike plot_sensors_2d_inter(), this function positions the heads side by side rather than facing each other, which is appropriate for visualizing intra-brain connectivity where comparisons are made between participants.

Examples

import matplotlib.pyplot as plt

Create a figure

fig, ax = plt.subplots()

Plot sensors for intra-brain visualization

plot_sensors_2d_intra(epochs_subj1, epochs_subj2, lab=True) plt.show()

plot_sensors_3d_inter(ax, epo1, epo2, lab=False, children=False, child_head=False)

Plot sensors from two participants in 3D for inter-brain visualizations.

This function plots the sensor positions from two participants in a 3D view, with special markers for bad channels. It's typically used as part of inter-brain connectivity 3D visualizations.

Parameters

ax : matplotlib.axes.Axes Matplotlib 3D axis (created with projection='3d')

mne.Epochs

Epochs object for participant 1, containing channel information

mne.Epochs

Epochs object for participant 2, containing channel information

bool, optional

Whether to plot channel labels (default=False)

bool, optional

Whether to apply transformations for child head models (default=False)

bool, optional

If True and children=True, treats participant 2 as a child If False and children=True, treats participant 1 as a child (default=False)

Returns

None Plots the sensors in the provided matplotlib 3D Axes

Notes

The function: 1. Extracts electrode coordinates from the Epochs objects 2. Transforms them for proper 3D visualization using transform() 3. Plots each sensor in 3D space with: - Sphere markers for good channels - X markers for bad channels (those in info['bads']) 4. Optionally adds channel labels in 3D space

This function is typically used as part of a larger visualization function like viz_3D_inter() rather than called directly.

The main difference from the 2D equivalent is that this function requires a 3D axis and uses 3D scatter plots instead of 2D plots.

Examples

import matplotlib.pyplot as plt from mpl_toolkits.mplot3d import Axes3D

Create a 3D figure

fig = plt.figure() ax = fig.add_subplot(111, projection='3d')

Plot sensors in 3D

plot_sensors_3d_inter(ax, epochs_subj1, epochs_subj2, lab=True) plt.show()

plot_sensors_3d_intra(ax, epo1, epo2, lab=False, children=False, child_head=False)

Plot sensors from two participants in 3D for intra-brain visualizations.

This function plots the sensor positions from two participants in a 3D view for visualizing intra-brain connectivity. The sensors are positioned side by side rather than facing each other as in inter-brain plots.

Parameters

ax : matplotlib.axes.Axes Matplotlib 3D axis (created with projection='3d')

mne.Epochs

Epochs object for participant 1, containing channel information

mne.Epochs

Epochs object for participant 2, containing channel information

bool, optional

Whether to plot channel labels (default=False)

bool, optional

Whether to apply transformations for child head models (default=False)

bool, optional

If True and children=True, treats participant 2 as a child If False and children=True, treats participant 1 as a child (default=False)

Returns

None Plots the sensors in the provided matplotlib 3D Axes

Notes

The function: 1. Extracts electrode coordinates from the Epochs objects 2. Transforms them for side-by-side 3D visualization using transform() 3. Plots each sensor in 3D space with: - Sphere markers for good channels - X markers for bad channels (those in info['bads']) 4. Optionally adds channel labels in 3D space

Unlike plot_sensors_3d_inter(), this function positions the heads side by side rather than facing each other, which is appropriate for visualizing intra-brain connectivity where comparisons are made between participants.

Examples

import matplotlib.pyplot as plt from mpl_toolkits.mplot3d import Axes3D

Create a 3D figure

fig = plt.figure() ax = fig.add_subplot(111, projection='3d')

Plot sensors in 3D for intra-brain visualization

plot_sensors_3d_intra(ax, epochs_subj1, epochs_subj2, lab=True) plt.show()

plot_significant_sensors(T_obs_plot, epochs, significant=None)

Plot statistical values on a topographic map for significant sensors.

This function visualizes the results of statistical tests (such as t-tests or cluster-corrected t-tests) performed on sensor data across participants or conditions. It creates a topographic plot with statistical values displayed for significant sensors.

Parameters

T_obs_plot : np.ndarray Array of shape (n_sensors,) containing the statistical values (T or F statistics) to plot for significant sensors. Typically, this array has zeros for non-significant sensors and the actual statistical values for significant ones.

mne.Epochs

Epochs object to get channel positions from

np.ndarray, optional

Optional mask array of shape (n_sensors,) where non-zero values indicate significant sensors to highlight (default=None)

Returns

None Creates a topographic plot of the statistical values

Notes

The function: 1. Extracts sensor positions from the epochs object 2. Determines appropriate color scale limits (symmetric around zero) 3. Creates a topographic plot using MNE's plot_topomap function 4. If significant mask is provided, adds white circles around the significant sensors

This function is designed for single-participant statistical visualization. For inter-brain connectivity statistics, use the plot_links_* functions instead.

Examples

import numpy as np import mne

Create array with statistical values (zeros for non-significant sensors)

n_channels = len(epochs.ch_names)

Example: t-values for a statistical test, with zeros for non-significant channels

t_values = np.zeros(n_channels)

Set some random significant values

significant_indices = [3, 7, 12, 20, 25] t_values[significant_indices] = np.random.randn(len(significant_indices)) * 3

Plot the significant sensors

plot_significant_sensors(t_values, epochs)

Alternatively, use a significance mask

significance_mask = np.zeros(n_channels) significance_mask[significant_indices] = 1 plot_significant_sensors(t_values, epochs, significant=significance_mask)

plot_xwt(sig1, sig2, sfreq, freqs, time, analysis, figsize=(30, 8), tmin=0, x_units=100)

Plot the results of Cross-Wavelet Transform (XWT) analysis.

This function visualizes time-frequency representations of cross-wavelet transform results between two participants' EEG signals. It can display phase angles, power, or wavelet coherence.

Parameters

sig1 : mne.Epochs EEG data for the first participant

mne.Epochs

EEG data for the second participant

int or float

Sampling frequency of the EEG data in Hz

int, float, or np.ndarray

Frequencies of interest in Hz

int

Time duration of the sample in seconds

str

Type of analysis to visualize, options: - 'phase': Phase angle differences - 'power': Cross-wavelet power - 'wtc': Wavelet coherence

tuple, optional

Figure size in inches (default=(30, 8))

int, optional

Start time for the plot in seconds (default=0)

int or float, optional

Distance between x-axis ticks in data points (default=100)

Returns

fig : matplotlib.figure.Figure The matplotlib Figure object containing the visualization

Notes

The function: 1. Calculates the appropriate time and frequency axes for plotting 2. Computes the cone of influence (COI) to indicate regions with edge effects 3. Creates a colormap-based visualization of the XWT results 4. Masks regions outside the COI with hatching to indicate less reliable values

Different colormaps are used based on the analysis type: - 'phase': 'hsv' colormap for phase angles - 'power': 'viridis' colormap for power values - 'wtc': 'plasma' colormap for coherence values

This function is not meant to be called independently but is usually called from higher-level functions like plot_xwt_crosspower or plot_xwt_phase_angle.

Examples

Plot cross-wavelet power

fig = plot_xwt( ... epochs_subj1, ... epochs_subj2, ... sfreq=256, ... freqs=np.arange(4, 40, 1), # 4-40 Hz ... time=10, # 10 seconds ... analysis='power', ... figsize=(12, 8) ... ) plt.show()

Plot wavelet coherence

fig = plot_xwt( ... epochs_subj1, ... epochs_subj2, ... sfreq=256, ... freqs=np.arange(4, 40, 1), ... time=10, ... analysis='wtc', ... figsize=(12, 8) ... ) plt.show()

transform(locs, traX=0.15, traY=0, traZ=0.5, rotY=np.pi / 2, rotZ=np.pi / 2, children=False, child_head=False)

Apply a series of transformations to 3D coordinates for visualization.

This function transforms electrode coordinates to fit properly into the head models for hyperscanning visualizations. It can adjust for adult or child head sizes and positions.

Parameters

locs : np.ndarray Array of shape (n_sensors, 3) containing the 3D coordinates to transform

float, optional

Translation along X-axis in meters (default=0.15)

float, optional

Translation along Y-axis in meters (default=0)

float, optional

Translation along Z-axis in meters (default=0.5)

float, optional

Rotation around Y-axis in radians (default=π/2)

float, optional

Rotation around Z-axis in radians (default=π/2)

bool, optional

Whether to apply transformations specific to children's head models (default=False)

bool, optional

If True and children=True, apply transformations for a child's head model If False and children=True, apply transformations for an adult's head model with a child (default=False)

Returns

np.ndarray The transformed 3D coordinates with the same shape as input

Notes

The transformation sequence is: 1. Z-axis rotation 2. Scaling (with different factors for children) 3. X/Y/Z translations 4. Y-axis rotation

When using with hyperscanning visualization functions, this transformation is typically applied with different parameters to position each participant's sensors appropriately in the visualization.

Examples

Transform adult electrode positions

transformed_locs = transform(electrode_positions, traX=-0.17, rotZ=-np.pi/2)

Transform child electrode positions

child_locs = transform( ... electrode_positions, ... traX=0.17, ... rotZ=np.pi/2, ... children=True, ... child_head=True ... )

transform_2d_intra(locs, traX=0.15, traY=0, traZ=0, rotZ=np.pi / 2, children=False, child_head=False)

Transform electrode coordinates for 2D intra-brain visualizations.

This function applies transformations to electrode coordinates for 2D visualizations of intra-brain connectivity. It's a simplified version of the transform() function with fewer rotations.

Parameters

locs : np.ndarray Array of shape (n_sensors, 3) containing the 3D coordinates to transform

float, optional

Translation along X-axis in meters (default=0.15)

float, optional

Translation along Y-axis in meters (default=0)

float, optional

Translation along Z-axis in meters (default=0)

float, optional

Rotation around Z-axis in radians (default=π/2)

bool, optional

Whether to apply transformations specific to children's head models (default=False)

bool, optional

If True and children=True, apply transformations for a child's head model If False and children=True, apply transformations for an adult's head model with a child (default=False)

Returns

np.ndarray The transformed 3D coordinates with the same shape as input

Notes

This function is primarily used for 2D intra-brain connectivity visualizations where the full 3D rotation from transform() is not needed.

The main differences from transform() are: 1. No Y-axis rotation 2. Simpler scaling for the Z dimension

Examples

Transform adult electrode positions for 2D intra-brain visualization

transformed_locs = transform_2d_intra( ... electrode_positions, ... traX=-0.178, ... traY=0.012 ... )

Transform child electrode positions

child_locs = transform_2d_intra( ... electrode_positions, ... traX=0.178, ... traY=0.012, ... children=True, ... child_head=True ... )

viz_2D_headmodel_inter(epo1, epo2, C, threshold=0.95, steps=10, lab=True, children=False, child_head=False)

Create a complete 2D head model visualization with inter-brain connectivity.

This function provides a high-level interface for creating a 2D visualization of two head models with sensors and inter-brain connectivity links.

Parameters

epo1 : mne.Epochs Epochs object for participant 1, containing channel information

mne.Epochs

Epochs object for participant 2, containing channel information

np.ndarray

Connectivity matrix with shape (n_channels_1, n_channels_2) containing connectivity values between all pairs of electrodes across participants

float, optional

Threshold for displaying connections (default=0.95) Only connections with absolute value above this threshold are displayed

int, optional

Number of steps for bezier curve interpolation (default=10) If steps < 3, straight lines are drawn instead of curves

bool, optional

Whether to plot channel labels (default=True)

bool, optional

Whether to apply transformations for child head models (default=False)

bool, optional

If True and children=True, treats participant 2 as a child If False and children=True, treats participant 1 as a child (default=False)

Returns

ax : matplotlib.axes.Axes The matplotlib Axes object containing the visualization

Notes

This function combines several lower-level visualization functions: 1. Creates a figure and axis with appropriate settings 2. Generates 3D head models and applies a camera transformation for 2D view 3. Plots sensors using plot_sensors_2d_inter() 4. Plots connectivity links using plot_links_2d_inter()

Unlike viz_2D_topomap_inter() which uses simpler 2D head outlines, this function uses a 3D head model rendered in a 2D view, which can provide a more realistic representation.

Examples

import numpy as np

Create random connectivity matrix

n_channels_1 = len(epochs_subj1.ch_names) n_channels_2 = len(epochs_subj2.ch_names) connectivity = np.random.rand(n_channels_1, n_channels_2) * 2 - 1 # Values between -1 and 1

Create visualization

ax = viz_2D_headmodel_inter( ... epochs_subj1, ... epochs_subj2, ... connectivity, ... threshold=0.7, ... steps=15, ... lab=True ... )

Add a title

ax.set_title('Inter-brain connectivity') plt.show()

viz_2D_topomap_inter(epo1, epo2, C, threshold=0.95, steps=10, lab=False, children=False, child_head=False)

Create a 2D topographic map visualization with inter-brain connectivity.

This function provides a high-level interface for creating a 2D topographic visualization of two head outlines with sensors and inter-brain connectivity links.

Parameters

epo1 : mne.Epochs Epochs object for participant 1, containing channel information

mne.Epochs

Epochs object for participant 2, containing channel information

np.ndarray

Connectivity matrix with shape (n_channels_1, n_channels_2) containing connectivity values between all pairs of electrodes across participants

float, optional

Threshold for displaying connections (default=0.95) Only connections with absolute value above this threshold are displayed

int, optional

Number of steps for bezier curve interpolation (default=10) If steps < 3, straight lines are drawn instead of curves

bool, optional

Whether to plot channel labels (default=False)

bool, optional

Whether to apply transformations for child head models (default=False)

bool, optional

If True and children=True, treats participant 2 as a child If False and children=True, treats participant 1 as a child (default=False)

Returns

ax : matplotlib.axes.Axes The matplotlib Axes object containing the visualization

Notes

This function combines several lower-level visualization functions: 1. Creates a figure and axis with appropriate settings 2. Draws 2D head outlines using plot_2d_topomap_inter() 3. Plots sensors using plot_sensors_2d_inter() 4. Plots connectivity links using plot_links_2d_inter()

This function uses simpler 2D head outlines compared to viz_2D_headmodel_inter() which uses a projected 3D model. The 2D outlines are computationally lighter and may be preferred for quick visualizations or publications.

Examples

import numpy as np

Create random connectivity matrix

n_channels_1 = len(epochs_subj1.ch_names) n_channels_2 = len(epochs_subj2.ch_names) connectivity = np.random.rand(n_channels_1, n_channels_2) * 2 - 1 # Values between -1 and 1

Create visualization

ax = viz_2D_topomap_inter( ... epochs_subj1, ... epochs_subj2, ... connectivity, ... threshold=0.7, ... steps=15, ... lab=True ... )

Add a title

ax.set_title('Inter-brain connectivity') plt.show()

viz_2D_topomap_intra(epo1, epo2, C1, C2, threshold=0.95, steps=2, lab=False, children=False, child_head=False)

Create a 2D topographic map visualization with intra-brain connectivity.

This function provides a high-level interface for creating a 2D topographic visualization of two head outlines side by side, displaying intra-brain connectivity within each participant separately.

Parameters

epo1 : mne.Epochs Epochs object for participant 1, containing channel information

mne.Epochs

Epochs object for participant 2, containing channel information

np.ndarray

Connectivity matrix with shape (n_channels_1, n_channels_1) containing connectivity values between pairs of electrodes for participant 1

np.ndarray

Connectivity matrix with shape (n_channels_2, n_channels_2) containing connectivity values between pairs of electrodes for participant 2

float, optional

Threshold for displaying connections (default=0.95) Only connections with absolute value above this threshold are displayed

int, optional

Number of steps for bezier curve interpolation (default=2) If steps < 3, straight lines are drawn instead of curves

bool, optional

Whether to plot channel labels (default=False)

bool, optional

Whether to apply transformations for child head models (default=False)

bool, optional

If True and children=True, treats participant 2 as a child If False and children=True, treats participant 1 as a child (default=False)

Returns

ax : matplotlib.axes.Axes The matplotlib Axes object containing the visualization

Notes

This function combines several lower-level visualization functions: 1. Creates a figure and axis with appropriate settings 2. Draws 2D head outlines using plot_2d_topomap_intra() 3. Plots sensors using plot_sensors_2d_intra() 4. Plots connectivity links using plot_links_2d_intra()

Unlike viz_2D_topomap_inter() which visualizes connections between participants, this function displays connections within each participant's brain separately, allowing for comparison of intra-brain connectivity patterns.

Examples

import numpy as np

Create random connectivity matrices

n_channels_1 = len(epochs_subj1.ch_names) n_channels_2 = len(epochs_subj2.ch_names) connectivity_1 = np.random.rand(n_channels_1, n_channels_1) * 2 - 1 # Values between -1 and 1 connectivity_2 = np.random.rand(n_channels_2, n_channels_2) * 2 - 1 # Values between -1 and 1

Create visualization

ax = viz_2D_topomap_intra( ... epochs_subj1, ... epochs_subj2, ... connectivity_1, ... connectivity_2, ... threshold=0.7, ... steps=10, ... lab=True ... )

Add a title

ax.set_title('Intra-brain connectivity comparison') plt.show()

viz_3D_inter(epo1, epo2, C, threshold=0.95, steps=10, lab=False, children=False, child_head=False)

Create a complete 3D visualization with inter-brain connectivity.

This function provides a high-level interface for creating a 3D visualization of two head models with sensors and inter-brain connectivity links.

Parameters

epo1 : mne.Epochs Epochs object for participant 1, containing channel information

mne.Epochs

Epochs object for participant 2, containing channel information

np.ndarray

Connectivity matrix with shape (n_channels_1, n_channels_2) containing connectivity values between all pairs of electrodes across participants

float, optional

Threshold for displaying connections (default=0.95) Only connections with absolute value above this threshold are displayed

int, optional

Number of steps for bezier curve interpolation (default=10) If steps < 3, straight lines are drawn instead of curves

bool, optional

Whether to plot channel labels (default=False)

bool, optional

Whether to apply transformations for child head models (default=False)

bool, optional

If True and children=True, treats participant 2 as a child If False and children=True, treats participant 1 as a child (default=False)

Returns

ax : matplotlib.axes.Axes The matplotlib 3D Axes object containing the visualization

Notes

This function combines several lower-level visualization functions: 1. Creates a 3D figure and axis with appropriate settings 2. Gets 3D head model vertices and faces using get_3d_heads_inter() 3. Plots 3D head models using plot_3d_heads() 4. Plots sensors using plot_sensors_3d_inter() 5. Plots connectivity links using plot_links_3d_inter()

The 3D visualization allows for interactive rotation and zoom, providing a more comprehensive view of the connectivity patterns compared to 2D visualizations.

Examples

import numpy as np

Create random connectivity matrix

n_channels_1 = len(epochs_subj1.ch_names) n_channels_2 = len(epochs_subj2.ch_names) connectivity = np.random.rand(n_channels_1, n_channels_2) * 2 - 1 # Values between -1 and 1

Create 3D visualization

ax = viz_3D_inter( ... epochs_subj1, ... epochs_subj2, ... connectivity, ... threshold=0.7, ... steps=15, ... lab=False ... ) plt.show()

viz_3D_intra(epo1, epo2, C1, C2, threshold=0.95, steps=10, lab=False, children=False, child_head=False)

Create a complete 3D visualization with intra-brain connectivity.

This function provides a high-level interface for creating a 3D visualization of two head models side by side, displaying intra-brain connectivity within each participant separately.

Parameters

epo1 : mne.Epochs Epochs object for participant 1, containing channel information

mne.Epochs

Epochs object for participant 2, containing channel information

np.ndarray

Connectivity matrix with shape (n_channels_1, n_channels_1) containing connectivity values between pairs of electrodes for participant 1

np.ndarray

Connectivity matrix with shape (n_channels_2, n_channels_2) containing connectivity values between pairs of electrodes for participant 2

float, optional

Threshold for displaying connections (default=0.95) Only connections with absolute value above this threshold are displayed

int, optional

Number of steps for bezier curve interpolation (default=10) If steps < 3, straight lines are drawn instead of curves

bool, optional

Whether to plot channel labels (default=False)

bool, optional

Whether to apply transformations for child head models (default=False)

bool, optional

If True and children=True, treats participant 2 as a child If False and children=True, treats participant 1 as a child (default=False)

Returns

ax : matplotlib.axes.Axes The matplotlib 3D Axes object containing the visualization

Notes

This function combines several lower-level visualization functions: 1. Creates a 3D figure and axis with appropriate settings 2. Gets 3D head model vertices and faces using get_3d_heads_intra() 3. Plots 3D head models using plot_3d_heads() 4. Plots sensors using plot_sensors_3d_intra() 5. Plots connectivity links using plot_links_3d_intra()

Unlike viz_3D_inter() which visualizes connections between participants, this function displays connections within each participant's brain separately, allowing for comparison of intra-brain connectivity patterns in 3D.

Examples

import numpy as np

Create random connectivity matrices

n_channels_1 = len(epochs_subj1.ch_names) n_channels_2 = len(epochs_subj2.ch_names) connectivity_1 = np.random.rand(n_channels_1, n_channels_1) * 2 - 1 # Values between -1 and 1 connectivity_2 = np.random.rand(n_channels_2, n_channels_2) * 2 - 1 # Values between -1 and 1

Create 3D visualization

ax = viz_3D_intra( ... epochs_subj1, ... epochs_subj2, ... connectivity_1, ... connectivity_2, ... threshold=0.7, ... steps=15, ... lab=False ... ) plt.show()