Topographical Maps

Initialize NeuroAnalyzer
using NeuroAnalyzer
using CairoMakie
NeuroAnalyzer.progress_bar = false

# Quarto sets a default figure size (672 × 480 px), which overrides the sizes of
# NeuroAnalyzer figures (e.g. the small and medium topographical maps): remove it
delete!(CairoMakie.Makie.CURRENT_DEFAULT_THEME, :resolution)

# preprocessed recording, EEG channels only
eeg = load_neuro("files/eeg/eeg.hdf")
eeg = keep_channel(eeg; ch = "eeg")
e10 = epoch(eeg; ep_len = 10)

A topographical map (topomap) shows the spatial distribution of a value (amplitude, power, a statistic, …) over the scalp: the values at the electrode locations are interpolated over the whole head. The object must contain channel locations (see the channel locations tutorial).

Plotting Topomaps

plot_topo() plots either the signal at a time point, or any values given for each channel.

The signal at a time point (tpos, in seconds); for a range of time points the signal is averaged (amethod = :mean or :median):

plot_topo(eeg; ch = "eeg", tpos = 2.5)

Values of each channel are given using data, e.g. the power of the theta band (4–8 Hz):

theta = band_power(eeg;
                   ch = "eeg",
                   flim = band_frq(eeg; band = :theta))
plot_topo(eeg;
          ch = "eeg",
          data = theta[:, 1],
          title = "Theta power")

By default, the values are normalized (nmethod = :minmax), so the colorbar is in arbitrary units. To plot the original values, use nmethod = :none:

plot_topo(eeg;
          ch = "eeg",
          data = theta[:, 1],
          nmethod = :none,
          cb_title = "[μV²/Hz]",
          title = "Theta power")

The theta power is highest over the posterior regions, where the slow posterior dominant rhythm of this recording is located.

Plot Options

  • ps: plot size: :l (large, default), :m (medium) or :s (small)
  • contours: number of contour lines
  • electrodes, ch_labels: show electrodes and their labels
  • sch: highlight selected (e.g. significant) channels
  • head: draw the head outline
  • mono: use a monochrome palette

A medium map with contour lines and highlighted channels:

plot_topo(eeg;
          ch = "eeg",
          data = theta[:, 1],
          ps = :m,
          contours = 8,
          sch = ["O1", "O2"])

A small map without labels:

plot_topo(eeg;
          ch = "eeg",
          data = theta[:, 1],
          ps = :s)

Thresholding

The map can be thresholded using the same rules as other plots (:eq, :neq, :geq, :leq, :g, :l, :in, :bin); the threshold is in the units of the plotted values (normalized values unless nmethod = :none). With threshold_method = :reg (default) only the region of the map meeting the threshold is shown:

plot_topo(eeg;
          ch = "eeg",
          data = theta[:, 1],
          nmethod = :none,
          threshold = 6,
          threshold_type = :geq,
          threshold_method = :reg)

With threshold_method = :loc the whole map is shown and the electrodes meeting the threshold are marked:

plot_topo(eeg;
          ch = "eeg",
          data = theta[:, 1],
          nmethod = :none,
          threshold = 6,
          threshold_type = :geq,
          threshold_method = :loc)

Interpolation Methods

The interpolation method is selected using imethod:

imethod Method Notes
:tp thin-plate spline (default) works for all layouts and data types, fast; similar to the default of EEGLAB
:sph spherical spline (Perrin et al., 1989) recommended for EEG figures for publication; fitted at the 3D electrode positions
:sib, :sib1, :lap, :far, :hiy, :tri natural neighbour methods (NaturalNeighbours.jl) parameter-free; :tri is piecewise linear (similar to MNE)
:mq, :imq, :ga multiquadric, inverse multiquadric, Gaussian the shape parameter is fixed, so the result depends on the scale of the locations
:sh Shepard (inverse distance weighting) produces “bullseye” artifacts around the electrodes; not recommended
:nn nearest neighbour Voronoi patches; useful only for checking the data

The spherical spline takes longer to calculate (about 2 seconds for a large map), the thin-plate spline is about 20 times faster.

Spherical spline:

plot_topo(eeg;
          ch = "eeg",
          data = theta[:, 1],
          imethod = :sph,
          title = "Spherical spline")

Sibson (natural neighbour):

plot_topo(eeg;
          ch = "eeg",
          data = theta[:, 1],
          imethod = :sib,
          title = "Sibson")

Shepard; note the local maxima and minima around the electrodes:

plot_topo(eeg;
          ch = "eeg",
          data = theta[:, 1],
          imethod = :sh,
          title = "Shepard")

Tip: to interpolate the signal of a bad channel, use sphinterpolate_channel() (see the bad channels tutorial).

Plotting Weights

plot_locs() shows the channel locations; with weights, a value is shown at each location (positive values in red, negative in blue):

plot_locs(eeg;
          ch = "eeg",
          weights = theta[:, 1],
          gui = false)

Plotting Connections

With connections (a channels × channels matrix), the connections passing the threshold are drawn between the electrodes; the line widths and transparency are scaled by the connection strength. The correlation matrix of the first 10-second epoch, correlations > 0.8:

cm = corm(e10; ch = "eeg")[:, :, 1]
plot_locs(eeg;
          ch = "eeg",
          connections = cm,
          threshold = 0.8,
          threshold_type = :g,
          gui = false)

Connections can be plotted in the top (XY, default), front (XZ) and side (YZ) planes (plane). For legibility, it is recommended to disable the channel labels.

Front view:

plot_locs(eeg;
          ch = "eeg",
          ch_labels = false,
          connections = cm,
          threshold = 0.8,
          threshold_type = :g,
          plane = :xz,
          gui = false)

Side view:

plot_locs(eeg;
          ch = "eeg",
          ch_labels = false,
          connections = cm,
          threshold = 0.8,
          threshold_type = :g,
          plane = :yz,
          gui = false)

Connectivity Circle

Connections can also be shown as a connectivity circle, with the channels placed around a circle:

plot_connectivity_circle(cm;
                         clabels = labels(eeg),
                         threshold = 0.8,
                         threshold_type = :g,
                         title = "Correlation > 0.8")

Negative values are drawn in blue; correlations < −0.1:

plot_connectivity_circle(cm;
                         clabels = labels(eeg),
                         threshold = -0.1,
                         threshold_type = :l,
                         title = "Correlation < -0.1")
  • Only the upper triangle of the connectivity matrix is used, so the matrix should be symmetric. For directed (asymmetric) connectivity, draw two plots: one for the matrix and one for its transpose (m').
  • Positive values are drawn in red, negative values in blue.
  • The widths of the connections are scaled by their values.