diegr

epochdata

The brain signal originally measured by 256-channel HydroCel Geodesic Sensor Net with sampling frequency 250 Hz. Example dataset contains amplitude values from 204 selected channels at 50 time points (stimulus at time point 10) for 2 representative subjects (one healthy control, one patient). From 50 epochs per subject, 14 (or 15) epochs were selected.

The data is organized into a data frame with the following columns:

• time: Number of time point. Number 10 indicates the time of stimulus (0 ms), the interval between two time points corresponds to 4 ms (sampling frequency 250 Hz).
• signal: HD-EEG signal amplitude (in microvolts).
• epoch: Epoch number (there are 14 epochs for subject one, 15 epochs for subject two).
• sensor: Sensor label (labeling corresponds to the Geodesic Sensor Net Technical Manual, 2024).
• subject: Subject ID (1 - representative healthy control subject, 2 - representative patient subject).

HCGSN256

The Cartesian coordinates of HD-EEG sensor positions in 3D space on the scalp surface and their projection into 2D space according to 256-channel HydroCel Geodesic Sensor Net average template montage.

The data is organized into a list with the following elements:

• D2: A tibble with coordinates and labels of sensors in 2D.
• D3: A tibble with coordinates and labels of sensors in 3D.
• ROI:A vector with the region of interest (ROI) assignment for each sensor (“central”, “frontal”, “occipital”, “parietal” or “temporal”).
• pairedname: Alternative sensor labels corresponding to left/right paired electrodes (with C for midline). Sensors are labeled according to Geodesic Sensor Net Technical Manual, 2024.

Axis orientation (3D): - x: left (-) to right (+); - y: posterior (-) to anterior (+); - z: inferior (-) to superior (+).

rtdata

The response time values in individual experiment epochs for 2 representative subjects (one from patient, one from healthy control group). The epochs and subjects correspond to the sample dataset epochdata.

The data is organized into a data frame with the following columns:

• subject: Subject ID (1 - representative healthy control subject, 2 - representative patient subject).
• epoch: Epoch number (there are 14 epochs for subject one, 15 epochs for subject two).
• RT: Response time in ms.

Mesh Generation

The original electrode grid is too coarse for graphical rendering. To achieve smoother and more visually appealing results in plots, it’s necessary to generate a denser mesh of points. This refined mesh provides better spatial resolution and enhances the quality of visualizations. Creating a new mesh is available through point_mesh() function. This function computes the coordinates of mesh in 2D and/or 3D and enables to control a density (argument n) or the shape (argument type) of the result mesh.
The default setting creates a polygonal mesh with starting number 10000 points and computes the coordinates in both dimensions, which are available in $D2 and $D3 parts of a result list (class "mesh").

For simple created mesh plotting use the function plot_point_mesh(), which results in two dimensional ggplot of point mesh or three dimensional rgl plot depending on the input dimension.

Notes:

• Creating and plotting a mesh for subset from the whole template montage is available through sensor_select parameter. For consistency between created mesh and its plot use the same vector of sensor labels in both functions.
• The input of plot_point_mesh() must be only the relevant part with coordinates - $D2 for two dimensional and $D3 for three dimensional plot.
• If the number of mesh points is large, they are no longer visible in the plot and the mesh looks like a solid surface (as can be seen below in first plot).
• Depending on the hardware used, the computational cost of default n = 10000 can be high. In this case we recommend to reduce n and to reuse a precomputed mesh across plots for speed.

# creating a mesh with default settings
sensors204 <- unique(epochdata$sensor)
M1 <- point_mesh(template = "HCGSN256", sensor_select = sensors204)
# plot output in 2D
plot_point_mesh(M1$D2, sensor_select = sensors204)

# creating a circular mesh, only 2D coordinates
M2 <- point_mesh(dimension = 2, n = 3000, template = "HCGSN256",
                 sensor_select = sensors204, type = "circle")
# plotting a mesh - function allows different options of the result plot
plot_point_mesh(M2$D2, sensor_select = sensors204, col_sensors = "purple",
                label_sensors = TRUE, cex = 0.1)

diegr’s plotting functions also allow users to input the custom mesh created in other way, it is only necessary to maintain the structure following a "mesh" object.
If the mesh input is not specified, the graphic functions automatically use the mesh created by point_mesh() with default settings.

Topographical maps in 2D projection

