eelbrain.plot.TopoButterfly

class eelbrain.plot.TopoButterfly(y, xax=None, data=None, sub=None, vmax=None, vmin=None, cmap=None, contours=None, color=None, linewidth=None, t=None, proj='default', res=None, interpolation=None, clip='even', clip_distance=0.05, head_radius=None, head_pos=0, im_interpolation=None, sensors='.', sensorlabels=None, mark=None, mcolor=None, xlabel=True, ylabel=True, xticklabels='bottom', yticklabels='left', axtitle=True, frame=True, xlim=None, **kwargs)

Butterfly plot with corresponding topomaps

Parameters:

  • y (NDVarArg | Sequence[NDVarArg] | Sequence[Sequence[NDVarArg]]) – Data to plot. A plain NDVar or list of NDVar produces the standard single-topomap layout. A list of lists enables a multi-modality layout: each inner list represents one plot row and contains one NDVar per sensor modality (e.g. [[mag_original, eeg_original], [mag_cleaned, eeg_cleaned]]). In this case the butterfly traces for each row are formed by concatenating all modalities after normalizing each one to its data range (determined via vmax/vmin or derived automatically from the data), so that channels with very different physical units are visible on a common axis. One topomap column is added to the right for each modality, each with its own color scale. Scaling is shared per modality column across rows, so relative amplitudes between rows are preserved.

  • xax (CategorialArg) – Create a separate plot for each cell in this model.

  • data (Dataset) – If a Dataset is provided, data can be specified as strings.

  • sub (IndexArg) – Specify a subset of the data.

  • vmax (float) – Upper limits for the colormap (default is determined from data).

  • vmin (float) – Lower limit for the colormap (default -vmax).

  • cmap (CMapArg) – Colormap (default depends on the data).

  • contours (int | Sequence | dict) – Draw contours. Can be an int (number of contours, including vmin and vmax), a sequence (values at which to draw contours), or a dictionary with **kwargs for contour() (must include a "levels" key). Default is no contours.

  • color (matplotlib color) – Color of the butterfly plots.

  • linewidth (scalar) – Linewidth for plots (defult is to use matplotlib.rcParams).

  • t (float) – Time to display in the topomap.

  • proj (str) – The sensor projection to use for topomaps.

  • res (int) – Resolution of the topomaps (width = height = res).

  • interpolation (InterpolationArg) – Method for interpolating topo-map between sensors (default is based on mne-python).

  • clip (bool | 'even' | 'circle') – Outline for clipping topomaps: ‘even’ to clip at a constant distance (default), ‘circle’ to clip using a circle.

  • clip_distance (scalar) – How far from sensor locations to clip (1 is the axes height/width).

  • head_radius (scalar | tuple) – Radius of the head outline drawn over sensors (on sensor plots with normalized positions, 0.45 is the outline of the topomap); 0 to plot no outline; tuple for separate (right, anterior) radius. The default is determined automatically.

  • head_pos (scalar) – Head outline position along the anterior axis (0 is the center, 0.5 is the top end of the plot).

  • im_interpolation (str) – Topomap image interpolation (see Matplotlib’s imshow()). Matplotlib 1.5.3’s SVG output can’t handle uneven aspect with interpolation='none', use interpolation='nearest' instead.

  • sensors (str | matplotlib.markers.MarkerStyle) – How to mark sensor locations in the topomap (empty string '' to omit marks).

  • sensorlabels (SensorLabelsArg) – Show sensor labels. For ‘name’, any prefix common to all names is removed; with ‘fullname’, the full name is shown.

  • mark (Sensor index) – Sensors to mark in the topo-map. To highlight sensors in the butterfly plot, consider using NDVar.mask() on y.

  • mcolor (matplotlib color) – Color for marked sensors.

  • xlabel (bool | str) – X-axis label. By default the label is inferred from the data.

  • ylabel (bool | str) – Y-axis label. By default the label is inferred from the data.

  • xticklabels (str | int | Sequence[int]) – Specify which axes should be annotated with x-axis tick labels. Use int for a single axis, a sequence of int for multiple specific axes, or one of 'left' | 'bottom' | 'all' | 'none'.

  • yticklabels (str | int | Sequence[int]) – Specify which axes should be annotated with y-axis tick labels. Use int for a single axis, a sequence of int for multiple specific axes, or one of 'left' | 'bottom' | 'all' | 'none'.

  • axtitle (bool | sequence of str) – Title for the individual axes. The default is to show the names of the epochs, but only if multiple axes are plotted.

  • xlim (scalar | (scalar, scalar)) – Initial x-axis view limits as (left, right) tuple or as length scalar (default is the full x-axis in the data).

  • ... – Also accepts General layout parameters.

  • frame (bool)

Notes

Topomap control:

  • LMB click in a butterfly plot fixates the topomap time

  • RMB click in a butterfly plot removes the time point, the topomaps follow the mouse pointer

  • .: Increment the current topomap time (got right)

  • ,: Decrement the current topomap time (go left)

  • t: open a Topomap plot for the time point under the mouse pointer

  • T: open a larger Topomap plot with visible sensor names for the time point under the mouse pointer

Navigation:

  • ↑: scroll up

  • ↓: scroll down

  • ←: scroll left

  • →: scroll right

  • home: scroll to beginning

  • end: scroll to end

  • f: x-axis zoom in (reduce x axis range)

  • d: x-axis zoom out (increase x axis range)

  • r: y-axis zoom in (reduce y-axis range)

  • c: y-axis zoom out (increase y-axis range)

Methods

add_contour(level[, color, meas])

Add a contour line

add_hline(y[, axes])

Draw a horizontal line on one or more axes

add_hspan(bottom, top[, axes])

Draw a horizontal bar on one or more axes

add_vline(x[, axes])

Draw a vertical line on one or more axes

add_vspan(xmin, xmax[, axes])

Draw a vertical bar on one or more axes

add_vspans(intervals[, axes])

Draw vertical bars over axes

close()

Close the figure.

draw()

(Re-)draw the figure (after making manual changes).

draw_crosshairs([enable])

Draw crosshairs under the cursor

draw_outline([color])

Draw the outline of the figure

get_time()

Retrieve the current time

get_vlim([meas])

Retrieve colormap value limits as (vmin, vmax) tuple

get_xlim()

get_ylim()

image([name, format, close])

Create FMTXT Image from the figure

link_time_axis(other)

Link the time axis of this figure with another figure

play_movie([time_dilation])

Cycle through the time axis

plot_colorbar([label, label_position, ...])

Plot a colorbar corresponding to the displayed data

save(*args, **kwargs)

Short-cut for Matplotlib's savefig()

save_movie([filename, time_dilation])

Save the figure with moving time axis as movie

set_cmap(cmap[, meas])

Change the colormap in the array plots

set_name(name)

Set the figure window title

set_time(time)

Set the time point to display

set_vlim([v, vmax, meas])

Change the colormap limits

set_xlabel(label[, ax])

Set the label for the x-axis

set_xlim([left, right])

Set the x-axis limits for all axes

set_xtick_rotation(rotation)

Rotate every x-axis tick-label by an angle (counterclockwise, in degrees)

set_ylabel(label[, ax])

Set the label for the y-axis

set_ylim([bottom, top])

Set the y-axis limits