3. Signal


3.1. Description

Signal is a data-mining module for 1-D, 2-D and 3-D datasets. It tries to offer a convenient way to inspect datasets, locate bad trials and reveal time-frequency properties. It is subdivided into to two distinct components :

  • The grid : each datasets is re-arranged into a clickable 2-D grid so that all of the time-series of a dataset are represented inside. This idea of a grid was originally present into the VisPy examples and has been adapted for brain signals.
  • The signal canvas : the second layout display one trial at a time. This trial can either be represented as a continuous line or markers. It’s also possible to compute the histogram, time-frequency map or PSD.

(left) continuous line, markers, histogram, time-frequency map, power spectrum density (PSD), (right) grid representation

3.1.1. Main features

  • Grid disposition
    • 2-D and 3-D datasets are disposed into a grid for an overview of an entire dataset
    • Zoom, translate and double click on a signal to enlarge it
  • Signal inspection
    • Plot one time-series at a time
    • Navigate across all of the time-series present in the dataset
    • Change the plotting form (continuous line, markers, histogram, time-frequency map, power spectrum density (PSD))
    • Load and export annotated trials
  • Tools
    • De-trending and de-meaning
    • Filtering (lowpass, highpass, bandpass, bandstop)
    • Extract the amplitude, phase or power in specific frequency bands
    • Take a screenshot (of the entire window, or the grid canvas only or of the signal canvas only)

3.1.2. Import and use Signal

The Signal module can be imported as follow :

from visbrain import Signal

3.1.3. Examples and datasets

To try out this module, check out the Signal example scripts.

3.2. API

3.2.1. Signal class

class visbrain.Signal(data, axis=-1, time=None, sf=1.0, enable_grid=True, form='line', color='black', line_lw=1.0, line_smooth=False, marker_symbol='disc', marker_size=10.0, hist_nbins=10, tf_norm=0, tf_baseline=None, tf_interp='gaussian', tf_cmap='viridis', tf_av_window=None, tf_av_overlap=0.0, tf_clim=None, psd_nperseg=256, psd_noverlap=128, display_grid=True, display_signal=True, annotations=None, annot_txtsz=18.0, annot_marksz=16.0, annot_color='#2ecc71', grid_lw=1.0, grid_smooth=False, grid_titles=None, grid_font_size=10.0, grid_color='random', grid_shape=None, grid_titles_color='black', verbose=None, **kwargs)[source][source]

Signal inspection module (data mining).

The Signal module can be used to relatively large datasets of time-series. Two layout are provided :

  • Grid layout : visualize all of the signals into a grid.
  • Signal layout : visualize only one signal.

data : array_like

Array of data of shape (N,),

axis : int | -1

Specify where is located the time axis in data. By default, the last axis is considered as the time axis (-1).

time : array_like | None

Time vector to use. If None, the time vector is inferred using the axis input.

sf : float | 1.

Sampling frequency.

enable_grid : bool | True

Enable or disable the grid. If False, the grid is not computed and not accessible from the GUI. The grid requires more memory RAM. It could be turn to False for very large datasets.

form : {‘line’, ‘marker’, ‘histogram’, ‘tf’, ‘psd’, ‘butterfly’}

Plotting type.

color : array_like/string/tuple | ‘black’

Color of the plot.

line_lw : float | 1.

Line width (form in [‘line’, ‘psd’, ‘butterfly’]).

line_smooth : bool | False

Specify if grid lines have to be smoothed. might be unstable on some platform.

marker_symbol : string | ‘o’

Marker symbol.

marker_size : float | 10.

Marker size.

hist_nbins : int | 10

Number of bins for the histogram.

tf_norm : int | 0

Time-frequency normalization. If tf_baseline is not defined, the mean and deviation are deduced using the entire trial. Use :

  • 0 : No normalization
  • 1 : Subtract the mean
  • 2 : Divide by the mean
  • 3 : Subtract then divide by the mean
  • 4 : Z-score

tf_baseline : tuple | None

Baseline to used for the normalization. Must be a tuple of two integers (starting, ending) time index.

tf_interp : string | ‘gaussian’

Time-frequency interpolation method.

tf_cmap : string | ‘viridis’

Time-frequency colormap.

tf_av_window : int | None

