Topoplot

Topoplot (aka topography plot) is a plot type for visualisation of EEG activity in a specific time stemp or time interval. It can fully represent channel and channel location dimensions using contour lines.

The topoplot is a 2D projection and interpolation of the 3D distributed sensor activity. The name stems from physical geography, but instead of height, the contour lines represent voltage levels.

Setup

Package loading

using Unfold
using UnfoldMakie
using DataFrames
using CairoMakie
using TopoPlots
using DataFrames

Data loading

data, positions = TopoPlots.example_data()

(Float32[0.020321019 0.017548025 … -0.01600543 -0.01283471; 0.0031529826 -0.0015369694 … 0.0435155 0.042441286; … ; 0.019118542 0.018276842 … -0.0016676243 0.000102287915; 0.019761175 0.015906857 … 0.11238504 0.10997909;;; 0.12287474 0.12434518 … 0.26227304 0.2553188; 0.07275557 0.07255436 … 0.30493587 0.30125305; … ; 0.06405158 0.06326836 … 0.2052622 0.2037698; 0.07259608 0.07544017 … 0.2627769 0.25834358;;; 0.26609147 0.2966399 … 0.40829125 0.4242154; 0.43455398 0.46788654 … 0.29459625 0.29695213; … ; 0.13350745 0.14102341 … 0.48767123 0.4992381; 0.15481107 0.21390781 … 0.059936017 0.06072311], Point{2, Float32}[[0.49371386, 0.5440313], [0.5630452, 0.50400287], [0.5630452, 0.4239459], [0.49371386, 0.38391745], [0.4243825, 0.4239459], [0.4243825, 0.50400287], [0.5378472, 0.6178857], [0.61455333, 0.56901854], [0.6522695, 0.4862579], [0.6388263, 0.39630732]  …  [0.93907887, 0.6439135], [0.9450873, 0.29968786], [0.8333667, 0.12432156], [0.61803544, 1.9428903f-16], [0.3693923, 2.7755576f-17], [0.15406103, 0.12432156], [0.029739477, 0.3396528], [0.04834886, 0.6439135], [0.26820713, 0.88809085], [0.7192206, 0.88809085]])

The size of data is 64×400×3. This means:

64 channels;
400 timepoints in range from -0.3 to 0.5 mseconds;
Estimates of 3 averaging functions. Instead of displaying the EEG data for all subjects, here we aggregate the data using (1) mean, (2) standard deviation and (3) p-value within t-tests.

While position consist of 64 x and y coordinates of each channels on a scalp.

Plot Topoplots

Here we select a time point in 340 msec and the mean estimate.

plot_topoplot(data[:, 340, 1]; positions = positions)

df = DataFrame(:estimate => data[:, 340, 1])
plot_topoplot(df; positions = positions)

Setting sensor positions

The plot_topoplot() needs the sensor positions to be specified. There are several ways to do this:

Specify positions directly: plot_topoplot(...; positions=[...])
Specify the sensor labels: plot_topoplot(...; labels=[...])

To get the positions from the labels we use a database.

Column Mappings for Topoplots

When using topoplots with a DataFrame as input, the library needs to know the names of the columns used for plotting. This is specified using the mapping=(;) kwargs.

While there are several default values that will be checked in order if they exist in the DataFrame, a custom name may need to be chosen:

Note that only one of positions or labels needs to be set to draw a topoplot. If both are set, positions takes precedence, labels can be used to label electrodes in TopoPlots.jl.

The default columns of mapping could be seen usign this code:

cfgDefault = UnfoldMakie.PlotConfig()
cfgDefault.mapping.y

(:estimate, :yhat, :y)

Labelling

label_text draws labels next to their positions.

Example: plot_topoplot(...; visual=(; label_text = true))

label_scatter (boolean) draws the markers at the given positions.

Example: plot_topoplot(...; visual=(; label_scatter = true))

f = Figure(size = (500, 500))
labs4 = ["O1", "F2", "F3", "P4"]
plot_topoplot!(
    f[1, 1],
    data[1:4, 340, 1];
    visual = (; label_scatter = false),
    labels = labs4,
    axis = (; title = "no channel scatter"),
)

plot_topoplot!(
    f[1, 2],
    data[1:4, 340, 1];
    visual = (; label_text = true, label_scatter = (markersize = 15, strokewidth = 2)),
    labels = labs4,
    axis = (; title = "channel scatter with text"),
    mapping = (; labels = labs4),
)
f

Configurations of Topoplot

UnfoldMakie.plot_topoplot — Function

plot_topoplot!(f::Union{GridPosition, GridLayout, Figure}, data, ; positions = nothing, labels = nothing, kwargs...)
plot_topoplot(data; positions = nothing, labels = nothing, kwargs...)

Plot a topoplot.

Arguments

f::Union{GridPosition, GridLayout, Figure}
Figure, GridLayout, or GridPosition to draw the plot.
data::Union{DataFrame, Vector{Float32}}
Data for the plot visualization.
positions::Vector{Point{2, Float32}} = nothing
Positions used if data is not a DataFrame. Positions are generated from labels if positions = nothing.
labels::Vector{String} = nothing
Labels used if data is not a DataFrame.

Shared plot configuration options

The shared plot options can be used as follows: type = (; key = value, ...)).
For example, plot_x(...; layout = (; show_legend = true, legend_position = :right)).
Multiple defaults will be cycled until match.

Placing ; is important!

figure = NamedTuple() - use kwargs... of Makie.Figure

axis = (xlabel = "", aspect = Makie.DataAspect()) - use kwargs... of Makie.Axis

layout = (show_legend = true, legend_position = :right, xlabelFromMapping = nothing, ylabelFromMapping = nothing, use_colorbar = true, hidespines = (), hidedecorations = Dict{Symbol, Bool}(:label => 0))

mapping = (x = nothing, y = (:estimate, :yhat, :y), positions = (:pos, :positions, :position, nothing), labels = (:labels, :label, :sensor, nothing))

visual = (colormap = Makie.Reverse{Symbol}(:RdBu), contours = (color = :white, linewidth = 2), label_scatter = true, label_text = true, bounding_geometry = GeometryBasics.Circle) - use kwargs... of Topoplot.eeg_topoplot

legend = (orientation = :vertical, tellwidth = true, tellheight = false) - use kwargs... of Makie.Legend

colorbar = (vertical = true, tellwidth = true, tellheight = false, flipaxis = true, labelrotation = -1.5707963267948966, label = "Voltage [µV]") - use kwargs... of Makie.Colorbar

Return Value: Figure displaying the Topoplot.

source

This page was generated using Literate.jl.