topo_plot: Plot topographic map of EEG signal

In diegr: Dynamic and Interactive EEG Graphics

Plot topographic map of EEG signal

Description

Plot a topographic circle or polygon map of the EEG signal amplitude using topographic colour scale. The thin-plate spline interpolation model \text{IM:}\; \mathbb{R}^2 \rightarrow \mathbb{R} is used for signal interpolation between the sensor locations. The output in the form of a ggplot object allows to easily edit the result image properties.

Usage

topo_plot(
  data,
  amplitude,
  mesh,
  coords = NULL,
  template = NULL,
  col_range = NULL,
  col_scale = NULL,
  contour = FALSE,
  show_legend = TRUE,
  label_sensors = FALSE
)

Arguments

data	A data frame, tibble or a database table with input data to plot with at least two columns: sensor with sensor labels and the column with the EEG amplitude specified in the argument amplitude.
amplitude	A character string naming the column with EEG amplitude values.
mesh	A "mesh" object (or a named list with the same structure) containing at least D2 element with x and y coordinates of a point mesh used for computing IM model. If not defined, the point mesh with default settings from point_mesh function is used.
coords	Sensor coordinates as a tibble or data frame with named x, y and sensor columns. The sensor labels must match the labels in sensor column in data. If not defined, the HCGSN256 template is used.
template	The kind of sensor template montage used. Currently the only available option is "HCGSN256" denoting the 256-channel HydroCel Geodesic Sensor Net v.1.0, which is also a default setting.
col_range	A vector with minimum and maximum value of the amplitude used in the colour palette for plotting. If not defined, the range of interpolated signal is used.
col_scale	Optionally, a colour scale to be utilised for plotting. It should be a list with colors and breaks components (usually created via create_scale). If not defined, it is computed from col_range.
contour	Logical. Indicates, whether contours should be plotted in the graph. Default value is FALSE.
show_legend	Logical. Indicates, whether legend should be displayed beside the graph. Default value is TRUE.
label_sensors	A logical value indicating whether the sensor labels should also be plotted (default value is FALSE).

Details

For more details about required mesh structure see point_mesh function. If the input mesh structure does not match this format, an error or incorrect function behavior may occur.

Be careful when choosing the argument col_range. If the amplitude in input data contains values outside the chosen range, this will cause "holes" in the resulting plot. To compare results for different subjects or conditions, set the same values of col_range and col_scale arguments in all cases. The default used scale is based on topographical colours with zero value always at the border of blue and green shades.

Note: When specifying the coords and template at the same time, the template parameter takes precedence and the coords parameter is ignored.

Value

A ggplot object showing an interpolated topographic map of EEG amplitude.

See Also

animate_topo, point_mesh, plot_topo_mean

Examples

# Plot average topographic map of signal for subject 2 from the time point 10
# (the time of the stimulus) without the outliers (epoch 14 and 15)

# a) preparing data
# a1) extract required data
edata <- epochdata |>
dplyr::filter(subject == 2 & time %in% 1:10 & epoch %in% 1:13)
# a2) baseline correction (needed for suitable topographic map)
data_base <- baseline_correction(edata, baseline_range = 1:10)
# a3) average computing
data_mean <- compute_mean(data_base, amplitude = "signal_base", subject = 2, time = 10,
 type = "jack", group = "space")


# b) plotting the topographic map with contours and legend
# interval (-30,15) is selected in consideration of the signal progress
topo_plot(data = data_mean, amplitude = "average", template = "HCGSN256",
col_range = c(-30, 15), contour = TRUE)

# c) plotting the same map without contours but with sensor labels
topo_plot(data = data_mean, amplitude = "average", template = "HCGSN256",
 col_range = c(-30, 15), label_sensors = TRUE)

diegr documentation built on Nov. 5, 2025, 5:25 p.m.