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 xlim_topo and 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, Figure}
    Figure, GridLayout, or GridPosition to draw the plot.
  • data::Union{DataFrame, Vector{Float32}}
    DataFrame with data. 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.

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.

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) - 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.