Butterfly Plot

Butterfly plot is a plot type for visualisation of Event-related potentials. It can fully represent time and channels dimensions using lines. With addition of topoplot inset it can also represent location of channels. It called "butterfly" because the envelope of channels reminds butterfly wings🦋.

The configurations of ERP plots and Butterfly plots are somehow similar.

Setup

Package loading

The following modules are necessary for run this tutorial:

using UnfoldMakie
using Unfold
using CairoMakie
using DataFrames
using Colors

Note that DataFramesMeta is also used here in order to be able to use @subset for testing (filtering).

Data

We filter the data to make it more clearly represented:

include("../../../example_data.jl")
df, pos = example_data("TopoPlots.jl")
first(df, 3)

3×7 DataFrame

Row	estimate	time	channel	coefname	topo_positions	se	pval
	Float64	Float64	Int64	String	Any	Float64	Float64
1	0.020321	-0.3	1	A	(0.493714, 0.544031)	0.122875	0.266091
2	0.017548	-0.298	1	A	(0.493714, 0.544031)	0.124345	0.29664
3	0.0150747	-0.296	1	A	(0.493714, 0.544031)	0.124828	0.323592

Plot Butterfly Plots

The default butterfly plot:

plot_butterfly(df)

The butterfly plot with corresponding topoplot. You need to provide the channel positions.

plot_butterfly(df; positions = pos)

You want to change size of topomarkers and size of topoplot:

plot_butterfly(df; positions = pos, topomarkersize = 10, topoheigth = 0.4, topowidth = 0.4)

You want to add vline and hline:

f = Figure()
plot_butterfly!(f, df; positions = pos)
hlines!(0, color = :gray, linewidth = 1)
vlines!(0, color = :gray, linewidth = 1)
f

You want to remove all decorations:

plot_butterfly(
    df;
    positions = pos,
    layout = (; hidedecorations = (:label => true, :ticks => true, :ticklabels => true)),
)

Changing the colors of channels

Please check this page.

You want to highlight a specific channel or channels. Specify channels first:

df.highlight1 = in.(df.channel, Ref([12])) # for single channel
df.highlight2 = in.(df.channel, Ref([10, 12])) # for multiple channels

Second, you can highlight it or them by color.

gray = Colors.RGB(128 / 255, 128 / 255, 128 / 255)
f = Figure(size = (1000, 400))
plot_butterfly!(
    f[1, 1],
    df;
    positions = pos,
    mapping = (; color = :highlight1),
    visual = (; color = 1:2, colormap = [gray, :red]),
)
plot_butterfly!(
    f[1, 2],
    df;
    positions = pos,
    mapping = (; color = :highlight2),
    visual = (; color = 1:2, colormap = [gray, :red]),
)
f

Or by faceting:

df.highlight2 = replace(df.highlight2, true => "channels 10, 12", false => "all channels")

plot_butterfly(
    df;
    positions = pos,
    mapping = (; color = :highlight2, col = :highlight2),
    visual = (; color = 1:2, colormap = [gray, :red]),
)

Column Mappings for Butterfly Plot

Since butterfly plots use a DataFrame as input, the library needs to know the names of the columns used for plotting. You can set these mapping values by calling plot_butterfly(...; mapping=(; :x=:time)). Just specify a NamedTuple. Note the ; right after the opening parentheses.

Configurations of Butterfly Plot

UnfoldMakie.plot_butterfly — Function

plot_butterfly(plot_data::DataFrame; positions = nothing)

Plot a Butterfly plot.

Keyword argumets (kwargs)

positions::Array = []
Adds a topoplot as an inset legend to the provided channel positions. Must be the same length as plot_data. To change the colors of the channel lines use the topoposition_to_color function.
topolegend::Bool = true
Show an inlay topoplot with corresponding electrodes. Requires positions.
topomarkersize::Real = 10
Change the size of the electrode markers in topoplot.
topowidth::Real = 0.25
Change the width of inlay topoplot.
topoheigth::Real = 0.25
Change the height of inlay topoplot.
topopositions_to_color::x -> pos_to_color_RomaO(x)
Change the line colors.

Return Value: Figure displaying Butterfly plot.

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 [s]", ylabel = "Voltage [µV]", yticklabelsize = 14) - use kwargs... of Makie.Axis

layout = (show_legend = false, legend_position = :right, xlabelFromMapping = :x, ylabelFromMapping = :y, use_colorbar = false, hidespines = (:r, :t), hidedecorations = Dict{Symbol, Bool}(:label => 0, :ticks => 0, :ticklabels => 0))

mapping = (x = (:time,), y = (:estimate, :yhat, :y), color = (:channel, :channels, :trial, :trials), positions = (:pos, :positions, :position, :topo_positions, :x, nothing), labels = (:labels, :label, :topoLabels, :sensor, nothing), group = (:channel,))

visual = (colormap = nothing, color = nothing) - use kwargs... of Makie.lines

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

colorbar = (vertical = true, tellwidth = true, tellheight = false) - use kwargs... of AlgebraOfGraphics.colobar!