medusa.plots package

Submodules

medusa.plots.brain_plots module

medusa.plots.erp_plots module

Created on Friday October 01 10:09:11 2021

In this module you will find useful functions and classes to plot event-related potentials (ERPs). This module is not finished, it has numerous improvement points but can be useful for a quick plot. Enjoy!

@author: Eduardo Santamaría-Vázquez

medusa.plots.erp_plots.compute_dev_epochs(epochs, measure='C95')[source]

Computes the error of a 2D data.

Parameters

epochs (ndarray) – Data being plotted, with dimensions [observations x signal]
error (basestring) – Type of error being plotted (mean+error, mean-error), which can be: - ‘std’: standard deviation - ‘sem’: standard error mean - ‘var’: variance - Confidence interval: For this error, the measure parameter must be constituted by ‘c’ and the desired percentile. E.g. ‘c95’ for the 95% confidence interval, ‘c90’ for the 90%, ‘c99’ for the 99%, and so on.

Returns

pos_deviation (ndarray) – 1D vector containing the positive deviation measure [1 x signal].
neg_deviation (ndarray) – 1D vector containing the negative deviation measure [1 x signal].

medusa.plots.erp_plots.plot_erp(erp_epochs, noerp_epochs, channel, window=(0, 1000), error_measure='C95', plot=True)[source]

Function designed to quickly plot an ERP with 95% confidence interval. It does offer limited functions that will be improved in the future.

TODO: a lot of things, very basic functionality

Parameters

erp_epochs (numpy.ndarray) – Epochs that contain ERPs (go epochs)
noerp_epochs (numpy.ndarray) – Epochs that do not contain ERPs (nogo epochs)
channel (int) – Channel index to plot
window (list) – List with the lower and upper window time in milliseconds
error_measure (str) – Error measure (default: “C95” or 95% confidence interval). Check parameters of function compute_dev_epochs() for further information.
plot (bool) – Set to True to plot the ERP

Returns

erp_mean (numpy.ndarray) – ERP activity (mean of the go epochs)
erp_dev (numpy.ndarray) – Error measure across observations for ERP activity
noerp_mean (numpy.ndarray) – Non-ERP activity (mean of the nogo epochs)
noerp_dev (numpy.ndarray) – Error measure across observations for non-ERP activity

medusa.plots.erp_plots.plot_erp_from_erp_speller_runs(erp_speller_runs, channel, window=(0, 1000), plot=True)[source]

medusa.plots.generic_plots module

Created on Tue Sep 27 10:45:15 2022

@author: Víctor Martínez-Cagigal

medusa.plots.generic_plots.shaded_plot(data, error='std', times=None, axes=None)[source]

This function plots the mean and the shaded error of a time series.

Parameters

data (2D numpy.ndarray) – Data being plotted, with dimensions [observations x signal]
error (basestring) – Type of error being plotted (mean+error, mean-error), which can be: - ‘std’: standard deviation - ‘sem’: standard error mean - ‘var’: variance - ‘c95’: 95% confidence interval (assuming normality)
times (numpy.ndarray) – Timestamps of the time series.
axes (matplotlib.pyplot.axes) – If a matplotlib axes are specified, the plot is displayed inside it. Otherwise, the plot will generate a new figure.

Returns

axes

Return type

matplotlib.pyplot.axes

medusa.plots.head_plots module

In this module, you will find some functions to represent connectivity graphs and topographic plots over a 2D head model. Enjoy!

class medusa.plots.head_plots.ConnectivityPlot[source]

Bases: object

Helper function to use a Connectivity topographic plot.

Parameters

axes (matplotlib.Axes.axes) – Matplotlib axes in which the head will be displayed into.
channel_set (eeg_standards.EEGChannelSet) – EEG channel set.
**kwargs (**dict() (Optional)) – Settings for the topoplot. Refer to plot_topography and plot_head to check the different parameters.

__init__(axes, channel_set, **kwargs)[source]

clear()[source]: This method clears all the handles.

update(adj_mat)[source]

Use this function to update the topographic plot in real-time.

Parameters

adj_mat: numpy.ndarray: Numpy array with the connectivity values. It must be one of the following dimensions [n_channels, n_channels]

class medusa.plots.head_plots.TopographicPlot[source]

Bases: object

Helper function to use a Topographic plot.

Parameters

