GitHub

ERP image

ERP image is a plot type for visualizing EEG activity for all trials. It can fully represent time and trial dimensions using a heatmap. Y-axis represents all trials, x-axis represents time, while color represents voltage. The ERP image can also be sorted by specific experimental variables, which helps to reveal important correlations.

Setup

Package loading

using Unfold
using UnfoldMakie
using CairoMakie
using UnfoldSim
using Statistics

Data input

include("../../../example_data.jl")
data, evts = UnfoldSim.predef_eeg(; noiselevel = 10, return_epoched = true)
plot_erpimage(data)
Example block output

Plot ERP image

The following code will result in the default configuration.

Sorted ERP image

Generate the data and specify the necessary sorting parameter.

  • sortvalues::Vector{Int64} = false Parameter over which plot will be sorted. Using sortperm() of Base Julia. sortperm() computes a permutation of the array's indices that puts the array in sorted order.
dat_e, evts, times = example_data("sort_data")
dat_norm = dat_e[:, :] .- mean(dat_e, dims = 2) # normalisation
plot_erpimage(times, dat_norm; sortvalues = evts.Δlatency)
Example block output

To see the effect of sorting and normalization, also check this figure.

f = Figure()
plot_erpimage!(f[1, 1], times, dat_e; axis = (; ylabel = "test"))
plot_erpimage!(
    f[2, 1],
    times,
    dat_e;
    sortvalues = evts.Δlatency,
    axis = (; ylabel = "test"),
)
plot_erpimage!(f[1, 2], times, dat_norm;)
plot_erpimage!(f[2, 2], times, dat_norm; sortvalues = evts.Δlatency)
f
Example block output

Additional features

Since ERP images use a Matrix as an input, the library does not need any informations about the mapping.

  • erpblur::Number = 10 Number indicating how much blur is applied to the image. Gaussian blur of the ImageFiltering module is used.
  • meanplot::bool = false Indicating whether the plot should add a line plot below the ERP image, showing the mean of the data.

Example of mean plot

plot_erpimage(
    data;
    meanplot = true,
    colorbar = (label = "Voltage [µV]",),
    visual = (colormap = :viridis, colorrange = (-40, 40)),
)
Example block output

Example of mean plot and plot of sorted values

plot_erpimage(
    times,
    dat_e;
    sortvalues = evts.Δlatency,
    meanplot = true,
    show_sortval = true,
)
Example block output

Configurations for ERP image

UnfoldMakie.plot_erpimage — Function
plot_erpimage!(f::Union{GridPosition, GridLayout, Figure}, data::AbstractMatrix{Float64}; kwargs...)
plot_erpimage!(f::Union{GridPosition, GridLayout, Figure}, data::Observable{<:AbstractMatrix}; kwargs...)
plot_erpimage!(f::Union{GridPosition, GridLayout, Figure}, times::Observable{<:AbstractVector}, data::Observable{<:AbstractMatrix{<:Real}}; kwargs...)

plot_erpimage(times::AbstractVector, data::Union{<:Observable{Matrix{<:Real}}, Matrix{<:Real}}; kwargs...)
plot_erpimage(data::Matrix{Float64}; kwargs...)

Plot an ERP image.

Arguments:

  • f::Union{GridPosition, GridLayout, Figure}
    Figure, GridLayout, or GridPosition to draw the plot.
  • data::Union{DataFrame, Vector{Float32}}
    Data for the plot visualization.

Keyword arguments (kwargs)

  • erpblur::Number = 10
    Number indicating how much blur is applied to the image.
    Gaussian blur of the ImageFiltering module is used.
    Non-Positive values deactivate the blur.
  • sortvalues::Vector{Int64} = false
    Parameter over which plot will be sorted. Using sortperm() of Base Julia.
    sortperm() computes a permutation of the array's indices that puts the array in sorted order.
  • sortindex::Vector{Int64} = nothing
    Sorting over index values.
  • meanplot::bool = false
    Add a line plot below the ERP image, showing the mean of the data.
  • show_sortval::bool = false
    Add a plot on the right from ERP image, showing the distribution of the sorting data.
  • sortval_xlabel::String = "Sorting variable"
    If show_sortval = true controls xlabel.
  • axis.ylabel::String = "Trials"
    If sortvalues = true the default text will change to "Sorted trials", but it could be changed to any values specified manually.
  • meanplot_axis::NamedTuple = (;)
    Here you can flexibly change configurations of meanplot.
    To see all options just type ?Axis in REPL.
    Defaults: (height = 100, xlabel = "Time", xlabelpadding = 0, xautolimitmargin = (0, 0))
  • sortplot_axis::NamedTuple = (;)
    Here you can flexibly change configurations of meanplot.
    To see all options just type ?Axis in REPL.
    Defaults: (ylabelvisible = true, yticklabelsvisible = false)

Shared plot configuration options

The shared plot options can be used as follows: type = (; key = value, ...)).
For example, plot_x(...; colorbar = (; vertical = true, label = "Test")).
Multiple defaults will be cycled until match.

Placing ; is important!

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

axis = (xlabel = "Time", ylabel = "Trials") - use kwargs... of Makie.Axis

layout = (show_legend = true, use_colorbar = true) - check this page

mapping = (x = (:time,), y = (:estimate, :yhat, :y)) - use any mapping from AlgebraOfGraphics

visual = (colormap = Makie.Reverse{String}("RdBu"),) - use kwargs... of Makie.heatmap

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

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

Return Value: Figure displaying the ERP image.

source

This page was generated using Literate.jl.