GitHub

Topoplot Series

Topoplot Series is a plot type for visualizing EEG activity in a given time frame or time interval. It can fully represent channel and channel location dimensions using contour lines. It can also partially represent the time dimension. Basically, it is a series of Topoplots.

Setup

Package loading

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

Data input

data, positions = TopoPlots.example_data()
df = UnfoldMakie.eeg_matrix_to_dataframe(data[:, :, 1], string.(1:length(positions)));

Plotting

Δbin = 80
plot_topoplotseries(df, Δbin; positions = positions)
Example block output

Additional features

Disabling colorbar

plot_topoplotseries(df, Δbin; positions = positions, layout = (; use_colorbar = false))
Example block output

Aggregating functions

In this example combinefun is specified by mean, median and std.

f = Figure(size = (500, 500))
plot_topoplotseries!(
    f[1, 1],
    df,
    Δbin;
    positions = positions,
    combinefun = mean,
    axis = (; title = "combinefun = mean"),
)
plot_topoplotseries!(
    f[2, 1],
    df,
    Δbin;
    positions = positions,
    combinefun = median,
    axis = (; title = "combinefun = median"),
)
plot_topoplotseries!(
    f[3, 1],
    df,
    Δbin;
    positions = positions,
    combinefun = std,
    axis = (; title = "combinefun = std"),
)
f
Example block output

Faceting

If you need to plot many topoplots, you should display them in multiple rows.

Here you can specify:

  • Grouping condition using mapping.row.
  • Label the y-axis with axis.ylabel.
  • Hide electrode markers with visual.label_scatter.
  • Change the color map with visual.colormap. The default is Reverse(:RdBu).
  • Adjust the limits of the topoplot boxes with axis.xlim_topo and axis.ylim_topo. By default both are (-0.25, 1.25).
  • Adjust the size of the figure with Figure(size = (x, y)).
  • Adjust the padding between topoplot labels and axis labels using xlabelpadding and ylabelpadding.
df1 = UnfoldMakie.eeg_matrix_to_dataframe(data[:, :, 1], string.(1:length(positions)))
df1.condition = repeat(["A", "B", "C", "D", "E"], size(df, 1) ÷ 5)

f = Figure(size = (600, 500))

plot_topoplotseries!(
    f[1:2, 1:2],
    df1,
    Δbin;
    col_labels = true,
    mapping = (; row = :condition),
    axis = (; ylabel = "Conditions"),
    positions = positions,
    visual = (label_scatter = false,),
    layout = (; use_colorbar = true),
)
f
Example block output

Configurations of Topoplot series

UnfoldMakie.plot_topoplotseries — Function
plot_topoplotseries(f::Union{GridPosition, GridLayout, Figure}, data::DataFrame, Δbin::Real; kwargs...)
plot_topoplotseries!(data::DataFrame, Δbin::Real; kwargs...)

Multiple miniature topoplots in regular distances.

Arguments

  • f::Union{GridPosition, GridLayout, GridLayoutBase.GridSubposition, Figure}
    Figure, GridLayout, GridPosition, or GridLayoutBase.GridSubposition to draw the plot.
  • data::Union{<:Observable{<:DataFrame},DataFrame}
    DataFrame with data or Observable DataFrame. Requires a time column.
  • Δbin::Real
    A number for how large one time bin should be.
    Δbin is in units of the data.time column.
    Should be 0 if mapping.col or mapping.row are categorical.

Keyword arguments (kwargs)

  • combinefun::Function = mean
    Specify how the samples within Δbin are summarised.
    Example functions: mean, median, std.
  • rasterize_heatmaps::Bool = true
    Force rasterization of the plot heatmap when saving in svg format.
    Except for the interpolated heatmap, all lines/points are vectors.
    This is typically what you want, otherwise you get ~128x128 vectors per topoplot, which makes everything super slow.
  • col_labels::Bool, row_labels::Bool = true
    Shows column and row labels.
  • labels::Vector{String} = nothing
    Show labels for each electrode.
  • positions::Vector{Point{2, Float32}} = nothing
    Specify channel positions. Requires the list of x and y positions for all unique electrode.
  • interactive_scatter = nothing
    Enable interactive mode. \ If you create obs_tuple = Observable((0, 0, 0)) and pass it into interactive_scatter you can change observable indecies by clicking topopplot markers.
    (0, 0, 0) corresponds to the indecies of row of topoplot layout, column of topoplot layout and channell.

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 = "Time windows [s]", aspect = Makie.DataAspect(), title = "", titlesize = 16, titlefont = :bold, ylabel = "", xlim_topo = (-0.25, 1.25), ylim_topo = (-0.25, 1.25), ylabelpadding = 25, xlabelpadding = 25, xpanlock = true, ypanlock = true, xzoomlock = true, yzoomlock = true, xrectzoom = false, yrectzoom = false) - 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), col = (:time,), row = (nothing,))

visual = (colormap = Makie.Reverse{Symbol}(:RdBu), contours = (color = :white, linewidth = 2), label_scatter = false, label_text = false, bounding_geometry = GeometryBasics.Circle, enlarge = 1) - 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]", colorrange = nothing) - use kwargs... of Makie.Colorbar

Return Value: Figure displaying the Topoplot series.

source

This page was generated using Literate.jl.