"""Figure classes for MNE-Python's 2D plots.
Class Hierarchy
---------------
MNEFigParams Container object, attached to MNEFigure by default. Sets
close_key='escape' plus whatever other key-value pairs are
passed to its constructor.
matplotlib.figure.Figure
└ MNEFigure
├ MNEBrowseFigure Interactive figure for scrollable data.
│ Generated by:
│ - raw.plot()
│ - epochs.plot()
│ - ica.plot_sources(raw)
│ - ica.plot_sources(epochs)
│
├ MNEAnnotationFigure GUI for adding annotations to Raw
│
├ MNESelectionFigure GUI for spatial channel selection. raw.plot()
│ and epochs.plot() will generate one of these
│ alongside an MNEBrowseFigure when
│ group_by == 'selection' or 'position'
│
└ MNELineFigure Interactive figure for non-scrollable data.
Generated by:
- spectrum.plot()
- evoked.plot() TODO Not yet implemented
- evoked.plot_white() TODO Not yet implemented
- evoked.plot_joint() TODO Not yet implemented
"""
# Authors: The MNE-Python contributors.
# License: BSD-3-Clause
# Copyright the MNE-Python contributors.
import datetime
import platform
from collections import OrderedDict
from contextlib import contextmanager
from functools import partial
import matplotlib.pyplot as plt
import numpy as np
from matplotlib import get_backend
from matplotlib.figure import Figure
from .._fiff.pick import (
_DATA_CH_TYPES_ORDER_DEFAULT,
_DATA_CH_TYPES_SPLIT,
_EYETRACK_CH_TYPES_SPLIT,
_FNIRS_CH_TYPES_SPLIT,
_VALID_CHANNEL_TYPES,
channel_indices_by_type,
pick_types,
)
from ..fixes import _close_event
from ..utils import Bunch, _click_ch_name, check_version, logger
from ._figure import BrowserBase
from .utils import (
DraggableLine,
_events_off,
_fake_click,
_fake_keypress,
_fake_scroll,
_merge_annotations,
_set_window_title,
_validate_if_list_of_axes,
plot_sensors,
plt_show,
)
name = "matplotlib"
BACKEND = get_backend()
# CONSTANTS (inches)
ANNOTATION_FIG_PAD = 0.1
ANNOTATION_FIG_MIN_H = 2.9 # fixed part, not including radio buttons/labels
ANNOTATION_FIG_W = 5.0
ANNOTATION_FIG_CHECKBOX_COLUMN_W = 0.5
_OLD_BUTTONS = not check_version("matplotlib", "3.7")
class MNEFigure(Figure):
"""Base class for 2D figures & dialogs; wraps matplotlib.figure.Figure."""
def __init__(self, **kwargs):
from matplotlib import rcParams
# figsize is the only kwarg we pass to matplotlib Figure()
figsize = kwargs.pop("figsize", None)
super().__init__(figsize=figsize)
# things we'll almost always want
defaults = dict(
fgcolor=rcParams["axes.edgecolor"], bgcolor=rcParams["axes.facecolor"]
)
for key, value in defaults.items():
if key not in kwargs:
kwargs[key] = value
# add param object if not already added (e.g. by BrowserBase)
if not hasattr(self, "mne"):
from mne.viz._figure import BrowserParams
self.mne = BrowserParams(**kwargs)
else:
for key in [k for k in kwargs if not hasattr(self.mne, k)]:
setattr(self.mne, key, kwargs[key])
def _close(self, event=None):
"""Handle close events."""
logger.debug(f"Closing {self!r}")
# remove references from parent fig to child fig
is_child = getattr(self.mne, "parent_fig", None) is not None
is_named = getattr(self.mne, "fig_name", None) is not None
if is_child:
try:
self.mne.parent_fig.mne.child_figs.remove(self)
except ValueError:
pass # already removed (on its own, probably?)
if is_named:
setattr(self.mne.parent_fig.mne, self.mne.fig_name, None)
def _keypress(self, event):
"""Handle keypress events."""
if event.key == self.mne.close_key:
plt.close(self)
elif event.key == "f11": # full screen
self.canvas.manager.full_screen_toggle()
def _buttonpress(self, event):
"""Handle buttonpress events."""
pass
def _pick(self, event):
"""Handle matplotlib pick events."""
pass
def _resize(self, event):
"""Handle window resize events."""
pass
def _add_default_callbacks(self, **kwargs):
"""Remove some matplotlib default callbacks and add MNE-Python ones."""
# Remove matplotlib default keypress catchers
default_callbacks = list(
self.canvas.callbacks.callbacks.get("key_press_event", {})
)
for callback in default_callbacks:
self.canvas.callbacks.disconnect(callback)
# add our event callbacks
callbacks = dict(
resize_event=self._resize,
key_press_event=self._keypress,
button_press_event=self._buttonpress,
close_event=self._close,
pick_event=self._pick,
)
callbacks.update(kwargs)
callback_ids = dict()
for event, callback in callbacks.items():
callback_ids[event] = self.canvas.mpl_connect(event, callback)
# store callback references so they aren't garbage-collected
self.mne._callback_ids = callback_ids
def _get_dpi_ratio(self):
"""Get DPI ratio (to handle hi-DPI screens)."""
dpi_ratio = 1.0
for key in ("_dpi_ratio", "_device_scale"):
dpi_ratio = getattr(self.canvas, key, dpi_ratio)
return dpi_ratio
def _get_size_px(self):
"""Get figure size in pixels."""
dpi_ratio = self._get_dpi_ratio()
return self.get_size_inches() * self.dpi / dpi_ratio
def _inch_to_rel(self, dim_inches, horiz=True):
"""Convert inches to figure-relative distances."""
fig_w, fig_h = self.get_size_inches()
w_or_h = fig_w if horiz else fig_h
return dim_inches / w_or_h
class MNEAnnotationFigure(MNEFigure):
"""Interactive dialog figure for annotations."""
def _close(self, event=None):
"""Handle close events (via keypress or window [x])."""
parent = self.mne.parent_fig
# disable span selector
parent.mne.ax_main.selector.active = False
# clear hover line
parent._remove_annotation_hover_line()
# disconnect hover callback
callback_id = parent.mne._callback_ids["motion_notify_event"]
parent.canvas.callbacks.disconnect(callback_id)
# do all the other cleanup activities
super()._close(event)
def _keypress(self, event):
"""Handle keypress events."""
text = self.label.get_text()
key = event.key
if key == self.mne.close_key:
plt.close(self)
elif key == "backspace":
text = text[:-1]
elif key == "enter":
self.mne.parent_fig._add_annotation_label(event)
return
elif len(key) > 1 or key == ";": # ignore modifier keys
return
else:
text = text + key
self.label.set_text(text)
self.canvas.draw()
def _radiopress(self, event, *, draw=True):
"""Handle Radiobutton clicks for Annotation label selection."""
# update which button looks active
buttons = self.mne.radio_ax.buttons
labels = [label.get_text() for label in buttons.labels]
idx = labels.index(buttons.value_selected)
self._set_active_button(idx, draw=False)
# update click-drag rectangle color
color = self.mne.parent_fig.mne.annotation_segment_colors[labels[idx]]
selector = self.mne.parent_fig.mne.ax_main.selector
# https://github.com/matplotlib/matplotlib/issues/20618
# https://github.com/matplotlib/matplotlib/pull/20693
selector.set_props(color=color, facecolor=color)
if draw:
self.canvas.draw()
def _click_override(self, event):
"""Override MPL radiobutton click detector to use transData."""
assert _OLD_BUTTONS
ax = self.mne.radio_ax
buttons = ax.buttons
if buttons.ignore(event) or event.button != 1 or event.inaxes != ax:
return
pclicked = ax.transData.inverted().transform((event.x, event.y))
distances = {}
for i, (p, t) in enumerate(zip(buttons.circles, buttons.labels)):
if (
t.get_window_extent().contains(event.x, event.y)
or np.linalg.norm(pclicked - p.center) < p.radius
):
distances[i] = np.linalg.norm(pclicked - p.center)
if len(distances) > 0:
closest = min(distances, key=distances.get)
buttons.set_active(closest)
def _set_active_button(self, idx, *, draw=True):
"""Set active button in annotation dialog figure."""
buttons = self.mne.radio_ax.buttons
logger.debug(f"buttons: {buttons}")
logger.debug(f"active idx: {idx}")
with _events_off(buttons):
buttons.set_active(idx)
if _OLD_BUTTONS:
logger.debug(f"circles: {buttons.circles}")
for circle in buttons.circles:
circle.set_facecolor(self.mne.parent_fig.mne.bgcolor)
# active circle gets filled in, partially transparent
color = list(buttons.circles[idx].get_edgecolor())
logger.debug(f"color: {color}")
color[-1] = 0.5
buttons.circles[idx].set_facecolor(color)
if draw:
self.canvas.draw()
class MNESelectionFigure(MNEFigure):
"""Interactive dialog figure for channel selections."""
def _close(self, event=None):
"""Handle close events."""
self.mne.parent_fig.mne.child_figs.remove(self)
self.mne.fig_selection = None
# selection fig & main fig tightly integrated; closing one closes both
plt.close(self.mne.parent_fig)
def _keypress(self, event):
"""Handle keypress events."""
if event.key in ("up", "down", "b"):
self.mne.parent_fig._keypress(event)
else: # check for close key
super()._keypress(event)
def _radiopress(self, event):
"""Handle RadioButton clicks for channel selection groups."""
logger.debug(f"Got radio press: {repr(event)}")
selections_dict = self.mne.parent_fig.mne.ch_selections
buttons = self.mne.radio_ax.buttons
labels = [label.get_text() for label in buttons.labels]
this_label = buttons.value_selected
parent = self.mne.parent_fig
if this_label == "Custom" and not len(selections_dict["Custom"]):
with _events_off(buttons):
buttons.set_active(self.mne.old_selection)
return
# clicking a selection cancels butterfly mode
if parent.mne.butterfly:
logger.debug("Disabling butterfly mode")
parent._toggle_butterfly()
with _events_off(buttons):
buttons.set_active(labels.index(this_label))
parent._update_selection()
def _set_custom_selection(self):
"""Set custom selection by lasso selector."""
chs = self.lasso.selection
parent = self.mne.parent_fig
buttons = self.mne.radio_ax.buttons
if not len(chs):
return
labels = [label.get_text() for label in buttons.labels]
inds = np.isin(parent.mne.ch_names, chs)
parent.mne.ch_selections["Custom"] = inds.nonzero()[0]
buttons.set_active(labels.index("Custom"))
def _style_radio_buttons_butterfly(self):
"""Handle RadioButton state for keyboard interactions."""
# Show all radio buttons as selected when in butterfly mode
parent = self.mne.parent_fig
buttons = self.mne.radio_ax.buttons
color = buttons.activecolor if parent.mne.butterfly else parent.mne.bgcolor
if _OLD_BUTTONS:
for circle in buttons.circles:
circle.set_facecolor(color)
# when leaving butterfly mode, make most-recently-used selection active
if not parent.mne.butterfly:
with _events_off(buttons):
buttons.set_active(self.mne.old_selection)
# update the sensors too
parent._update_highlighted_sensors()
class MNEBrowseFigure(BrowserBase, MNEFigure):
"""Interactive figure with scrollbars, for data browsing."""
def __init__(self, inst, figsize, ica=None, xlabel="Time (s)", **kwargs):
from matplotlib.colors import to_rgba_array
from matplotlib.patches import Rectangle
from matplotlib.ticker import (
FixedFormatter,
FixedLocator,
FuncFormatter,
NullFormatter,
)
from matplotlib.transforms import blended_transform_factory
from matplotlib.widgets import Button
from mpl_toolkits.axes_grid1.axes_divider import make_axes_locatable
from mpl_toolkits.axes_grid1.axes_size import Fixed
self.backend_name = "matplotlib"
kwargs.update({"inst": inst, "figsize": figsize, "ica": ica, "xlabel": xlabel})
BrowserBase.__init__(self, **kwargs)
MNEFigure.__init__(self, **kwargs)
# MAIN AXES: default sizes (inches)
# XXX simpler with constrained_layout? (when it's no longer "beta")
l_margin = 1.0
r_margin = 0.1
b_margin = 0.45
t_margin = 0.25
scroll_width = 0.25
hscroll_dist = 0.25
vscroll_dist = 0.1
help_width = scroll_width * 2
# MAIN AXES: default margins (figure-relative coordinates)
left = self._inch_to_rel(l_margin - vscroll_dist - help_width)
right = 1 - self._inch_to_rel(r_margin)
bottom = self._inch_to_rel(b_margin, horiz=False)
top = 1 - self._inch_to_rel(t_margin, horiz=False)
width = right - left
height = top - bottom
position = [left, bottom, width, height]
# Main axes must be a subplot for subplots_adjust to work (so user can
# adjust margins). That's why we don't use the Divider class directly.
ax_main = self.add_subplot(1, 1, 1, position=position)
self.subplotpars.update(left=left, bottom=bottom, top=top, right=right)
div = make_axes_locatable(ax_main)
# this only gets shown in zen mode
self.mne.zen_xlabel = ax_main.set_xlabel(xlabel)
self.mne.zen_xlabel.set_visible(not self.mne.scrollbars_visible)
# make sure background color of the axis is set
if "bgcolor" in kwargs:
ax_main.set_facecolor(kwargs["bgcolor"])
# SCROLLBARS
ax_hscroll = div.append_axes(
position="bottom", size=Fixed(scroll_width), pad=Fixed(hscroll_dist)
)
ax_vscroll = div.append_axes(
position="right", size=Fixed(scroll_width), pad=Fixed(vscroll_dist)
)
ax_hscroll.get_yaxis().set_visible(False)
ax_hscroll.set_xlabel(xlabel)
ax_vscroll.set_axis_off()
# HORIZONTAL SCROLLBAR PATCHES (FOR MARKING BAD EPOCHS)
if self.mne.is_epochs:
epoch_nums = self.mne.inst.selection
for ix, _ in enumerate(epoch_nums):
start = self.mne.boundary_times[ix]
width = np.diff(self.mne.boundary_times[:2])[0]
ax_hscroll.add_patch(
Rectangle(
(start, 0),
width,
1,
color="none",
zorder=self.mne.zorder["patch"],
)
)
# both axes, major ticks: gridlines
for _ax in (ax_main, ax_hscroll):
_ax.xaxis.set_major_locator(FixedLocator(self.mne.boundary_times[1:-1]))
_ax.xaxis.set_major_formatter(NullFormatter())
grid_kwargs = dict(
color=self.mne.fgcolor, axis="x", zorder=self.mne.zorder["grid"]
)
ax_main.grid(linewidth=2, linestyle="dashed", **grid_kwargs)
ax_hscroll.grid(alpha=0.5, linewidth=0.5, linestyle="solid", **grid_kwargs)
# main axes, minor ticks: ticklabel (epoch number) for every epoch
ax_main.xaxis.set_minor_locator(FixedLocator(self.mne.midpoints))
ax_main.xaxis.set_minor_formatter(FixedFormatter(epoch_nums))
# hscroll axes, minor ticks: up to 20 ticklabels (epoch numbers)
ax_hscroll.xaxis.set_minor_locator(
FixedLocator(self.mne.midpoints, nbins=20)
)
ax_hscroll.xaxis.set_minor_formatter(
FuncFormatter(lambda x, pos: self._get_epoch_num_from_time(x))
)
# hide some ticks
ax_main.tick_params(axis="x", which="major", bottom=False)
ax_hscroll.tick_params(axis="x", which="both", bottom=False)
else:
# RAW / ICA X-AXIS TICK & LABEL FORMATTING
ax_main.xaxis.set_major_formatter(
FuncFormatter(partial(self._xtick_formatter, ax_type="main"))
)
ax_hscroll.xaxis.set_major_formatter(
FuncFormatter(partial(self._xtick_formatter, ax_type="hscroll"))
)
if self.mne.time_format != "float":
for _ax in (ax_main, ax_hscroll):
_ax.set_xlabel("Time (HH:MM:SS)")
# VERTICAL SCROLLBAR PATCHES (COLORED BY CHANNEL TYPE)
ch_order = self.mne.ch_order
for ix, pick in enumerate(ch_order):
this_color = (
self.mne.ch_color_bad
if self.mne.ch_names[pick] in self.mne.info["bads"]
else self.mne.ch_color_dict
)
if isinstance(this_color, dict):
this_color = this_color[self.mne.ch_types[pick]]
ax_vscroll.add_patch(
Rectangle(
(0, ix), 1, 1, color=this_color, zorder=self.mne.zorder["patch"]
)
)
ax_vscroll.set_ylim(len(ch_order), 0)
ax_vscroll.set_visible(not self.mne.butterfly)
# SCROLLBAR VISIBLE SELECTION PATCHES
sel_kwargs = dict(
alpha=0.3, linewidth=4, clip_on=False, edgecolor=self.mne.fgcolor
)
vsel_patch = Rectangle(
(0, 0), 1, self.mne.n_channels, facecolor=self.mne.bgcolor, **sel_kwargs
)
ax_vscroll.add_patch(vsel_patch)
hsel_facecolor = np.average(
np.vstack(
(to_rgba_array(self.mne.fgcolor), to_rgba_array(self.mne.bgcolor))
),
axis=0,
weights=(3, 1),
) # 75% foreground, 25% background
hsel_patch = Rectangle(
(self.mne.t_start, 0),
self.mne.duration,
1,
facecolor=hsel_facecolor,
**sel_kwargs,
)
ax_hscroll.add_patch(hsel_patch)
ax_hscroll.set_xlim(
self.mne.first_time,
self.mne.first_time + self.mne.n_times / self.mne.info["sfreq"],
)
# VLINE
vline_color = (0.0, 0.75, 0.0)
vline_kwargs = dict(visible=False, zorder=self.mne.zorder["vline"])
if self.mne.is_epochs:
x = np.arange(self.mne.n_epochs)
vline = ax_main.vlines(x, 0, 1, colors=vline_color, **vline_kwargs)
vline.set_transform(
blended_transform_factory(ax_main.transData, ax_main.transAxes)
)
vline_hscroll = None
else:
vline = ax_main.axvline(0, color=vline_color, **vline_kwargs)
vline_hscroll = ax_hscroll.axvline(0, color=vline_color, **vline_kwargs)
vline_text = ax_main.annotate(
"",
xy=(0, 0),
xycoords="axes fraction",
xytext=(-2, 0),
textcoords="offset points",
fontsize=10,
ha="right",
va="center",
color=vline_color,
**vline_kwargs,
)
# HELP BUTTON: initialize in the wrong spot...
ax_help = div.append_axes(
position="left", size=Fixed(help_width), pad=Fixed(vscroll_dist)
)
# HELP BUTTON: ...move it down by changing its locator
loc = div.new_locator(nx=0, ny=0)
ax_help.set_axes_locator(loc)
# HELP BUTTON: make it a proper button
with _patched_canvas(ax_help.figure):
self.mne.button_help = Button(ax_help, "Help")
# PROJ BUTTON
ax_proj = None
if len(self.mne.projs) and not self.mne.inst.proj:
proj_button_pos = [
1 - self._inch_to_rel(r_margin + scroll_width), # left
self._inch_to_rel(b_margin, horiz=False), # bottom
self._inch_to_rel(scroll_width), # width
self._inch_to_rel(scroll_width, horiz=False), # height
]
loc = div.new_locator(nx=4, ny=0)
ax_proj = self.add_axes(proj_button_pos)
ax_proj.set_axes_locator(loc)
with _patched_canvas(ax_help.figure):
self.mne.button_proj = Button(ax_proj, "Prj")
# INIT TRACES
self.mne.trace_kwargs = dict(antialiased=True, linewidth=0.5)
self.mne.traces = ax_main.plot(
np.full((1, self.mne.n_channels), np.nan), **self.mne.trace_kwargs
)
# SAVE UI ELEMENT HANDLES
vars(self.mne).update(
ax_main=ax_main,
ax_help=ax_help,
ax_proj=ax_proj,
ax_hscroll=ax_hscroll,
ax_vscroll=ax_vscroll,
vsel_patch=vsel_patch,
hsel_patch=hsel_patch,
vline=vline,
vline_hscroll=vline_hscroll,
vline_text=vline_text,
)
def _get_size(self):
return self.get_size_inches()
def _resize(self, event):
"""Handle resize event for mne_browse-style plots (Raw/Epochs/ICA)."""
old_width, old_height = self.mne.fig_size_px
new_width, new_height = self._get_size_px()
new_margins = _calc_new_margins(
self, old_width, old_height, new_width, new_height
)
self.subplots_adjust(**new_margins)
# zen mode bookkeeping
self.mne.zen_w *= old_width / new_width
self.mne.zen_h *= old_height / new_height
self.mne.fig_size_px = (new_width, new_height)
self.canvas.draw_idle()
def _hover(self, event):
"""Handle motion event when annotating."""
if (
event.button is not None
or event.xdata is None
or event.inaxes != self.mne.ax_main
):
return
if not self.mne.draggable_annotations:
self._remove_annotation_hover_line()
return
from matplotlib.patheffects import Normal, Stroke
for coll in self.mne.annotations:
if coll.contains(event)[0]:
path = coll.get_paths()
assert len(path) == 1
path = path[0]
color = coll.get_edgecolors()[0]
ylim = self.mne.ax_main.get_ylim()
# are we on the left or right edge?
_l = path.vertices[:, 0].min()
_r = path.vertices[:, 0].max()
x = _l if abs(event.xdata - _l) < abs(event.xdata - _r) else _r
mask = path.vertices[:, 0] == x
def drag_callback(x0):
path.vertices[mask, 0] = x0
# create or update the DraggableLine
hover_line = self.mne.annotation_hover_line
if hover_line is None:
line = self.mne.ax_main.plot(
[x, x], ylim, color=color, linewidth=2, pickradius=5.0
)[0]
hover_line = DraggableLine(
line, self._modify_annotation, drag_callback
)
else:
hover_line.set_x(x)
hover_line.drag_callback = drag_callback
# style the line
line = hover_line.line
patheff = [Stroke(linewidth=4, foreground=color, alpha=0.5), Normal()]
line.set_path_effects(
patheff if line.contains(event)[0] else patheff[1:]
)
self.mne.ax_main.selector.active = False
self.mne.annotation_hover_line = hover_line
self.canvas.draw_idle()
return
self._remove_annotation_hover_line()
def _keypress(self, event):
"""Handle keypress events."""
key = event.key
n_channels = self.mne.n_channels
if self.mne.is_epochs:
last_time = self.mne.n_times / self.mne.info["sfreq"]
else:
last_time = self.mne.inst.times[-1]
# scroll up/down
if key in ("down", "up", "shift+down", "shift+up"):
key = key.split("+")[-1]
direction = -1 if key == "up" else 1
# butterfly case
if self.mne.butterfly:
return
# group_by case
elif self.mne.fig_selection is not None:
buttons = self.mne.fig_selection.mne.radio_ax.buttons
labels = [label.get_text() for label in buttons.labels]
current_label = buttons.value_selected
current_idx = labels.index(current_label)
selections_dict = self.mne.ch_selections
penult = current_idx < (len(labels) - 1)
pre_penult = current_idx < (len(labels) - 2)
has_custom = selections_dict.get("Custom", None) is not None
def_custom = len(selections_dict.get("Custom", list()))
up_ok = key == "up" and current_idx > 0
down_ok = key == "down" and (
pre_penult
or (penult and not has_custom)
or (penult and has_custom and def_custom)
)
if up_ok or down_ok:
buttons.set_active(current_idx + direction)
# normal case
else:
ceiling = len(self.mne.ch_order) - n_channels
ch_start = self.mne.ch_start + direction * n_channels
self.mne.ch_start = np.clip(ch_start, 0, ceiling)
self._update_picks()
self._update_vscroll()
self._redraw()
# scroll left/right
elif key in ("right", "left", "shift+right", "shift+left"):
old_t_start = self.mne.t_start
direction = 1 if key.endswith("right") else -1
if self.mne.is_epochs:
denom = 1 if key.startswith("shift") else self.mne.n_epochs
else:
denom = 1 if key.startswith("shift") else 4
t_max = last_time - self.mne.duration
t_start = self.mne.t_start + direction * self.mne.duration / denom
self.mne.t_start = np.clip(t_start, self.mne.first_time, t_max)
if self.mne.t_start != old_t_start:
self._update_hscroll()
self._redraw(annotations=True)
# scale traces
elif key in ("=", "+", "-"):
scaler = 1 / 1.1 if key == "-" else 1.1
self.mne.scale_factor *= scaler
self._redraw(update_data=False)
# change number of visible channels
elif (
key in ("pageup", "pagedown")
and self.mne.fig_selection is None
and not self.mne.butterfly
):
new_n_ch = n_channels + (1 if key == "pageup" else -1)
self.mne.n_channels = np.clip(new_n_ch, 1, len(self.mne.ch_order))
# add new chs from above if we're at the bottom of the scrollbar
ch_end = self.mne.ch_start + self.mne.n_channels
if ch_end > len(self.mne.ch_order) and self.mne.ch_start > 0:
self.mne.ch_start -= 1
self._update_vscroll()
# redraw only if changed
if self.mne.n_channels != n_channels:
self._update_picks()
self._update_trace_offsets()
self._redraw(annotations=True)
# change duration
elif key in ("home", "end"):
old_dur = self.mne.duration
dur_delta = 1 if key == "end" else -1
if self.mne.is_epochs:
# prevent from showing zero epochs, or more epochs than we have
self.mne.n_epochs = np.clip(
self.mne.n_epochs + dur_delta, 1, len(self.mne.inst)
)
# use the length of one epoch as duration change
min_dur = len(self.mne.inst.times) / self.mne.info["sfreq"]
new_dur = self.mne.duration + dur_delta * min_dur
else:
# never show fewer than 3 samples
min_dur = 3 * np.diff(self.mne.inst.times[:2])[0]
# use multiplicative dur_delta
dur_delta = 5 / 4 if dur_delta > 0 else 4 / 5
new_dur = self.mne.duration * dur_delta
self.mne.duration = np.clip(new_dur, min_dur, last_time)
if self.mne.duration != old_dur:
if self.mne.t_start + self.mne.duration > last_time:
self.mne.t_start = last_time - self.mne.duration
self._update_hscroll()
self._redraw(annotations=True)
elif key == "?": # help window
self._toggle_help_fig(event)
elif key == "a": # annotation mode
self._toggle_annotation_fig()
elif key == "b" and self.mne.instance_type != "ica": # butterfly mode
self._toggle_butterfly()
elif key == "d": # DC shift
self.mne.remove_dc = not self.mne.remove_dc
self._redraw()
elif key == "h": # histogram
self._toggle_epoch_histogram()
elif key == "j" and len(self.mne.projs): # SSP window
self._toggle_proj_fig()
elif key == "J" and len(self.mne.projs):
self._toggle_proj_checkbox(event, toggle_all=True)
elif key == "p": # toggle draggable annotations
self._toggle_draggable_annotations(event)
if self.mne.fig_annotation is not None:
checkbox = self.mne.fig_annotation.mne.drag_checkbox
with _events_off(checkbox):
checkbox.set_active(0)
elif key == "s": # scalebars
self._toggle_scalebars(event)
elif key == "w": # toggle noise cov whitening
self._toggle_whitening()
elif key == "z": # zen mode: hide scrollbars and buttons
self._toggle_scrollbars()
self._redraw(update_data=False)
elif key == "t":
self._toggle_time_format()
else: # check for close key / fullscreen toggle
super()._keypress(event)
def _buttonpress(self, event):
"""Handle mouse clicks."""
from matplotlib.collections import PolyCollection
from ..annotations import _sync_onset
butterfly = self.mne.butterfly
annotating = self.mne.fig_annotation is not None
ax_main = self.mne.ax_main
inst = self.mne.inst
# ignore middle clicks, scroll wheel events, and clicks outside axes
if event.button not in (1, 3) or event.inaxes is None:
return
elif event.button == 1: # left-click (primary)
# click in main axes
if event.inaxes == ax_main and not annotating:
if self.mne.instance_type == "epochs" or not butterfly:
for line in self.mne.traces + self.mne.epoch_traces:
if line.contains(event)[0]:
if self.mne.instance_type == "epochs":
self._toggle_bad_epoch(event)
else:
idx = self.mne.traces.index(line)
self._toggle_bad_channel(idx)
return
self._show_vline(event.xdata) # butterfly / not on data trace
self._redraw(update_data=False, annotations=False)
return
# click in vertical scrollbar
elif event.inaxes == self.mne.ax_vscroll:
if self.mne.fig_selection is not None:
self._change_selection_vscroll(event)
elif self._check_update_vscroll_clicked(event):
self._redraw()
# click in horizontal scrollbar
elif event.inaxes == self.mne.ax_hscroll:
if self._check_update_hscroll_clicked(event):
self._redraw(annotations=True)
# click on proj button
elif event.inaxes == self.mne.ax_proj:
self._toggle_proj_fig(event)
# click on help button
elif event.inaxes == self.mne.ax_help:
self._toggle_help_fig(event)
else: # right-click (secondary)
if annotating:
spans = [
span
for span in ax_main.collections
if isinstance(span, PolyCollection)
]
if any(span.contains(event)[0] for span in spans):
xdata = event.xdata - self.mne.first_time
start = _sync_onset(inst, inst.annotations.onset)
end = start + inst.annotations.duration
is_onscreen = self.mne.onscreen_annotations # boolean array
was_clicked = (xdata > start) & (xdata < end) & is_onscreen
# determine which annotation label is "selected"
buttons = self.mne.fig_annotation.mne.radio_ax.buttons
current_label = buttons.value_selected
is_active_label = inst.annotations.description == current_label
# use z-order as tiebreaker (or if click wasn't on an active span)
# (ax_main.collections only includes *visible* annots, so we offset)
visible_zorders = [span.zorder for span in spans]
zorders = np.zeros_like(is_onscreen).astype(int)
offset = np.where(is_onscreen)[0][0]
zorders[offset : (offset + len(visible_zorders))] = visible_zorders
# among overlapping clicked spans, prefer removing spans whose label
# is the active label; then fall back to zorder as deciding factor
active_clicked = was_clicked & is_active_label
mask = active_clicked if any(active_clicked) else was_clicked
highest = zorders == zorders[mask].max()
idx = np.where(highest)[0]
inst.annotations.delete(idx)
self._remove_annotation_hover_line()
self._draw_annotations()
self.canvas.draw_idle()
elif event.inaxes == ax_main:
self._toggle_vline(False)
def _pick(self, event):
"""Handle matplotlib pick events."""
from matplotlib.text import Text
if self.mne.butterfly:
return
# clicked on channel name
if isinstance(event.artist, Text):
ch_name = event.artist.get_text()
ind = self.mne.ch_names[self.mne.picks].tolist().index(ch_name)
if event.mouseevent.button == 1: # left click
self._toggle_bad_channel(ind)
elif event.mouseevent.button == 3: # right click
self._create_ch_context_fig(ind)
def _create_ch_context_fig(self, idx):
fig = super()._create_ch_context_fig(idx)
plt_show(fig=fig)
def _new_child_figure(self, fig_name, *, layout=None, **kwargs):
"""Instantiate a new MNE dialog figure (with event listeners)."""
fig = _figure(
toolbar=False,
parent_fig=self,
fig_name=fig_name,
layout=layout,
**kwargs,
)
fig._add_default_callbacks()
self.mne.child_figs.append(fig)
if isinstance(fig_name, str):
setattr(self.mne, fig_name, fig)
return fig
# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
# HELP DIALOG
# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
def _create_help_fig(self):
"""Create help dialog window."""
text = {
key: val for key, val in self._get_help_text().items() if val is not None
}
keys = ""
vals = ""
for key, val in text.items():
newsection = "\n" if key.startswith("_") else ""
key = key[1:] if key.startswith("_") else key
newlines = "\n" * len(val.split("\n")) # handle multiline values
keys += f"{newsection}{key} {newlines}"
vals += f"{newsection}{val}\n"
# calc figure size
n_lines = len(keys.split("\n"))
longest_key = max(len(k) for k in text.keys())
longest_val = max(
max(len(w) for w in v.split("\n")) if "\n" in v else len(v)
for v in text.values()
)
width = (longest_key + longest_val) / 12
height = (n_lines) / 5
# create figure and axes
fig = self._new_child_figure(
figsize=(width, height), fig_name="fig_help", window_title="Help"
)
ax = fig.add_axes((0.01, 0.01, 0.98, 0.98))
ax.set_axis_off()
kwargs = dict(va="top", linespacing=1.5, usetex=False)
ax.text(0.42, 1, keys, ma="right", ha="right", **kwargs)
ax.text(0.42, 1, vals, ma="left", ha="left", **kwargs)
def _toggle_help_fig(self, event):
"""Show/hide the help dialog window."""
if self.mne.fig_help is None:
self._create_help_fig()
plt_show(fig=self.mne.fig_help)
else:
plt.close(self.mne.fig_help)
def _get_help_text(self):
"""Generate help dialog text; `None`-valued entries removed later."""
inst = self.mne.instance_type
is_raw = inst == "raw"
is_epo = inst == "epochs"
is_ica = inst == "ica"
has_proj = bool(len(self.mne.projs))
# adapt keys to different platforms
is_mac = platform.system() == "Darwin"
dur_keys = ("fn + ←", "fn + →") if is_mac else ("Home", "End")
ch_keys = ("fn + ↑", "fn + ↓") if is_mac else ("Page up", "Page down")
# adapt descriptions to different instance types
ch_cmp = "component" if is_ica else "channel"
ch_epo = "epoch" if is_epo else "channel"
ica_bad = "Mark/unmark component for exclusion"
dur_vals = (
[f"Show {n} epochs" for n in ("fewer", "more")]
if self.mne.is_epochs
else [f"Show {d} time window" for d in ("shorter", "longer")]
)
ch_vals = [
f"{inc_dec} number of visible {ch_cmp}s"
for inc_dec in ("Increase", "Decrease")
]
lclick_data = ica_bad if is_ica else f"Mark/unmark bad {ch_epo}"
lclick_name = ica_bad if is_ica else "Mark/unmark bad channel"
rclick_name = dict(
ica="Show diagnostics for component",
epochs="Show imageplot for channel",
raw="Show channel location",
)[inst]
# TODO not yet implemented
# ldrag = ('Show spectrum plot for selected time span;\nor (in '
# 'annotation mode) add annotation') if inst== 'raw' else None
ldrag = "add annotation (in annotation mode)" if is_raw else None
noise_cov = None if self.mne.noise_cov is None else "Toggle signal whitening"
scrl = "1 epoch" if self.mne.is_epochs else "¼ window"
# below, value " " is a hack to make "\n".split(value) have length 1
help_text = OrderedDict(
[
("_NAVIGATION", " "),
("→", f"Scroll {scrl} right (scroll full window with Shift + →)"),
("←", f"Scroll {scrl} left (scroll full window with Shift + ←)"),
(dur_keys[0], dur_vals[0]),
(dur_keys[1], dur_vals[1]),
("↑", f"Scroll up ({ch_cmp}s)"),
("↓", f"Scroll down ({ch_cmp}s)"),
(ch_keys[0], ch_vals[0]),
(ch_keys[1], ch_vals[1]),
("_SIGNAL TRANSFORMATIONS", " "),
("+ or =", "Increase signal scaling"),
("-", "Decrease signal scaling"),
("b", "Toggle butterfly mode" if not is_ica else None),
("d", "Toggle DC removal" if is_raw else None),
("w", noise_cov),
("_USER INTERFACE", " "),
("a", "Toggle annotation mode" if is_raw else None),
("h", "Toggle peak-to-peak histogram" if is_epo else None),
("j", "Toggle SSP projector window" if has_proj else None),
("shift+j", "Toggle all SSPs"),
("p", "Toggle draggable annotations" if is_raw else None),
("s", "Toggle scalebars" if not is_ica else None),
("z", "Toggle scrollbars"),
("t", "Toggle time format" if not is_epo else None),
("F11", "Toggle fullscreen" if not is_mac else None),
("?", "Open this help window"),
("esc", "Close focused figure or dialog window"),
("_MOUSE INTERACTION", " "),
(f"Left-click {ch_cmp} name", lclick_name),
(f"Left-click {ch_cmp} data", lclick_data),
("Left-click-and-drag on plot", ldrag),
("Left-click on plot background", "Place vertical guide"),
("Right-click on plot background", "Clear vertical guide"),
("Right-click on channel name", rclick_name),
]
)
return help_text
# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
# ANNOTATIONS
# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
def _create_annotation_fig(self):
"""Create the annotation dialog window."""
from matplotlib.widgets import Button, CheckButtons, SpanSelector
from mpl_toolkits.axes_grid1.axes_divider import make_axes_locatable
from mpl_toolkits.axes_grid1.axes_size import Fixed
# make figure
labels = np.array(sorted(set(self.mne.inst.annotations.description)))
radio_button_h = self._compute_annotation_figsize(len(labels))
figsize = (ANNOTATION_FIG_W, ANNOTATION_FIG_MIN_H + radio_button_h)
fig = self._new_child_figure(
figsize=figsize,
FigureClass=MNEAnnotationFigure,
fig_name="fig_annotation",
window_title="Annotations",
)
# make main axes
left = fig._inch_to_rel(ANNOTATION_FIG_PAD)
bottom = fig._inch_to_rel(ANNOTATION_FIG_PAD, horiz=False)
width = 1 - 2 * left
height = 1 - 2 * bottom
fig.mne.radio_ax = fig.add_axes(
(left, bottom, width, height), frame_on=False, aspect="equal"
)
div = make_axes_locatable(fig.mne.radio_ax)
# append show/hide checkboxes at right
fig.mne.show_hide_ax = div.append_axes(
position="right",
size=Fixed(ANNOTATION_FIG_CHECKBOX_COLUMN_W),
pad=Fixed(ANNOTATION_FIG_PAD),
aspect="equal",
sharey=fig.mne.radio_ax,
)
# populate w/ radio buttons & labels
self._update_annotation_fig()
# append instructions at top
instructions_ax = div.append_axes(
position="top", size=Fixed(1), pad=Fixed(5 * ANNOTATION_FIG_PAD)
)
instructions = "\n".join(
[
r"$\mathbf{Left‐click~&~drag~on~plot:}$ create/modify annotation",
r"$\mathbf{Right‐click~on~plot~annotation:}$ delete annotation",
r"$\mathbf{Type~in~annotation~window:}$ modify new label name",
r"$\mathbf{Enter~(or~click~button):}$ add new label to list",
r"$\mathbf{Esc:}$ exit annotation mode & close this window",
]
)
instructions_ax.text(
0, 1, instructions, va="top", ha="left", linespacing=1.7, usetex=False
) # force use of MPL mathtext parser
instructions_ax.set_axis_off()
# append text entry axes at bottom
text_entry_ax = div.append_axes(
position="bottom",
size=Fixed(3 * ANNOTATION_FIG_PAD),
pad=Fixed(ANNOTATION_FIG_PAD),
)
text_entry_ax.text(
0.4, 0.5, "New label:", va="center", ha="right", weight="bold"
)
fig.label = text_entry_ax.text(0.5, 0.5, "BAD_", va="center", ha="left")
text_entry_ax.set_axis_off()
# append button at bottom
button_ax = div.append_axes(
position="bottom",
size=Fixed(3 * ANNOTATION_FIG_PAD),
pad=Fixed(ANNOTATION_FIG_PAD),
)
fig.button = Button(button_ax, "Add new label")
fig.button.on_clicked(self._add_annotation_label)
plt_show(fig=fig)
# add "draggable" checkbox
drag_ax_height = 3 * ANNOTATION_FIG_PAD
drag_ax = div.append_axes(
"bottom", size=Fixed(drag_ax_height), pad=Fixed(ANNOTATION_FIG_PAD)
)
check_kwargs = _get_check_kwargs()
checkbox = CheckButtons(
drag_ax,
labels=("Draggable edges?",),
actives=(self.mne.draggable_annotations,),
**check_kwargs,
)
checkbox.on_clicked(self._toggle_draggable_annotations)
fig.mne.drag_checkbox = checkbox
# reposition & resize axes
width_in, _ = fig.get_size_inches()
width_ax = fig._inch_to_rel(
width_in - ANNOTATION_FIG_CHECKBOX_COLUMN_W - 3 * ANNOTATION_FIG_PAD
)
aspect = width_ax / fig._inch_to_rel(drag_ax_height)
drag_ax.set(xlim=(0, aspect), ylim=(0, 1))
drag_ax.set_axis_off()
if _OLD_BUTTONS:
rect = checkbox.rectangles[0]
_pad, _size = (0.2, 0.6)
rect.set_bounds(_pad, _pad, _size, _size)
lines = checkbox.lines[0]
for line, direction in zip(lines, (1, -1)):
line.set_xdata((_pad, _pad + _size)[::direction])
line.set_ydata((_pad, _pad + _size))
text = checkbox.labels[0]
text.set(position=(3 * _pad + _size, 0.45), va="center")
for artist in lines + (rect, text):
artist.set_transform(drag_ax.transData)
# setup interactivity in plot window
if fig.mne.radio_ax.buttons is None:
col = "#ff0000"
else:
col = self.mne.annotation_segment_colors[self._get_annotation_labels()[0]]
selector = SpanSelector(
self.mne.ax_main,
self._select_annotation_span,
"horizontal",
minspan=0.1,
useblit=True,
button=1,
props=dict(alpha=0.5, facecolor=col),
)
self.mne.ax_main.selector = selector
self.mne._callback_ids["motion_notify_event"] = self.canvas.mpl_connect(
"motion_notify_event", self._hover
)
def _toggle_visible_annotations(self, event):
"""Enable/disable display of annotations on a per-label basis."""
checkboxes = self.mne.show_hide_annotation_checkboxes
labels = [t.get_text() for t in checkboxes.labels]
actives = checkboxes.get_status()
self.mne.visible_annotations = dict(zip(labels, actives))
self._redraw(update_data=False, annotations=True)
def _toggle_draggable_annotations(self, event):
"""Enable/disable draggable annotation edges."""
self.mne.draggable_annotations = not self.mne.draggable_annotations
def _update_annotation_fig(self, *, draw=True):
"""Draw or redraw the radio buttons and annotation labels."""
from matplotlib.colors import to_rgba
from matplotlib.widgets import CheckButtons, RadioButtons
# define shorthand variables
fig = self.mne.fig_annotation
ax = fig.mne.radio_ax
labels = self._get_annotation_labels()
# compute new figsize
radio_button_h = self._compute_annotation_figsize(len(labels))
fig.set_size_inches(
ANNOTATION_FIG_W, ANNOTATION_FIG_MIN_H + radio_button_h, forward=True
)
# populate center axes with labels & radio buttons
ax.clear()
title = "Existing labels:" if len(labels) else "No existing labels"
ax.set_title(title, size=None, loc="left")
if len(labels):
if _OLD_BUTTONS:
ax.buttons = RadioButtons(ax, labels)
radius = 0.15
circles = ax.buttons.circles
for circle, label in zip(circles, ax.buttons.labels):
circle.set_transform(ax.transData)
center = ax.transData.inverted().transform(
ax.transAxes.transform((0.1, 0))
)
circle.set_center((center[0], circle.center[1]))
circle.set_edgecolor(
self.mne.annotation_segment_colors[label.get_text()]
)
circle.set_linewidth(4)
circle.set_radius(radius / len(labels))
else:
edgecolors = [
self.mne.annotation_segment_colors[label] for label in labels
]
facecolors = [to_rgba(col)[:3] + (0.5,) for col in edgecolors]
radio_props = dict(
s=144,
linewidth=4,
edgecolor=edgecolors,
facecolor=facecolors,
)
ax.buttons = RadioButtons(ax, labels, radio_props=radio_props)
else:
ax.buttons = None
# adjust xlim to keep equal aspect & full width (keep circles round)
aspect = (
ANNOTATION_FIG_W - ANNOTATION_FIG_CHECKBOX_COLUMN_W - 3 * ANNOTATION_FIG_PAD
) / radio_button_h
ax.set_xlim((0, aspect))
# style the selected button
if len(labels):
fig._set_active_button(0, draw=False)
# add event listeners
if ax.buttons is not None:
if _OLD_BUTTONS:
ax.buttons.disconnect_events() # clear MPL default listeners
ax.buttons.on_clicked(fig._radiopress)
if _OLD_BUTTONS:
ax.buttons.connect_event("button_press_event", fig._click_override)
ax.set_axis_off()
# now do the show/hide checkboxes
show_hide_ax = fig.mne.show_hide_ax
show_hide_ax.clear()
show_hide_ax.set_axis_on()
aspect = ANNOTATION_FIG_CHECKBOX_COLUMN_W / radio_button_h
show_hide_ax.set(xlim=(0, aspect), ylim=(0, 1))
# ensure new labels have checkbox values
check_values = {label: False for label in labels}
check_values.update(self.mne.visible_annotations) # existing checks
actives = [check_values[label] for label in labels]
# regenerate checkboxes
check_kwargs = _get_check_kwargs()
checkboxes = CheckButtons(
ax=fig.mne.show_hide_ax, labels=labels, actives=actives, **check_kwargs
)
checkboxes.on_clicked(self._toggle_visible_annotations)
# add title, hide labels
show_hide_title = "show/\nhide " if len(labels) else ""
show_hide_ax.set_title(show_hide_title, size=None, loc="right")
for label in checkboxes.labels:
label.set_visible(False)
show_hide_ax.set_axis_off()
# fix aspect and right-align
if _OLD_BUTTONS:
if len(labels) == 1:
bounds = (0.05, 0.375, 0.25, 0.25) # undo MPL special case
checkboxes.rectangles[0].set_bounds(bounds)
for line, step in zip(checkboxes.lines[0], (1, -1)):
line.set_xdata((bounds[0], bounds[0] + bounds[2]))
line.set_ydata((bounds[1], bounds[1] + bounds[3])[::step])
for rect in checkboxes.rectangles:
rect.set_transform(show_hide_ax.transData)
bbox = rect.get_bbox()
bounds = (aspect, bbox.ymin, -bbox.width, bbox.height)
rect.set_bounds(bounds)
rect.set_clip_on(False)
for line in np.array(checkboxes.lines).ravel():
line.set_transform(show_hide_ax.transData)
line.set_xdata(aspect + 0.05 - np.array(line.get_xdata()))
# store state
self.mne.visible_annotations = check_values
self.mne.show_hide_annotation_checkboxes = checkboxes
if draw:
fig.canvas.draw_idle()
def _toggle_annotation_fig(self):
"""Show/hide the annotation dialog window."""
if self.mne.fig_annotation is None and not self.mne.is_epochs:
self._create_annotation_fig()
else:
plt.close(self.mne.fig_annotation)
def _compute_annotation_figsize(self, n_labels):
"""Adapt size of Annotation UI to accommodate the number of buttons.
self._create_annotation_fig() implements the following:
Fixed part of height:
0.1 top margin
1.0 instructions
0.5 padding below instructions
--- (variable-height axis for label list, returned by this method)
0.1 padding above text entry
0.3 text entry
0.1 padding above button
0.3 button
0.1 padding above checkbox
0.3 checkbox
0.1 bottom margin
------------------------------------------
2.9 total fixed height
"""
return max(ANNOTATION_FIG_PAD, 0.7 * n_labels)
def _add_annotation_label(self, event):
"""Add new annotation description."""
text = self.mne.fig_annotation.label.get_text()
# If it exists, change this title. If it doesn't, the title will
# be set in _update_annotation_fig()
if text in self.mne.new_annotation_labels:
self.mne.fig_annotation.mne.radio_ax.set_title(
f"Existing labels: (duplicate label: {repr(text)})",
size=None,
loc="left",
)
self.mne.fig_annotation.canvas.draw()
return
self.mne.new_annotation_labels.append(text)
self._setup_annotation_colors()
self._update_annotation_fig(draw=False)
# automatically activate new label's radio button
idx = [
label.get_text()
for label in self.mne.fig_annotation.mne.radio_ax.buttons.labels
].index(text)
self.mne.fig_annotation._set_active_button(idx, draw=False)
# simulate a click on the radiobutton → update the span selector color
self.mne.fig_annotation._radiopress(event=None, draw=False)
# reset the text entry box's text
self.mne.fig_annotation.label.set_text("BAD_")
self.mne.fig_annotation.canvas.draw()
def _select_annotation_span(self, vmin, vmax):
"""Handle annotation span selector."""
from ..annotations import _sync_onset
onset = _sync_onset(self.mne.inst, vmin, True) - self.mne.first_time
duration = vmax - vmin
buttons = self.mne.fig_annotation.mne.radio_ax.buttons
if buttons is None or buttons.value_selected is None:
logger.warning(
"No annotation-label exists! "
"Add one by typing the name and clicking "
'on "Add new label" in the annotation-dialog.'
)
else:
labels = [label.get_text() for label in buttons.labels]
active_idx = labels.index(buttons.value_selected)
_merge_annotations(
onset, onset + duration, labels[active_idx], self.mne.inst.annotations
)
# if adding a span with an annotation label that is hidden, show it
if not self.mne.visible_annotations[buttons.value_selected]:
self.mne.show_hide_annotation_checkboxes.set_active(active_idx)
self._redraw(update_data=False, annotations=True)
def _remove_annotation_hover_line(self):
"""Remove annotation line from the plot and reactivate selector."""
if self.mne.annotation_hover_line is not None:
self.mne.annotation_hover_line.remove()
self.mne.annotation_hover_line = None
self.mne.ax_main.selector.active = True
self.canvas.draw()
def _modify_annotation(self, old_x, new_x):
"""Modify annotation."""
from ..annotations import _sync_onset
segment = np.array(np.where(self.mne.annotation_segments == old_x))
if segment.shape[1] == 0:
return
raw = self.mne.inst
annotations = raw.annotations
first_time = self.mne.first_time
idx = [segment[0][0], segment[1][0]]
onset = _sync_onset(raw, self.mne.annotation_segments[idx[0]][0], True)
ann_idx = np.where(annotations.onset == onset - first_time)[0]
if idx[1] == 0: # start of annotation
onset = _sync_onset(raw, new_x, True) - first_time
duration = annotations.duration[ann_idx] + old_x - new_x
else: # end of annotation
onset = annotations.onset[ann_idx]
duration = _sync_onset(raw, new_x, True) - onset - first_time
if duration < 0:
onset += duration
duration *= -1.0
_merge_annotations(
onset,
onset + duration,
annotations.description[ann_idx],
annotations,
ann_idx,
)
self._draw_annotations()
self._remove_annotation_hover_line()
self.canvas.draw_idle()
def _clear_annotations(self):
"""Clear all annotations from the figure."""
for annot in list(self.mne.annotations):
annot.remove()
self.mne.annotations.remove(annot)
for annot in list(self.mne.hscroll_annotations):
annot.remove()
self.mne.hscroll_annotations.remove(annot)
for text in list(self.mne.annotation_texts):
text.remove()
self.mne.annotation_texts.remove(text)
def _draw_annotations(self):
"""Draw (or redraw) the annotation spans."""
self._clear_annotations()
self._update_annotation_segments()
segments = self.mne.annotation_segments
onscreen_annotations = np.zeros(len(segments), dtype=bool)
times = self.mne.times
ax = self.mne.ax_main
ylim = ax.get_ylim()
for idx, (start, end) in enumerate(segments):
descr = self.mne.inst.annotations.description[idx]
segment_color = self.mne.annotation_segment_colors[descr]
zorder = self.mne.zorder["ann"] + idx
kwargs = dict(color=segment_color, alpha=0.3, zorder=zorder)
if self.mne.visible_annotations[descr]:
# draw all segments on ax_hscroll
annot = self.mne.ax_hscroll.fill_betweenx((0, 1), start, end, **kwargs)
self.mne.hscroll_annotations.append(annot)
# draw only visible segments on ax_main
visible_segment = np.clip([start, end], times[0], times[-1])
if np.diff(visible_segment) > 0:
annot = ax.fill_betweenx(ylim, *visible_segment, **kwargs)
self.mne.annotations.append(annot)
onscreen_annotations[idx] = True
xy = (visible_segment.mean(), ylim[1])
text = ax.annotate(
descr,
xy,
xytext=(0, 9),
textcoords="offset points",
ha="center",
va="baseline",
color=segment_color,
)
self.mne.annotation_texts.append(text)
self.mne.onscreen_annotations = onscreen_annotations
# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
# CHANNEL SELECTION GUI
# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
def _create_selection_fig(self):
"""Create channel selection dialog window."""
from matplotlib.colors import to_rgb
from matplotlib.widgets import RadioButtons
# make figure
fig = self._new_child_figure(
figsize=(3, 7),
FigureClass=MNESelectionFigure,
fig_name="fig_selection",
window_title="Channel selection",
)
gs = fig.add_gridspec(15, 1)
# add sensor plot at top
fig.mne.sensor_ax = fig.add_subplot(gs[:5])
plot_sensors(
self.mne.info,
kind="select",
ch_type="all",
title="",
axes=fig.mne.sensor_ax,
ch_groups=self.mne.group_by,
show=False,
)
fig.subplots_adjust(bottom=0.01, top=0.99, left=0.01, right=0.99)
# style the sensors so the selection is easier to distinguish
fig.lasso.linewidth_selected = 2
self._update_highlighted_sensors()
# add radio button axes
radio_ax = fig.add_subplot(gs[5:-3], frame_on=False, aspect="equal")
fig.mne.radio_ax = radio_ax
selections_dict = self.mne.ch_selections
selections_dict.update(Custom=np.array([], dtype=int)) # for lasso
labels = list(selections_dict)
# make & style the radio buttons
activecolor = to_rgb(self.mne.fgcolor) + (0.5,)
radio_ax.buttons = RadioButtons(radio_ax, labels, activecolor=activecolor)
fig.mne.old_selection = 0
if _OLD_BUTTONS:
for circle in radio_ax.buttons.circles:
circle.set_radius(0.25 / len(labels))
circle.set_linewidth(2)
circle.set_edgecolor(self.mne.fgcolor)
fig._style_radio_buttons_butterfly()
# add instructions at bottom
instructions = (
"To use a custom selection, first click-drag on the sensor plot "
'to "lasso" the sensors you want to select, or hold Ctrl while '
"clicking individual sensors. Holding Ctrl while click-dragging "
"allows a lasso selection adding to (rather than replacing) the "
"existing selection."
)
instructions_ax = fig.add_subplot(gs[-3:], frame_on=False)
instructions_ax.text(
0.04, 0.08, instructions, va="bottom", ha="left", ma="left", wrap=True
)
instructions_ax.set_axis_off()
# add event listeners
radio_ax.buttons.on_clicked(fig._radiopress)
fig.lasso.callbacks.append(fig._set_custom_selection)
def _change_selection_vscroll(self, event):
"""Handle clicks on vertical scrollbar when using selections."""
buttons = self.mne.fig_selection.mne.radio_ax.buttons
labels = [label.get_text() for label in buttons.labels]
offset = 0
selections_dict = self.mne.ch_selections
for idx, label in enumerate(labels):
offset += len(selections_dict[label])
if event.ydata < offset:
with _events_off(buttons):
buttons.set_active(idx)
self.mne.fig_selection._radiopress(event)
return
def _update_selection(self):
"""Update visible channels based on selection dialog interaction."""
selections_dict = self.mne.ch_selections
fig = self.mne.fig_selection
buttons = fig.mne.radio_ax.buttons
label = buttons.value_selected
labels = [_label.get_text() for _label in buttons.labels]
self.mne.fig_selection.mne.old_selection = labels.index(label)
self.mne.picks = selections_dict[label]
self.mne.n_channels = len(self.mne.picks)
self._update_highlighted_sensors()
# if "Vertex" is defined, some channels appear twice, so if
# "Vertex" is selected, ch_start should be the *first* match;
# otherwise it should be the *last* match (since "Vertex" is
# always the first selection group, if it exists).
index = 0 if label == "Vertex" else -1
ch_order = np.concatenate(list(selections_dict.values()))
ch_start = np.where(ch_order == self.mne.picks[0])[0][index]
self.mne.ch_start = ch_start
self._update_trace_offsets()
self._update_vscroll()
self._redraw(annotations=True)
def _update_highlighted_sensors(self):
"""Update the sensor plot to show what is selected."""
inds = np.isin(
self.mne.fig_selection.lasso.names, self.mne.ch_names[self.mne.picks]
).nonzero()[0]
self.mne.fig_selection.lasso.select_many(inds)
def _update_bad_sensors(self, pick, mark_bad):
"""Update the sensor plot to reflect (un)marked bad channels."""
# replicate plotting order from plot_sensors(), to get index right
sensor_picks = list()
ch_indices = channel_indices_by_type(self.mne.info)
for this_type in _DATA_CH_TYPES_SPLIT:
if this_type in self.mne.ch_types:
sensor_picks.extend(ch_indices[this_type])
sensor_idx = np.isin(sensor_picks, pick).nonzero()[0]
# change the sensor color
fig = self.mne.fig_selection
fig.lasso.ec[sensor_idx, 0] = float(mark_bad) # change R of RGBA array
fig.lasso.collection.set_edgecolors(fig.lasso.ec)
fig.canvas.draw_idle()
# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
# PROJECTORS & BAD CHANNELS
# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
def _create_proj_fig(self):
"""Create the projectors dialog window."""
from matplotlib.widgets import Button, CheckButtons
projs = self.mne.projs
labels = [p["desc"] for p in projs]
for ix, active in enumerate(self.mne.projs_active):
if active:
labels[ix] += " (already applied)"
# make figure
width = max([4.5, max([len(label) for label in labels]) / 8 + 0.5])
height = (len(projs) + 1) / 6 + 1.5
fig = self._new_child_figure(
figsize=(width, height),
fig_name="fig_proj",
window_title="SSP projection vectors",
)
# pass through some proj fig keypresses to the parent
fig.canvas.mpl_connect(
"key_press_event", lambda ev: self._keypress(ev) if ev.key in "jJ" else None
)
# make axes
offset = 1 / 6 / height
position = (0, offset, 1, 0.8 - offset)
ax = fig.add_axes(position, frame_on=False, aspect="equal")
# make title
first_line = (
"Projectors already applied to the data are dimmed.\n"
if any(self.mne.projs_active)
else ""
)
second_line = 'Projectors marked with "X" are active on the plot.'
ax.set_title(f"{first_line}{second_line}")
# draw checkboxes
checkboxes = CheckButtons(
ax,
labels=labels,
actives=self.mne.projs_on,
**_get_check_kwargs(labels=labels),
)
# gray-out already applied projectors
if _OLD_BUTTONS:
for label, rect, lines in zip(
checkboxes.labels, checkboxes.rectangles, checkboxes.lines
):
if label.get_text().endswith("(already applied)"):
label.set_color("0.5")
rect.set_edgecolor("0.7")
[x.set_color("0.7") for x in lines]
rect.set_linewidth(1)
# add "toggle all" button
ax_all = fig.add_axes((0.25, 0.01, 0.5, offset), frame_on=True)
fig.mne.proj_all = Button(ax_all, "Toggle all")
# add event listeners
checkboxes.on_clicked(self._toggle_proj_checkbox)
fig.mne.proj_all.on_clicked(
partial(self._toggle_proj_checkbox, toggle_all=True)
)
# save params
fig.mne.proj_checkboxes = checkboxes
# show figure
self.mne.fig_proj.canvas.draw()
plt_show(fig=self.mne.fig_proj, warn=False)
def _toggle_proj_fig(self, event=None):
"""Show/hide the projectors dialog window."""
if self.mne.fig_proj is None:
self._create_proj_fig()
else:
plt.close(self.mne.fig_proj)
def _toggle_proj_checkbox(self, event, toggle_all=False):
"""Perform operations when proj boxes clicked."""
on = self.mne.projs_on
applied = self.mne.projs_active
fig = self.mne.fig_proj
new_state = (
np.full_like(on, not all(on))
if toggle_all
else np.array(fig.mne.proj_checkboxes.get_status())
)
# update Xs when toggling all
if fig is not None:
if toggle_all:
with _events_off(fig.mne.proj_checkboxes):
for ix in np.where(on != new_state)[0]:
fig.mne.proj_checkboxes.set_active(ix)
# don't allow disabling already-applied projs
with _events_off(fig.mne.proj_checkboxes):
for ix in np.where(applied)[0]:
if not new_state[ix]:
fig.mne.proj_checkboxes.set_active(ix)
new_state[applied] = True
# update the data if necessary
if not np.array_equal(on, new_state):
self.mne.projs_on = new_state
self._update_projector()
self._redraw()
def _toggle_epoch_histogram(self):
"""Show or hide peak-to-peak histogram of channel amplitudes."""
if self.mne.instance_type == "epochs":
if self.mne.fig_histogram is None:
self._create_epoch_histogram()
else:
plt.close(self.mne.fig_histogram)
def _toggle_bad_channel(self, idx):
"""Mark/unmark bad channels; `idx` is index of *visible* channels."""
color, pick, marked_bad = super()._toggle_bad_channel(idx)
# update sensor color (if in selection mode)
if self.mne.fig_selection is not None:
self._update_bad_sensors(pick, marked_bad)
# update vscroll color
vscroll_idx = (self.mne.ch_order == pick).nonzero()[0]
for _idx in vscroll_idx:
self.mne.ax_vscroll.patches[_idx].set_color(color)
# redraw
self._redraw()
def _toggle_bad_epoch(self, event):
"""Mark/unmark bad epochs."""
epoch_ix, color = super()._toggle_bad_epoch(event.xdata)
self.mne.ax_hscroll.patches[epoch_ix].set_color(color)
self._redraw(update_data=False)
# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
# SCROLLBARS
# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
def _update_zen_mode_offsets(self):
"""Compute difference between main axes edges and scrollbar edges."""
self.mne.fig_size_px = self._get_size_px()
self.mne.zen_w = (
self.mne.ax_vscroll.get_position().xmax
- self.mne.ax_main.get_position().xmax
)
self.mne.zen_h = (
self.mne.ax_main.get_position().ymin
- self.mne.ax_hscroll.get_position().ymin
)
def _toggle_scrollbars(self):
"""Show or hide scrollbars (A.K.A. zen mode)."""
self._update_zen_mode_offsets()
# grow/shrink main axes to take up space from (or make room for)
# scrollbars. We can't use ax.set_position() because axes are
# locatable, so we use subplots_adjust
should_show = not self.mne.scrollbars_visible
margins = {
side: getattr(self.subplotpars, side)
for side in ("left", "bottom", "right", "top")
}
# if should_show, bottom margin moves up; right margin moves left
margins["bottom"] += (1 if should_show else -1) * self.mne.zen_h
margins["right"] += (-1 if should_show else 1) * self.mne.zen_w
self.subplots_adjust(**margins)
# handle x-axis label
self.mne.zen_xlabel.set_visible(not should_show)
# show/hide other UI elements
for elem in ("ax_hscroll", "ax_vscroll", "ax_proj", "ax_help"):
if elem == "ax_vscroll" and self.mne.butterfly:
continue
# sometimes we don't have a proj button (ax_proj)
if getattr(self.mne, elem, None) is not None:
getattr(self.mne, elem).set_visible(should_show)
self.mne.scrollbars_visible = should_show
def _update_vscroll(self):
"""Update the vertical scrollbar (channel) selection indicator."""
self.mne.vsel_patch.set_xy((0, self.mne.ch_start))
self.mne.vsel_patch.set_height(self.mne.n_channels)
self._update_yaxis_labels()
def _update_hscroll(self):
"""Update the horizontal scrollbar (time) selection indicator."""
self.mne.hsel_patch.set_xy((self.mne.t_start, 0))
self.mne.hsel_patch.set_width(self.mne.duration)
def _check_update_hscroll_clicked(self, event):
"""Handle clicks on horizontal scrollbar."""
time = event.xdata - self.mne.duration / 2
max_time = (
self.mne.n_times / self.mne.info["sfreq"]
+ self.mne.first_time
- self.mne.duration
)
time = np.clip(time, self.mne.first_time, max_time)
if self.mne.is_epochs:
ix = np.searchsorted(self.mne.boundary_times[1:], time)
time = self.mne.boundary_times[ix]
if self.mne.t_start != time:
self.mne.t_start = time
self._update_hscroll()
return True
return False
def _check_update_vscroll_clicked(self, event):
"""Update vscroll patch on click, return True if location changed."""
new_ch_start = np.clip(
int(round(event.ydata - self.mne.n_channels / 2)),
0,
len(self.mne.ch_order) - self.mne.n_channels,
)
if self.mne.ch_start != new_ch_start:
self.mne.ch_start = new_ch_start
self._update_picks()
self._update_vscroll()
return True
return False
# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
# SCALEBARS & AXIS LABELS
# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
def _show_scalebars(self):
"""Add channel scale bars."""
for pi, pick in enumerate(self.mne.picks):
this_name = self.mne.ch_names[pick]
this_type = self.mne.ch_types[pick]
# TODO: Simplify this someday -- we have to duplicate the challenging
# logic of _draw_traces here
offset_ixs = (
self.mne.picks
if self.mne.butterfly and self.mne.ch_selections is None
else slice(None)
)
offset = self.mne.trace_offsets[offset_ixs][pi]
if (
this_type not in self.mne.scalebars
and this_type != "stim"
and this_type in self.mne.scalings
and this_type in getattr(self.mne, "units", {})
and this_type in getattr(self.mne, "unit_scalings", {})
and this_name not in self.mne.info["bads"]
and this_name not in self.mne.whitened_ch_names
):
x = (self.mne.times[0] + self.mne.first_time,) * 2
denom = 4 if self.mne.butterfly else 2
y = tuple(np.array([-1, 1]) / denom + offset)
self._draw_one_scalebar(x, y, this_type)
if self.mne.is_epochs:
x = (
self.mne.times[0],
self.mne.times[0] + self.mne.boundary_times[1] / 2,
)
y_value = self.mne.n_channels - 0.5
y = (y_value, y_value)
self._draw_one_scalebar(x, y, "time")
def _hide_scalebars(self):
"""Remove channel scale bars."""
for bar in self.mne.scalebars.values():
bar.remove()
for text in self.mne.scalebar_texts.values():
text.remove()
self.mne.scalebars = dict()
self.mne.scalebar_texts = dict()
def _toggle_scalebars(self, event):
"""Show/hide the scalebars."""
if self.mne.scalebars_visible:
self._hide_scalebars()
else:
self._update_picks()
self._show_scalebars()
# toggle
self.mne.scalebars_visible = not self.mne.scalebars_visible
self._redraw(update_data=False)
def _draw_one_scalebar(self, x, y, ch_type):
"""Draw a scalebar."""
from .utils import _simplify_float
color = "#AA3377" # purple
kwargs = dict(color=color, zorder=self.mne.zorder["scalebar"])
if ch_type == "time":
label = f"{self.mne.boundary_times[1] / 2:.2f} s"
text = self.mne.ax_main.text(
x[0] + 0.015,
y[1] - 0.05,
label,
va="bottom",
ha="left",
size="xx-small",
**kwargs,
)
else:
scaler = 1 if self.mne.butterfly else 2
inv_norm = (
scaler
* self.mne.scalings[ch_type]
* self.mne.unit_scalings[ch_type]
/ self.mne.scale_factor
)
label = f"{_simplify_float(inv_norm)} {self.mne.units[ch_type]} "
text = self.mne.ax_main.text(
x[1], y[1], label, va="baseline", ha="right", size="xx-small", **kwargs
)
bar = self.mne.ax_main.plot(x, y, lw=4, **kwargs)[0]
self.mne.scalebars[ch_type] = bar
self.mne.scalebar_texts[ch_type] = text
def _update_yaxis_labels(self):
"""Change the y-axis labels."""
if self.mne.butterfly and self.mne.fig_selection is not None:
exclude = ("Vertex", "Custom")
ticklabels = list(self.mne.ch_selections)
keep_mask = np.isin(ticklabels, exclude, invert=True)
ticklabels = [
t.replace("Left-", "L-").replace("Right-", "R-") for t in ticklabels
] # avoid having to rotate labels
ticklabels = np.array(ticklabels)[keep_mask]
elif self.mne.butterfly:
_, ixs, _ = np.intersect1d(
_DATA_CH_TYPES_ORDER_DEFAULT, self.mne.ch_types, return_indices=True
)
ixs.sort()
ticklabels = np.array(_DATA_CH_TYPES_ORDER_DEFAULT)[ixs]
else:
ticklabels = self.mne.ch_names[self.mne.picks]
texts = self.mne.ax_main.set_yticklabels(ticklabels, picker=True)
for text in texts:
sty = (
"italic" if text.get_text() in self.mne.whitened_ch_names else "normal"
)
text.set_style(sty)
def _xtick_formatter(self, x, pos=None, ax_type="main"):
"""Change the x-axis labels."""
tickdiff = np.diff(self.mne.ax_main.get_xticks())[0]
digits = np.ceil(-np.log10(tickdiff) + 1).astype(int)
# always show millisecond precision for vline text
if ax_type == "vline":
digits = 3
if self.mne.time_format == "float":
# round to integers when possible ('9.0' → '9')
if int(x) == x:
digits = None
if ax_type == "vline":
return f"{round(x, digits)} s"
return str(round(x, digits))
# format as timestamp
meas_date = self.mne.inst.info["meas_date"]
first_time = datetime.timedelta(seconds=self.mne.inst.first_time)
xtime = datetime.timedelta(seconds=x)
xdatetime = meas_date + first_time + xtime
xdtstr = xdatetime.strftime("%H:%M:%S")
if digits and ax_type != "hscroll" and int(xdatetime.microsecond):
xdtstr += f"{round(xdatetime.microsecond * 1e-6, digits)}"[1:]
return xdtstr
def _toggle_time_format(self):
if self.mne.time_format == "float":
self.mne.time_format = "clock"
x_axis_label = "Time (HH:MM:SS)"
else:
self.mne.time_format = "float"
x_axis_label = "Time (s)"
# Change x-axis label
for _ax in (self.mne.ax_main, self.mne.ax_hscroll):
_ax.set_xlabel(x_axis_label)
self._redraw(update_data=False, annotations=False)
# Update vline-text if displayed
if self.mne.vline is not None and self.mne.vline.get_visible():
self._show_vline(self.mne.vline.get_xdata())
# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
# DATA TRACES
# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
def _toggle_butterfly(self):
"""Enter or leave butterfly mode."""
self.mne.ax_vscroll.set_visible(self.mne.butterfly)
self.mne.butterfly = not self.mne.butterfly
self.mne.scale_factor *= 0.5 if self.mne.butterfly else 2.0
self._update_picks()
self._update_trace_offsets()
self._redraw(annotations=True)
if self.mne.fig_selection is not None:
self.mne.fig_selection._style_radio_buttons_butterfly()
def _update_trace_offsets(self):
"""Compute viewport height and adjust offsets."""
# simultaneous selection and butterfly modes
if self.mne.butterfly and self.mne.ch_selections is not None:
self._update_picks()
selections_dict = self._make_butterfly_selections_dict()
n_offsets = len(selections_dict)
sel_order = list(selections_dict)
offsets = np.array([])
for pick in self.mne.picks:
for sel in sel_order:
if pick in selections_dict[sel]:
offsets = np.append(offsets, sel_order.index(sel))
# butterfly only
elif self.mne.butterfly:
unique_ch_types = set(self.mne.ch_types)
n_offsets = len(unique_ch_types)
ch_type_order = [
_type
for _type in _DATA_CH_TYPES_ORDER_DEFAULT
if _type in unique_ch_types
]
offsets = np.array(
[ch_type_order.index(ch_type) for ch_type in self.mne.ch_types]
)
# normal mode
else:
n_offsets = self.mne.n_channels
offsets = np.arange(n_offsets, dtype=float)
# update ylim, ticks, vertline, and scrollbar patch
ylim = (n_offsets - 0.5, -0.5) # inverted y axis → new chs at bottom
self.mne.ax_main.set_ylim(ylim)
self.mne.ax_main.set_yticks(np.unique(offsets))
self.mne.vsel_patch.set_height(self.mne.n_channels)
# store new offsets, update axis labels
self.mne.trace_offsets = offsets
self._update_yaxis_labels()
def _draw_traces(self):
"""Draw (or redraw) the channel data."""
from matplotlib.colors import to_rgba_array
from matplotlib.patches import Rectangle
# clear scalebars
if self.mne.scalebars_visible:
self._hide_scalebars()
# get info about currently visible channels
picks = self.mne.picks
ch_names = self.mne.ch_names[picks]
ch_types = self.mne.ch_types[picks]
offset_ixs = (
picks
if self.mne.butterfly and self.mne.ch_selections is None
else slice(None)
)
offsets = self.mne.trace_offsets[offset_ixs]
bad_bool = np.isin(ch_names, self.mne.info["bads"])
# colors
good_ch_colors = [self.mne.ch_color_dict[_type] for _type in ch_types]
ch_colors = to_rgba_array(
[
self.mne.ch_color_bad if _bad else _color
for _bad, _color in zip(bad_bool, good_ch_colors)
]
)
self.mne.ch_colors = np.array(good_ch_colors) # use for unmarking bads
labels = self.mne.ax_main.yaxis.get_ticklabels()
if self.mne.butterfly:
for label in labels:
label.set_color(self.mne.fgcolor)
else:
for label, color in zip(labels, ch_colors):
label.set_color(color)
# decim
decim = np.ones_like(picks)
data_picks_mask = np.isin(picks, self.mne.picks_data)
decim[data_picks_mask] = self.mne.decim
# decim can vary by channel type, so compute different `times` vectors
decim_times = {
decim_value: self.mne.times[::decim_value] + self.mne.first_time
for decim_value in set(decim)
}
# add more traces if needed
n_picks = len(picks)
if n_picks > len(self.mne.traces):
n_new_chs = n_picks - len(self.mne.traces)
new_traces = self.mne.ax_main.plot(
np.full((1, n_new_chs), np.nan), **self.mne.trace_kwargs
)
self.mne.traces.extend(new_traces)
# remove extra traces if needed
extra_traces = self.mne.traces[n_picks:]
for trace in extra_traces:
trace.remove()
self.mne.traces = self.mne.traces[:n_picks]
# check for bad epochs
time_range = (self.mne.times + self.mne.first_time)[[0, -1]]
if self.mne.instance_type == "epochs":
epoch_ix = np.searchsorted(self.mne.boundary_times, time_range)
epoch_ix = np.arange(epoch_ix[0], epoch_ix[1])
epoch_nums = self.mne.inst.selection[epoch_ix[0] : epoch_ix[-1] + 1]
(visible_bad_epoch_ix,) = np.isin(epoch_nums, self.mne.bad_epochs).nonzero()
while len(self.mne.epoch_traces):
self.mne.epoch_traces.pop(-1).remove()
# handle custom epoch colors (for autoreject integration)
if self.mne.epoch_colors is None:
# shape: n_traces × RGBA → n_traces × n_epochs × RGBA
custom_colors = np.tile(
ch_colors[:, None, :], (1, self.mne.n_epochs, 1)
)
else:
custom_colors = np.empty((len(self.mne.picks), self.mne.n_epochs, 4))
for ii, _epoch_ix in enumerate(epoch_ix):
this_colors = self.mne.epoch_colors[_epoch_ix]
custom_colors[:, ii] = to_rgba_array(
[this_colors[_ch] for _ch in picks]
)
# override custom color on bad epochs
for _ix in visible_bad_epoch_ix:
_cols = np.array(
[self.mne.epoch_color_bad, self.mne.ch_color_bad], dtype=object
)[bad_bool.astype(int)]
custom_colors[:, _ix] = to_rgba_array(_cols)
# update traces
ylim = self.mne.ax_main.get_ylim()
for ii, line in enumerate(self.mne.traces):
this_name = ch_names[ii]
this_type = ch_types[ii]
this_offset = offsets[ii]
this_times = decim_times[decim[ii]]
this_data = this_offset - self.mne.data[ii] * self.mne.scale_factor
this_data = this_data[..., :: decim[ii]]
# clip
if self.mne.clipping == "clamp":
this_data = np.clip(this_data, -0.5, 0.5)
elif self.mne.clipping is not None:
clip = self.mne.clipping * (0.2 if self.mne.butterfly else 1)
bottom = max(this_offset - clip, ylim[1])
height = min(2 * clip, ylim[0] - bottom)
rect = Rectangle(
xy=np.array([time_range[0], bottom]),
width=time_range[1] - time_range[0],
height=height,
transform=self.mne.ax_main.transData,
)
line.set_clip_path(rect)
# prep z order
is_bad_ch = this_name in self.mne.info["bads"]
this_z = self.mne.zorder["bads" if is_bad_ch else "data"]
if self.mne.butterfly and not is_bad_ch:
this_z = self.mne.zorder.get(this_type, this_z)
# plot each trace multiple times to get the desired epoch coloring.
# use masked arrays to plot discontinuous epochs that have the same
# color in a single plot() call.
if self.mne.instance_type == "epochs":
this_colors = custom_colors[ii]
for cix, color in enumerate(np.unique(this_colors, axis=0)):
bool_ixs = (this_colors == color).all(axis=1)
mask = np.zeros_like(this_times, dtype=bool)
_starts = self.mne.boundary_times[epoch_ix][bool_ixs]
_stops = self.mne.boundary_times[epoch_ix + 1][bool_ixs]
for _start, _stop in zip(_starts, _stops):
_mask = np.logical_and(_start < this_times, this_times <= _stop)
mask = mask | _mask
_times = np.ma.masked_array(this_times, mask=~mask)
# always use the existing traces first
if cix == 0:
line.set_xdata(_times)
line.set_ydata(this_data)
line.set_color(color)
line.set_zorder(this_z)
else: # make new traces as needed
_trace = self.mne.ax_main.plot(
_times,
this_data,
color=color,
zorder=this_z,
**self.mne.trace_kwargs,
)
self.mne.epoch_traces.extend(_trace)
else:
line.set_xdata(this_times)
line.set_ydata(this_data)
line.set_color(ch_colors[ii])
line.set_zorder(this_z)
# update xlim
self.mne.ax_main.set_xlim(*time_range)
# draw scalebars maybe
if self.mne.scalebars_visible:
self._show_scalebars()
# redraw event lines
if self.mne.event_times is not None:
self._draw_event_lines()
def _redraw(self, update_data=True, annotations=False):
"""Redraw (convenience method for frequently grouped actions)."""
super()._redraw(update_data, annotations)
if self.mne.vline_visible and self.mne.is_epochs:
# prevent flickering
_ = self._recompute_epochs_vlines(None)
self.canvas.draw_idle()
# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
# EVENT LINES AND MARKER LINES
# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
def _draw_event_lines(self):
"""Draw the event lines and their labels."""
from matplotlib.collections import LineCollection
from matplotlib.colors import to_rgba_array
if self.mne.event_nums is not None:
mask = np.logical_and(
self.mne.event_times >= self.mne.times[0],
self.mne.event_times <= self.mne.times[-1],
)
this_event_times = self.mne.event_times[mask]
this_event_nums = self.mne.event_nums[mask]
n_visible_events = len(this_event_times)
colors = to_rgba_array(
[self.mne.event_color_dict[n] for n in this_event_nums]
)
# create event lines
ylim = self.mne.ax_main.get_ylim()
xs = np.repeat(this_event_times, 2)
ys = np.tile(ylim, n_visible_events)
segs = np.vstack([xs, ys]).T.reshape(n_visible_events, 2, 2)
event_lines = LineCollection(
segs, linewidths=0.5, colors=colors, zorder=self.mne.zorder["events"]
)
self.mne.ax_main.add_collection(event_lines)
self.mne.event_lines = event_lines
# create event labels
while len(self.mne.event_texts):
self.mne.event_texts.pop().remove()
for _t, _n, _c in zip(this_event_times, this_event_nums, colors):
label = self.mne.event_id_rev.get(_n, _n)
this_text = self.mne.ax_main.annotate(
label,
(_t, ylim[1]),
ha="center",
va="baseline",
color=self.mne.fgcolor,
xytext=(0, 2),
textcoords="offset points",
fontsize=8,
)
self.mne.event_texts.append(this_text)
def _recompute_epochs_vlines(self, xdata):
"""Recompute vline x-coords for epochs plots (after scrolling, etc)."""
# special case: changed view duration w/ "home" or "end" key
# (no click event, hence no xdata)
if xdata is None:
xdata = np.array(self.mne.vline.get_segments())[0, 0, 0]
# compute the (continuous) times for the lines on each epoch
epoch_dur = np.diff(self.mne.boundary_times[:2])[0]
rel_time = xdata % epoch_dur
abs_time = self.mne.times[0]
xs = np.arange(self.mne.n_epochs) * epoch_dur + abs_time + rel_time
segs = np.array(self.mne.vline.get_segments())
# recreate segs from scratch in case view duration changed
# (i.e., handle case when n_segments != n_epochs)
segs = np.tile([[0.0], [1.0]], (len(xs), 1, 2)) # y values
segs[..., 0] = np.tile(xs[:, None], 2) # x values
self.mne.vline.set_segments(segs)
return rel_time
def _show_vline(self, xdata):
"""Show the vertical line(s)."""
if self.mne.is_epochs:
# convert xdata to be epoch-relative (for the text)
rel_time = self._recompute_epochs_vlines(xdata)
xdata = rel_time + self.mne.inst.times[0]
else:
self.mne.vline.set_xdata([xdata])
self.mne.vline_hscroll.set_xdata([xdata])
text = self._xtick_formatter(xdata, ax_type="vline")[:12]
self.mne.vline_text.set_text(text)
self._toggle_vline(True)
def _toggle_vline(self, visible):
"""Show or hide the vertical line(s)."""
for artist in (self.mne.vline, self.mne.vline_hscroll, self.mne.vline_text):
if artist is not None:
artist.set_visible(visible)
self.draw_artist(artist)
self.mne.vline_visible = visible
self.canvas.draw_idle()
# workaround: plt.close() doesn't spawn close_event on Agg backend, this method
# can be removed once the _close_event in fixes.py is removed
def _close_event(self, fig=None):
"""Force calling of the MPL figure close event."""
fig = fig or self
_close_event(fig)
def _fake_keypress(self, key, fig=None):
fig = fig or self
_fake_keypress(fig, key)
def _fake_click(
self,
point,
add_points=None,
fig=None,
ax=None,
xform="ax",
button=1,
kind="press",
):
"""Fake a click at a relative point within axes."""
fig = fig or self
ax = ax or self.mne.ax_main
if kind == "drag" and add_points is not None:
_fake_click(
fig=fig, ax=ax, point=point, xform=xform, button=button, kind="press"
)
for apoint in add_points:
_fake_click(
fig=fig,
ax=ax,
point=apoint,
xform=xform,
button=button,
kind="motion",
)
_fake_click(
fig=fig,
ax=ax,
point=add_points[-1],
xform=xform,
button=button,
kind="release",
)
else:
_fake_click(
fig=fig, ax=ax, point=point, xform=xform, button=button, kind=kind
)
def _fake_scroll(self, x, y, step, fig=None):
fig = fig or self
_fake_scroll(fig, x, y, step)
def _click_ch_name(self, ch_index, button):
_click_ch_name(self, ch_index, button)
def _resize_by_factor(self, factor=None):
size = self.canvas.manager.canvas.get_width_height()
if isinstance(factor, tuple):
size = int(size[0] * factor[0], size[1] * factor[1])
else:
size = [int(x * factor) for x in size]
self.canvas.manager.resize(*size)
def _get_ticklabels(self, orientation):
if orientation == "x":
labels = self.mne.ax_main.get_xticklabels(minor=self.mne.is_epochs)
elif orientation == "y":
labels = self.mne.ax_main.get_yticklabels()
label_texts = [lb.get_text() for lb in labels]
return label_texts
def _get_scale_bar_texts(self):
texts = tuple(t.get_text().strip() for t in self.mne.ax_main.texts)
# First text is empty because of vline
texts = texts[1:]
return texts
class MNELineFigure(MNEFigure):
"""Interactive figure for non-scrolling line plots."""
def __init__(self, inst, n_axes, figsize, *, layout="constrained", **kwargs):
super().__init__(
figsize=figsize,
inst=inst,
layout=layout,
sharex=True,
**kwargs,
)
for ix in range(n_axes):
self.add_subplot(n_axes, 1, ix + 1)
def _close_all():
"""Close all figures (only used in our tests)."""
plt.close("all")
def _get_n_figs():
return len(plt.get_fignums())
def _figure(toolbar=True, FigureClass=MNEFigure, **kwargs):
"""Instantiate a new figure."""
from matplotlib import rc_context
title = kwargs.pop("window_title", None) # extract title before init
if "layout" not in kwargs:
kwargs["layout"] = "constrained"
rc = dict() if toolbar else dict(toolbar="none")
with rc_context(rc=rc):
fig = plt.figure(FigureClass=FigureClass, **kwargs)
# BACKEND defined globally at the top of this file
fig.mne.backend = BACKEND
if title is not None:
_set_window_title(fig, title)
# TODO: for some reason for topomaps->_prepare_trellis the layout=constrained does
# not work the first time (maybe toolbar=False?)
if kwargs.get("layout") == "constrained":
fig.set_layout_engine("constrained")
# add event callbacks
fig._add_default_callbacks()
return fig
def _line_figure(inst, axes=None, picks=None, **kwargs):
"""Instantiate a new line figure."""
from matplotlib.axes import Axes
# if picks is None, only show data channels
allowed_ch_types = _DATA_CH_TYPES_SPLIT if picks is None else _VALID_CHANNEL_TYPES
# figure out expected number of axes
ch_types = np.array(inst.get_channel_types())
if picks is not None:
ch_types = ch_types[picks]
n_axes = len(np.intersect1d(ch_types, allowed_ch_types))
# handle user-provided axes
if axes is not None:
if isinstance(axes, Axes):
axes = [axes]
_validate_if_list_of_axes(axes, n_axes)
fig = axes[0].get_figure()
else:
figsize = kwargs.pop("figsize", (10, 2.5 * n_axes + 1))
fig = _figure(
inst=inst,
toolbar=True,
FigureClass=MNELineFigure,
figsize=figsize,
n_axes=n_axes,
**kwargs,
)
fig.mne.fig_size_px = fig._get_size_px() # can't do in __init__
axes = fig.axes
return fig, axes
def _split_picks_by_type(inst, picks, units, scalings, titles):
"""Separate picks, units, etc, for plotting on separate subplots."""
picks_list = list()
units_list = list()
scalings_list = list()
titles_list = list()
# if picks is None, only show data channels
allowed_ch_types = _DATA_CH_TYPES_SPLIT if picks is None else _VALID_CHANNEL_TYPES
for ch_type in allowed_ch_types:
pick_kwargs = dict(meg=False, ref_meg=False, exclude=[])
if ch_type in ("mag", "grad"):
pick_kwargs["meg"] = ch_type
elif ch_type in _FNIRS_CH_TYPES_SPLIT:
pick_kwargs["fnirs"] = ch_type
elif ch_type in _EYETRACK_CH_TYPES_SPLIT:
pick_kwargs["eyetrack"] = ch_type
else:
pick_kwargs[ch_type] = True
these_picks = pick_types(inst.info, **pick_kwargs)
these_picks = np.intersect1d(these_picks, picks)
if len(these_picks) > 0:
picks_list.append(these_picks)
units_list.append(units[ch_type])
scalings_list.append(scalings[ch_type])
titles_list.append(titles[ch_type])
if len(picks_list) == 0:
raise RuntimeError("No data channels found")
return picks_list, units_list, scalings_list, titles_list
def _calc_new_margins(fig, old_width, old_height, new_width, new_height):
"""Compute new figure-relative values to maintain fixed-size margins."""
new_margins = dict()
for side in ("left", "right", "bottom", "top"):
ratio = (
(old_width / new_width)
if side in ("left", "right")
else (old_height / new_height)
)
rel_dim = getattr(fig.subplotpars, side)
if side in ("right", "top"):
new_margins[side] = 1 - ratio * (1 - rel_dim)
else:
new_margins[side] = ratio * rel_dim
# gh-8304: don't allow resizing too small
if (
new_margins["bottom"] < new_margins["top"]
and new_margins["left"] < new_margins["right"]
):
return new_margins
@contextmanager
def _patched_canvas(fig):
old_canvas = fig.canvas
if fig.canvas is None: # XXX old MPL (at least 3.0.3) does this for Agg
fig.canvas = Bunch(mpl_connect=lambda event, callback: None)
try:
yield
finally:
fig.canvas = old_canvas
def _init_browser(**kwargs):
"""Instantiate a new MNE browse-style figure."""
from mne.io import BaseRaw
fig = _figure(toolbar=False, FigureClass=MNEBrowseFigure, layout=None, **kwargs)
# splash is ignored (maybe we could do it for mpl if we get_backend() and
# check if it's Qt... but seems overkill)
# initialize zen mode
# (can't do in __init__ due to get_position() calls)
fig.canvas.draw()
fig._update_zen_mode_offsets()
fig._resize(None) # needed for MPL
# if scrollbars are supposed to start hidden,
# set to True and then toggle
if not fig.mne.scrollbars_visible:
fig.mne.scrollbars_visible = True
fig._toggle_scrollbars()
# Initialize parts of the plot
is_ica = fig.mne.instance_type == "ica"
if not is_ica:
# make channel selection dialog,
# if requested (doesn't work well in init)
if fig.mne.group_by in ("selection", "position"):
fig._create_selection_fig()
# start with projectors dialog open, if requested
if getattr(fig.mne, "show_options", False):
fig._toggle_proj_fig()
# update data, and plot
fig._update_trace_offsets()
fig._redraw(update_data=True, annotations=False)
if isinstance(fig.mne.inst, BaseRaw):
fig._setup_annotation_colors()
fig._draw_annotations()
return fig
def _get_check_kwargs(labels=None):
check_kwargs = dict()
if not _OLD_BUTTONS:
check_kwargs.update(
check_props=dict(s=144, clip_on=False),
frame_props=dict(s=144, clip_on=False),
)
if labels is not None:
textcolor = list()
checkcolor = list()
for label in labels:
if label.endswith("(already applied)"):
textcolor.append("0.5")
checkcolor.append("0.7")
else:
textcolor.append("k")
checkcolor.append("k")
check_kwargs["check_props"].update(facecolor=checkcolor, linewidth=1)
check_kwargs["frame_props"].update(edgecolor=checkcolor, linewidth=1)
check_kwargs["label_props"] = dict(color=textcolor)
return check_kwargs
Datasets
Models
