Skip to contents

Plots interpolated maps of observed sensor-level means, population-level posterior median expected responses, and residuals (`observed - predicted`). Inferences and clusters remain at the *original sensor locations*, not at interpolated pixels. Interpolation is for visualisation only and uses inverse-distance weighting (IDW) without additional package dependencies.

Usage

plot_spatiotemporal_topography(
  results,
  observed_data,
  observed_data_b = NULL,
  outcome_id = "voltage",
  sensor_id = "channel",
  time_id = "time",
  spatial_id = c("xproj", "yproj"),
  participant_id = NULL,
  times = NULL,
  n_times = 8L,
  what = c("observed", "predicted", "residual"),
  grid_n = 85L,
  idw_power = 2,
  limits = NULL,
  contour = TRUE,
  show_sensors = TRUE,
  show_labels = FALSE,
  head_outline = TRUE,
  cluster_overlay = c("predicted", "all", "none"),
  cluster_alpha = 0.9,
  cluster_size = 2.8
)

Arguments

results

Object returned by [analyse_bgam_spatiotemporal()].

observed_data

Original long-form observations, or condition A data.

observed_data_b

Observed condition B if `results` is an A - B contrast.

outcome_id

Observed outcome column.

sensor_id

Sensor identifier shared by observed data and predictions.

time_id

Numeric time column.

spatial_id

Two projected spatial coordinate columns.

participant_id

Optional participant ID for an equal-participant- weighted observed average. With `NULL`, observations are pooled.

times

Optional requested times; closest existing samples are used.

n_times

Number of evenly distributed panels if `times = NULL`.

what

One or more of `"observed"`, `"predicted"`, `"residual"`.

grid_n

Number of interpolated pixels per grid axis.

idw_power

Positive IDW inverse-distance exponent.

limits

Symmetric range half-width of a shared color scale, or `NULL` for automatic scaling across all selected panels.

contour

Whether to draw interpolated iso-value contours.

show_sensors

Show original electrode locations.

show_labels

Show sensor names (can be busy with dense montages).

head_outline

Add schematic scalp circle and nose.

cluster_overlay

`"predicted"` highlights inference clusters only on predicted maps; `"all"` on all maps; `"none"` disables highlights.

cluster_alpha

Transparency of cluster-marking rings.

cluster_size

Size of cluster-marking rings.

Value

A ggplot object.

Author

Ladislas Nalborczyk ladislas.nalborczyk@cnrs.fr.

Examples

if (FALSE) { # \dontrun{
# Not run: generating `results_st` requires
# computationally intensive Bayesian model fitting.
# `eeg_data2` contains the corresponding observations.
plot_spatiotemporal_topography(
    results_st, eeg_data2, outcome_id = "voltage",
    sensor_id = "channel", n_times = 8
    )
} # }