diegr (version 0.2.0)

interactive_waveforms: Plot interactive waveform graph

Description

Function for plotting time series of EEG signal colour-coded by epoch, condition, channel, subject or group (depending on selected level parameter) an interactive plotly graph. The function assumes that the input data have already been filtered to the desired subset according to the level. When using the function for plotting the average, there is an option to add a confidence band using the CI argument. The output in plotly format enables to easily edit the image layout.

Usage

interactive_waveforms(
  data,
  amplitude = "signal",
  FS = 250,
  t0 = NULL,
  col_palette,
  level = "epoch",
  avg = TRUE,
  CI = FALSE,
  use_latex = TRUE
)

Value

A plotly object showing an interactive time series of the signal according to the chosen level.

Arguments

data

A data frame, tibble or a database table with input data containing a time column and columns corresponding to the selected amplitude and level parameter (see Details).

amplitude

A character specifying the name of the column from input data with an EEG amplitude values. Default is "signal".

FS

The sampling frequency. Default value is 250 Hz.

t0

Index of the zero time point, i.e. point, where 0 ms should be marked (most often time of the stimulus or time of the response).

col_palette

Optionally, a colour palette for plotting lines. If missing, the rainbow palette is used. The expected length is the same (or higher) as the number of unique levels (e.g. number of epochs for level = "epoch").

level

A character specifying the level of the time curves. The possible values are "epoch" (default option), "condition", "sensor", "subject" and "group". See details for more information.

avg

A logical value indicating, if the average black curve should be plotted. Default is TRUE.

CI

A logical value indicating, if the confidence ribbon should be plotted. Default is FALSE. See Details for more information.

use_latex

A logical value indicating whether to use LaTeX formatting for the y-axis title. The default is TRUE.

Details

The input data frame or database table must contain column time (a column with time point numbers) and a column with the EEG amplitude (or average amplitude) specified in the argument amplitude.
It must also contain at least one of the optional columns (according to the level parameter - for "sensor" level the column sensor is required etc.):
group - a column with group identifiers,
subject - a column with subject IDs,
sensor - a column with sensor labels,
epoch - a column with epoch numbers.

Note: The average signals must be pre-aggregated before plotting at higher grouping levels, for example sensor level assumes a mean sensor signal in the amplitude column (the input data for individual epochs together with sensor level setting will result in a mess output).

Plotting confidence ribbon: To plot the confidence bands around the average lines (CI = TRUE), the input data must include the ci_up and ci_low columns (as in the output tibble from compute_mean function).

Examples

# 1) Plot epoch waveforms with average curve for subject 1 and electrode "E65"
# with 250 sampling frequency rate (default) and 10 as zero time point
epochdata |>
pick_data(subject_rg = 1, sensor_rg = "E65") |>
interactive_waveforms(amplitude = "signal", t0 = 10, level = "epoch")

# 2) Plot sensor level waveforms with confidence bands for subject 1 and electrodes "E65" and "E182"
# a) preparing data
sendata <- epochdata |>
pick_data(subject_rg = 1, sensor_rg = c("E65", "E182")) |>
compute_mean(amplitude = "signal", domain = "time", level = "epoch")
# b) plot the waveforms without the average
interactive_waveforms(sendata, amplitude = "average", t0 = 10,
level = "sensor", avg = FALSE, CI = TRUE)