The topo_plot() function is used to plot a topographic map of the brain signal, the amplitude values are colored using a topographic colour scale (unless users choose otherwise). An alternative to this function adapted directly to plot the mean along with the confidence interval bounds is plot_topo_mean(). In the default colour scale, amplitude = 0 is mapped to the blue–green boundary; positive values trend towards yellow/red, negative towards dark blue. Both functions allow setting some optionally arguments for editing the output appearance (with or without contours, sensor names, etc.) and return ggplot object for further customization.

Notes:

• The input values of amplitude (or also CI bounds in the case of the plot_topo_mean() function) outside the chosen col_range will cause “holes” in the resulting plot.

• To compare results for different subjects or conditions, setting the same values of col_range and col_scale arguments in all cases is necessary.

# Plot average topographic map of baseline corrected signal for subject 1 
# from the time point 10 (the time of the stimulus)
# the outlier epoch 14 is extracted before computing average

# preparing data
edata <- epochdata |>
  dplyr::filter(subject == 1 & time %in% 1:10)
data_base <- baseline_correction(edata, baseline_range = 1:10)
data_mean <- compute_mean(data_base, amplitude = "signal_base", time = 10,
                          type = "point", ex_epoch = 14, group = "space")

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

# plotting the same map without contours and legend 
# but with sensor labels and adding the title
g1 <- topo_plot(data = data_mean, amplitude = "average", col_range = c(-30, 15),
                label_sensors = TRUE, show_legend = FALSE)
g1 + ggplot2::ggtitle("Subject 1, time of the stimulus")

# plotting the average together with CI bounds using plot_topo_mean
plot_topo_mean(data = data_mean, template = "HCGSN256", col_range = c(-30, 15))

Topographical maps on the scalp

The scalp_plot() function is created for plotting a scalp polygon map of the EEG signal amplitude using topographic colour scale (default scale is the same as in topo_plot()). The result plot is rendered using rgl::shape3d function and the signal interpolation between sensor locations is based on thin-plate spline interpolation model.
Correct mesh triangulation is required for appropriate colour rendering. This triangulation is constructed by make_triangulation(), which creates a Delaunay type-I triangulation (Lai & Schumaker, 2007) with consistently oriented edges (Schneider & Eberly, 2003).

The function allows setting the col_range argument, which is necessary to obtain comparable results between different subjects or conditions.

Note: The input values of amplitude outside the chosen col_range will cause “holes” in the resulting plot.

# plotting the scalp polygon map of previously prepared signal s1
#open3d()
scalp_plot(s1, amplitude = "average", col_range = c(-30, 15))

# note: the output is not plotted to reduce the vignette file size

The rgl output enables to zoom and rotate the image with default view of the back of the head.

References

Lai M-J, Schumaker LL. Spline functions on triangulations. Cambridge University Press; 2007.

Schneider PJ, Eberly DH. Geometric Tools for Computer Graphics. The Morgan Kaufmann Series in Computer Graphics. San Francisco: Morgan Kaufmann, 2003.

Madetko-Alster N., Alster P., Lamoš M., Šmahovská L., Boušek T., Rektor I. and Bočková M. The role of the somatosensory cortex in self-paced movement impairment in Parkinson’s disease. Clinical Neurophysiology. 2025, vol. 171, 11-17. https://doi.org/10.1016/j.clinph.2025.01.001

Wickham H, Bryan J. R Packages (2e). O’Reilly Media; 2023.

Wickham H. ggplot2: Elegant Graphics for Data Analysis. Springer; 2016.

Electrical Geodesics, Inc.: Geodesic Sensor Net Technical Manual. 2024. https://www.egi.com/knowledge-center

Reproducibility & System Requirements

This document was compiled on 2025-09-18 using R version 4.5.0 and the following package versions:

• Primary Packages:

  • diegr (version 0.1.0)
  • dplyr (version 1.1.4)
  • rgl (version 1.3.18)
  • plotly (version 4.10.4)
  • gganimate (version 1.0.9)
  • gifski (version 1.32.0.2)
  • av (version 0.9.4)

• rgl on Headless Systems: The rgl package requires specific setup for graphics on systems without a display (headless servers, like those often used for package checks). If you are reproducing this vignette on a headless system, ensure the following command is run before loading rgl:

  options(rgl.useNULL = TRUE)
  # Alternatively, set the environment variable RGL_USE_NULL="true"

• Media Requirements: Interactive plots (from plotly) and animations (from gganimate and gifski / av) require the respective R packages and, for local rendering or specific output formats, may require external libraries or codecs. If media fails to render, check the documentation for plotly, gganimate, gifski, and av regarding system dependencies for video/GIF encoding.

• Full Session Details: For complete details on the software environment, please run the following command in your R session:

  sessionInfo()