4. Topo

_images/topo_ico.png

4.1. Description

Topo is a GUI based module for topographic representations.

_images/ex_topoplot_plotting_properties1.png

4.1.1. Help

If you need help with the Topo module, ask your questions in the dedicated gitter Topo chat

4.1.2. Main features

  • Display topographic map
    • Find coordinates according to channel names
    • Add connectivity edges
    • Support multiple coordinate systems
    • Highly controllable colorbar
  • Grid representation
    • Display topoplot into a highly controllable grid.
    • Add either one colorbar per topoplot or one shared colorbar across topoplot

4.1.3. Import and use Topo

The Topo module can be imported as follow :

from visbrain import Topo

4.1.4. Examples and datasets

Visit this page for a set of examples.

4.2. API

4.2.1. Topo class

class visbrain.Topo(verbose=None)[source][source]

Display topographic representation.

Methods

show() Display the graphical user interface.
add_topoplot(name, data[, xyz, channels, …]) Add a subplot embedded in a subplot.
add_shared_colorbar(name[, cmap, clim, …]) Add a shared colorbar across subplots.
add_shared_colorbar(name, cmap='viridis', clim=(0, 1), vmin=None, vmax=None, under='gray', over='red', cblabel='', cbtxtsz=5.0, cbtxtsh=2.3, txtcolor='black', txtsz=3.0, txtsh=1.2, width=0.17, border=True, bw=2.0, limtxt=True, bgcolor='white', ndigits=2, row=0, col=0, row_span=1, col_span=1, rect=(-1.2, -1.2, 2.4, 2.4))[source][source]

Add a shared colorbar across subplots.

Parameters:

cmap : string | None

Matplotlib colormap (like ‘viridis’, ‘inferno’…).

clim : tuple/list | None

Colorbar limit. Every values under / over clim will clip.

vmin : float | None

Every values under vmin will have the color defined using the under parameter.

vmax : float | None

Every values over vmin will have the color defined using the over parameter.

under : tuple/string | None

Matplotlib color under vmin.

over : tuple/string | None

Matplotlib color over vmax.

cblabel : string | ‘’

Colorbar label.

cbtxtsz : float | 5..

Text size of the colorbar label.

cbtxtsh : float | 2.3

Shift for the colorbar label.

txtcolor : string | ‘white’

Text color.

txtsz : float | 3.

Text size for clim/vmin/vmax text.

txtsh : float | 1.2

Shift for clim/vmin/vmax text.

border : bool | True

Display colorbar borders.

bw : float | 2.

Border width.

limtxt : bool | True

Display vmin/vmax text.

bgcolor : tuple/string | (0., 0., 0.)

Background color of the colorbar canvas.

ndigits : int | 2

Number of digits for the text.

row : int | 0

The row in which to add the widget (0 is the topmost row)

col : int | 0

The column in which to add the widget (0 is the leftmost column)

row_span : int | 1

The number of rows to be occupied by the topoplot.

col_span : int | 1

The number of columns to be occupied by the topoplot.

rect : tuple | (-1.2, -1.2, 2.4, 2.4)

The 2-D area on the screen to display. The rect input describe (x_start, y_start, x_width, y_height). This variable can be used to translate or scale.

add_topoplot(name, data, xyz=None, channels=None, c_connect=None, c_select=None, c_cmap='inferno', c_linewidth=3.0, system='cartesian', unit='degree', title=None, title_color='black', title_size=5.0, line_color='black', line_width=2.0, chan_size=2.0, chan_offset=(0.0, 0.0, 0.0), chan_mark_color='white', chan_mark_symbol='disc', chan_txt_color='black', bgcolor='white', cbar=True, cblabel=None, cb_txt_size=4.0, levels=None, level_colors='white', cmap='viridis', clim=None, vmin=None, under='gray', vmax=None, over='red', row=0, col=0, row_span=1, col_span=1, margin=0.05)[source][source]

Add a subplot embedded in a subplot.

For now, there’s two for using coordinates to define the subplot :

  • Using the xyz input (must either be in cartesian or spherical coordinate system)
  • Using the channel input. The Topo class contains a list of existing channel names and will try to identify those in the channels variable.
Parameters:

name : string

Name of the topographic plot.

data : array_like

Array of data of shape (n_channels,).

xyz : array_like | None

Array of source’s coordinates.

channels : list | None

List of channel names.

c_connect : array_like | None

Array of connections between sources. Must be a (n_channels, n_channels) upper triangular array of connecivity strength.

c_select : array_like | None

Array of boolean values to select which edges to display or to hide.

c_cmap : string | ‘inferno’

Colormap name to use for the edges color.

c_linewidth : float | 3.

Connectivity edges line width.

system : {‘cartesian’, ‘spherical’}

Coordinate system.

unit : {‘degree’, ‘rad’}

If system is ‘spherical’, specify if angles are in degrees or radians.

title : string | None

Title of the topoplot.

title_color : array_like/string | ‘black’

Color for the title.

title_size : float | 20.

Size of the title.

line_color : array_like/string | ‘black’

Color of lines for the head, nose and eras.

line_width : float | 4.

Line width for the head, nose and eras.

chan_size : float | 12.

Size of channel names text.

chan_mark_color : array_like/string | ‘white’

Color of channel markers.

chan_mark_symbol : string | ‘disc’

Symbol to use for markers. Use disc, arrow, ring, clobber, square, diamond, vbar, hbar, cross, tailed_arrow, x, triangle_up, triangle_down, and star.

chan_txt_color : array_like/string | ‘black’

Color of channel names.

bgcolor : array_like/string | ‘white’

Background color.

cbar : bool | True

Attach a colorbar to the topoplot.

cblabel : string | None

Colorbar label.

cb_txt_size : float | 16.

Text size for the colorbar limits and label.

levels : array_like/int | None

The levels at which the isocurve is constructed.

level_colors : string/array_like | ‘white’

The color to use when drawing the line. If a list is given, it must be of shape (Nlev), if an array is given, it must be of shape (Nlev, …). and provide one color per level (rgba, colorname). By default, all levels are whites.

cmap : string | None

Matplotlib colormap (like ‘viridis’, ‘inferno’…).

clim : tuple/list | None

Colorbar limit. Every values under / over clim will clip.

vmin : float | None

Every values under vmin will have the color defined using the under parameter.

vmax : float | None

Every values over vmin will have the color defined using the over parameter.

under : tuple/string | None

Matplotlib color under vmin.

over : tuple/string | None

Matplotlib color over vmax.

row : int | 0

The row in which to add the widget (0 is the topmost row)

col : int | 0

The column in which to add the widget (0 is the leftmost column)

row_span : int | 1

The number of rows to be occupied by the topoplot.

col_span : int | 1

The number of columns to be occupied by the topoplot.

margin : float | .05

Margin percentage between the topoplot and the edge of the subplot.

show()[source]

Display the graphical user interface.