axes (matplotlib.Axes.axes) – Matplotlib axes in which the head will be displayed into.
channel_set (eeg_standards.EEGChannelSet) – EEG channel set.
**kwargs (**dict() (Optional)) – Settings for the topoplot. Refer to plot_topography and plot_head to check the different parameters.

__init__(axes, channel_set, **kwargs)[source]

clear()[source]: This method clears all the handles.

update(values)[source]

Use this function to update the topographic plot in real-time.

Parameters: values (list or numpy.ndarray) – Numpy array with the channel values. It must be of the same size as channels.

medusa.plots.head_plots.plot_connectivity(adj_mat, axes, channel_set, cmap='bwr', clim=None, **kwargs)[source]

This function depicts a connectivity map over the desired channel locations.

Parameters

adj_mat (numpy.ndarray) – Numpy array with the connectivity values. It must be one of the following dimensions [n_channels, n_channels]
axes (matplotlib.Axes.axes) – Matplotlib axes in which the head will be displayed into.
channel_set (eeg_standards.EEGChannelSet) – EEG channel set.
cmap (str (Optional)) – Matplotlib colormap.
clim (list or None (Optional)) – Color bar limits. Index 0 contain the lower limit, whereas index 1 must contain the upper limit. if None, min and max values are used.

Returns

handles – Dict with all the handles that have been added to the axes.

Return type

dict

medusa.plots.head_plots.plot_head(axes, channel_set, head_radius=0.76266, head_line_width=4.0, head_skin_color='#E8BEAC', plot_channel_labels=False, plot_channel_points=True, channel_radius_size=None, **kwargs)[source]

This function depicts a two-dimensional head diagram.

Parameters

axes (matplotlib.Axes.axes) – Matplotlib axes in which the head will be displayed into.
channel_set (eeg_standards.EEGChannelSet) – EEG channel set.
head_radius (float (Optional)) – Head radius. Default is 0.7266, coinciding with FPz. The nasion and inion are located at r=1.0
head_line_width (float (Optional)) – Line width for the head, ears and nose.
head_skin_color (basestring or None (Optional)) – If None, skin will be transparent. Otherwise, skin will be colored.
plot_channel_labels (bool (Optional)) – Boolean that controls if the channel labels should be plotted (default: False)
plot_channel_points (bool (Optional)) –

Boolean that controls if the channel points should be plotted (default:
True)
channel_radius_size (float (Optional)) – Channels can be surrounded by a circunference to ease their visualization. Use this parameter to control the radius of the circle. If 0, no circle will be used; if None, an automatic value will be computed considering the minimum distance between channels (default: None)

Returns

handles – Dict with all the handles that have been added to the axes

Return type

dict

medusa.plots.head_plots.plot_topography(values, axes, channel_set, extra_radius=0.29, interp_neighbors=3, interp_points=500, interp_contour_width=0.8, cmap='YlGnBu_r', clim=None, **kwargs)[source]

This function depicts a topographic map of the scalp over the desired channel locations.

Parameters

values (list or numpy.ndarray) – Numpy array with the channel values. It must be of the same size as channels.
axes (matplotlib.Axes.axes) – Matplotlib axes in which the head will be displayed into.
channel_set (eeg_standards.EEGChannelSet) – EEG channel set
extra_radius (float (Optional)) – Extra radius of the plot surface.
interp_neighbors (int (Optional)) – Number of nearest neighbors for interpolation.
interp_points (int (Optional)) – No. interpolation points. The lower N, the lower resolution and faster computation (default: 500)
interp_contour_width (float or None (Optional)) – Line width of the contour lines. If None, no contour lines will be plotted (default: 0.8).
cmap (str (Optional)) – Matplotlib colormap.
clim (tuple or None (Optional)) – Color bar limits. Index 0 contain the lower limit, whereas index 1 must contain the upper limit. if None, min and max values are used.

Returns

handles – Dict with all the handles that have been added to the axes.

Return type

dict

medusa.plots.mi_plots module

class medusa.plots.mi_plots.MIPlots[source]

Bases: object

__init__()[source]

plot_erd_ers_freq(ch_to_plot, axs_to_plot=None, f_lims=(5, 40), f_sel=(8, 13), t_trial_window=(1000, 6000), welch_seg_len_pct=50, welch_overlap_pct=75, mov_mean_hz=0)[source]

Plots the ERD/ERS in the frequency domain.

Parameters