Length of the window to apply a time averaging.

tf_av_overlap : float | 0.

Overlap between successive time window. Default 0. means no overlap.

tf_clim : tuple | None

Colorbar limits to use for the tim-frequency map.

psd_nperseg : int | 256

Length of each segment (scipy.signal.welch).

psd_noverlap : int | 128

Number of points to overlap between segments (scipy.signal.welch).

parent : VisPy.parent | None

Parent of the mesh.

title : string | None

Title of the axis (signal layout).

xlabel : string | None

Label for the x-axis (signal layout).

ylabel : string | None

Label for the y-axis (signal layout).

title_font_size : float | 15.

Size of the title (signal layout).

axis_font_size : float | 12.

Size of x and y labels (signal layout).

axis_color : array_like/string/tuple | ‘black’

Label, title, axis and border color (signal layout).

tick_font_size : float | 8.

Size of ticks for the x and y-axis (signal layout).

grid_lw : float | 1.

Grid line width.

grid_titles : list | None

Titles do add to each plot in the grid. Sould be a list of length (n_rows * n_cols).

grid_font_size : float | 10.

Font size of grid titles.

grid_color : string | ‘random’

Grid plot color. Use ‘random’ to have one random color per plot or use a string (e.g. ‘gray’) for a uniform color.

grid_titles_color : array_like/string/tuple | ‘black’

Grid titles color.

bgcolor : array_like/tuple/string | ‘black’

Background color.

display_grid : bool | True

Display the grid layout.

display_signal : bool | True

Display the signal layout.

annotations : str | None

Path to an annotation file.

smooth_lines : bool | True

Specify if grid lines have to be smoothed. might be unstable on some platform.


show() Display the graphical user interface.
set_xlim(xstart, xend) Fix limits of the x-axis.
set_ylim(ystart, yend) Fix limits of the y-axis.
set_signal_index(index) Set the index of the signal.
set_signal_form([form]) Set plotting method.
screenshot([filename, canvas, autocrop, …]) Take a screenshot of the scene.
screenshot(filename='screenshot.png', canvas='signal', autocrop=False, region=None, print_size=None, unit='centimeter', dpi=300.0, factor=1.0, bgcolor=None, transparent=False)[source][source]

Take a screenshot of the scene.


filename : string | ‘screenshot.png’

Name and path of the screenshot file.

canvas : {‘signal’, ‘grid’}

Canvas to capture.

autocrop : bool | False

Auto-cropping argument to remove useless space.

region : tuple/list | None

The region to export (x_start, y_start, width, height).

print_size : tuple | None

The desired print size. This argument should be used in association with the dpi and unit inputs. print_size describe should be a tuple of two floats describing (width, height) of the exported image for a specific dpi level. The final image might not have the exact desired size but will try instead to find a compromize regarding to the proportion of width/height of the original image.

unit : {‘centimeter’, ‘millimeter’, ‘pixel’, ‘inch’}

Unit of the printed size.

dpi : float | 300.

Dots per inch for printing the image.

factor : float | None

If you don’t want to use the print_size input, factor simply multiply the resolution of your screen.

bgcolor : array_like/string | None

Background color of the canvas.

transparent : bool | False

Use transparent background.


Set plotting method.


form : {‘line’, ‘marker’, ‘histogram’, ‘tf’, ‘psd’, ‘butterfly’}

Plotting form.


Set the index of the signal.

set_xlim(xstart, xend)[source][source]

Fix limits of the x-axis.


xstart : float

Starting point of the x-axis.

xend : float

Ending point of the x-axis

set_ylim(ystart, yend)[source][source]

Fix limits of the y-axis.


ystart : float

Starting point of the y-axis.

yend : float

Ending point of the y-axis


Display the graphical user interface.

3.3. Shortcuts

  • go = Grid canvas only
  • so = Signal canvas only
Keys Description
Double click (go) Enlarge signal under the mouse cursor
n (so) Go to the next signal
b (so) Go to the previous signal
Double click (so) Insert annotation
g Display / hide grid
s Display / hide signal
<delete> (go and so) Reset the camera
CTRL + t Display shortcuts
CTRL + d Display / hide setting panel
CTRL + n Take a screenshot
CTRL + q Close Sleep graphical interface