ch_to_plot (list(basestring)) – List of channels to be plotted (commonly: [“C3”, “C4”])
axs_to_plot (list(dict())) –
List of dictionaries. Each dictionary belongs to each channel to be plotted, thus the number of dictionaries must be equal to len(ch_to_plot). Dictionary must have the following items:
- ”freq” (matplotib.axes): axes for the PSD plot.
- ”r2” (matplotlib.axes): axes for the statistic r2 plot.
- ”pval” (matplotlib.axes): axes for the p-values plot (
p-values are computed using a Wilcoxon signed-rank test and correcting FDR using Benjamini-Hochberg).
f_lims (tuple()) – Tuple containing the frequency limits of the PSD (i.e., the filtering cutoff)
f_sel (tuple()) – Tuple containing the desired frequency band for visualization purposes (it will be indicated with a shaded area)
t_trial_window (tuple()) – Trial window to be considered in ms.
welch_seg_len_pct (int) – Percentage of the trial window used to extract segments for the PSD Welch estimation
welch_overlap_pct (int) – Percentage of the segment length used to overlap segments.
mov_mean_hz (int) – Resolution (Hz/bin) desired after a moving average filter (use 0 to avoid the smooth filtering).

Returns

Modified axes

Return type

matplotlib.axes

plot_erd_ers_r2_topo(ch_to_plot, ax_to_plot=None, welch_seg_len_pct=50, welch_overlap_pct=75)[source]

plot_erd_ers_time(ch_to_plot, axs_to_plot=None, t_trial_window=(1000, 6000), t_reference_window=(- 1000, 0), f_cutoff=(8, 13), mov_mean_ms=1000)[source]

Plots the ERD/ERS in the temporal domain.

Parameters

ch_to_plot (list(basestring)) – List of channels to be plotted (commonly: [“C3”, “C4”]).
axs_to_plot (list(dict())) –
List of dictionaries. Each dictionary belongs to each channel to be plotted, thus the number of dictionaries must be equal to len(ch_to_plot). Dictionary must have the following items:
- ”freq” (matplotib.axes): axes for the PSD plot.
- ”r2” (matplotlib.axes): axes for the statistic r2 plot.
- ”pval” (matplotlib.axes): axes for the p-values plot (
p-values are computed using a Wilcoxon signed-rank test and correcting FDR using Benjamini-Hochberg).
t_trial_window (tuple()) – Trial window to be considered in ms (relative to the onset).
t_reference_window (tuple()) – Reference window to be considered in ms (relative to the onset).
f_cutoff (tuple()) – Filter cutoff to select a desired band
mov_mean_ms (int) – Resolution (ms/bin) desired after a moving average filter (use 0 to avoid the smooth filtering).

Returns

Modified axes

Return type

matplotlib.axes

plot_spectrogram(ch_to_plot, axs_to_plot=None, f_lims=(8, 30), t_trial_window=(1000, 6000), t_reference_window=(- 1000, 0), welch_seg_len_pct=30, welch_overlap_pct=96)[source]

set_dataset(files)[source]

Call this method to configure a dataset. It must be called before plotting anything.

Parameters: files (list()) – List of mi.bson files.

set_sizes(label_size=6, axes_size=5, line_width=1)[source]

medusa.plots.mi_plots.plot_erd_ers_freq(files, ch_to_plot, features=None, track_info=None, fs=None, lcha=None, channel_set=None, welch_seg_len_pct=50, welch_overlap_pct=75, mov_mean_hz=0, **kwargs)[source]: This function depicts the ERD/ERS events of MI BCIs over the frequency spectrum. :param files: List of paths pointing to MI files. :type files: list :param ch_to_plot: List with the labels of the channels to plot :type ch_to_plot: list

medusa.plots.mi_plots.plot_erd_ers_time(files, ch_to_plot, features=None, track_info=None, fs=None, lcha=None, channel_set=None, mov_mean_ms=1000, **kwargs)[source]: Plotting function of ERD/ERS from motor imagery runs of MEDUSA. :param files: List of paths pointing to MI files. :type files: list :param ch_to_plot: List with the labels of the channels to plot :type ch_to_plot: list

medusa.plots.mi_plots.plot_r2_topoplot(files, ch_to_plot, features=None, track_info=None, fs=None, lcha=None, channel_set=None, welch_seg_len_pct=50, welch_overlap_pct=75, background=False, **kwargs)[source]

medusa.plots.optimal_subplots module

medusa.plots.optimal_subplots.factor(n)[source]

Computes an irreducible factorization of a number.

nint: Number to factorize

Returns: List of factors
Return type: list

medusa.plots.optimal_subplots.optimal_subplot_row_col(n_items)[source]

Computes the optimal arrangement of items in rows and columns.

n_itemsint: Number of items.

Returns: Optimal number of rows and columns, respectively
Return type: int, int

medusa.plots.timeplot module

Created on Thu Aug 25 17:09:18 2022 Edited on Mon Jan 09 14:00:00 2023 @author: Diego Marcos-Martínez

medusa.plots.timeplot.time_plot(signal, fs=1.0, ch_labels=None, time_to_show=None, ch_to_show=None, ch_offset=None, color='k', conditions_dict=None, events_dict=None, show_epoch_lines=True, show=False, fig=None, axes=None)[source]

Parameters

signal (numpy ndarray) – Signal with shape of [n_epochs,n_samples, n_channels] or [n_samples, n_channels]
fs (float) – Sampling rate. Value 1 as default
ch_labels (list of strings or None) – List containing the channel labels
time_to_show (float or None) – Width of the time window displayed. If time_to_show value is greater than the entire signal duration, this will be set as new time_to_show value. If None, time_to_show value will be chosen between the minimum value of the following windows: five seconds or the entire duration of the signal.
ch_to_show (int or None) – Number of channels depicted in the plot. This parameter must be less or equal to the number of channels available in the recording. If None, this parameter is set as the total number of channels.
ch_offset (flot or None) – Amplitude value to compute the offset of each channel. If None, the value is automatically calculated from signal values.
color (string or tuple) – Color of the signal line. It is plotted in black by default.
conditions_dict (dict) –
Dictionary with the following structure: {‘conditions’:{‘con_1’:{‘desc-name’:’Condition 1’,’label’:0},

’con_2’:{‘desc-name’:’Condition 2’,’label’:1}},

’condition_labels’: [0,0,1,1,0,0], ‘condition_times’: [0,14,14,28,28,35]} In this example, the sub-dictionary ‘conditions’ include each condition with a descriptor name (‘desc-name’) which will be show in the time-plot legend, and the label to identify the condition. For its part, ‘condition_labels’ must be a list containing the order of start and end of each condition. Finally, ‘condition_times’ value must be a list with the same length as ‘condition_labels’ containing the time stamps (in seconds) related with the start and the end of each condition. Note that these time stamps must be referenced to the start of the signal recording (the value 14 in the example means the 14th second after the start of recording). Note that as the end of a conditions coincides with the start of the following condition, the same time stamps must be included twice (see 14 and 28 values in ‘condition_times’ in the example).
events_dict –
Dictionary with the following structure: {‘events’:{‘event_1’:{‘desc-name’:’Event 1’,’label’:0},

’event_2’:{‘desc-name’:’Event 2’,’label’:1}},

’event_labels’: [0,1,1,1,0,1], ‘event_times’: [0,14,15.4,28,2,35]} In this example, the sub-dictionary ‘events’ include each event with a descriptor name (‘desc-name’) which will be show in the time-plot legend, and the label to identify the event. For its part, ‘event_labels’ must be a list containing the order in which each event ocurred. Finally, ‘condition_times’ value must be a list with the same length as ‘event_times’ containing the time stamps (in seconds) related with each event. Note that, as in ‘conditions_dict’ argument, these time stamps must be referenced to the start of the signal recording.
show_epoch_lines (bool) – If signal is divided in epochs and the parameter value is True, vertical dotted red lines will be plotted, splitting the epochs. Otherwise, they will not be plotted. True is the default value.
show (bool) – Show matplotlib figure
fig (matplotlib.pyplot.figure or None) – If a matplotlib figure is specified, the plot is displayed inside it. Otherwise, the plot will generate a new figure.
axes (matplotlib.pyplot.axes or None) – If a matplotlib axes are specified, the plot is displayed inside it. Otherwise, the plot will generate a new figure.

Notes

If time_to_show or ch_to_show parameters are defined and the signal is partially represented, vertical and horizontal sliders will be added to control the represented channels and time window, respectively. Vertical slider can be controlled by pressing up and dow arrows, and by dragging the marker. For its part, horizontal slider van be controlled by pressing right or left arrow, and by dragging the marker.