dplyr_verbs: Dplyr-like functions for manipulating eeg_lst objects.

In bnicenboim/eeguana: Flexible Manipulation of EEG Data

Dplyr-like functions for manipulating eeg_lst objects.

Description

Manipulate the signal table and the segments table of an eeg_lst with dplyr-like functions.

Usage

eeg_mutate(.data, ...)

eeg_transmute(.data, ...)

eeg_filter(.data, ..., .preserve = FALSE)

eeg_summarize(.data, ..., .groups = "keep")

eeg_summarise(.data, ..., .groups = "keep")

eeg_group_by(.data, ..., .add = FALSE, .drop = FALSE)

eeg_ungroup(.data, ...)

eeg_select(.data, ...)

eeg_rename(.data, ...)

eeg_rename_with(.data, .fn, .cols = where(is_channel_dbl), ...)

eeg_groups(x)

## S3 method for class 'eeg_lst'
eeg_groups(x)

eeg_group_vars(x)

eeg_left_join(x, y, by = NULL, suffix = c(".x", ".y"), ..., keep = FALSE)

eeg_semi_join(x, y, by = NULL)

eeg_anti_join(x, y, by = NULL)

eeg_pull(.data, var = -1, name = NULL, ...)

across(.cols = everything(), .fns = NULL, ..., .names = NULL)

across_ch(.fns = NULL, ..., .names = NULL)

c_across_ch()

c_across(.cols = everything())

Arguments

.data	An eeg_lst.
...	Name-value pairs of expressions; see dplyr for more help.
.preserve	Not in use, for compatibility reasons.
.groups	Only .groups = "keep" is available. Same grouping structure as .data.
.add	When FALSE, the default, group_by() will override existing groups. To add to the existing groups, use .add = TRUE.
.drop	Only .drop = FALSE is available, empty groups are never dropped.
.fn	Function to transform the names with.
.cols	Columns to rename. Defaults to all columns. tidyselect compatible.
x	An eeg_lst.
y	A data frame, tibble, or data.table.
by	A character vector of variables to join by. If NULL, the default, the join will do a natural join, using all variables with common names across the two tables.
suffix	Append created for duplicated column names when using full_join()
keep	Should the join keys from both x and y be preserved in the output?
var	A variable specified as: a literal variable name a positive integer, giving the position counting from the left a negative integer, giving the position counting from the right. The default returns the last column (on the assumption that's the column you've created most recently). This argument is taken by expression and supports quasiquotation (you can unquote column names and column locations).
name	An optional parameter that specifies the column to be used as names for a named vector. Specified in a similar manner as var.
.fns	Function to apply. Can be a purrr-style lambda. Can pass also list of functions.
.names	A glue specification that helps with renaming output columns. {.col} stands for the selected column, and {.fn} stands for the name of the function being applied. The default (NULL) is equivalent to "{.col}" for a single function case and "{.col}_{.fn}" when a list is used for .fns.

Details

Wrappers for dplyr's commands that act eeg_lst objects. Functions that drop or rename columns won't remove columns starting with a dot. These functions are powered by data.table through tidytable.

The following wrappers act in a special way for eeg_lst objects:

• ⁠eeg_*_join()⁠: joins an external table to the segments table of the eeg_lst.

• eeg_mutate() and eeg_transmute(): mutates the signal_tbl table when is applied to a channel (or a column of the signal table), and mutates the segments table otherwise. It can also mutates by reference.

• eeg_summarize() summarizes the channel of the signal_tbl table.

• eeg_pull() only pulls columns of the signal table

In addition, across(), and c_across() work as well. Notice that there are convienent wrappers across_ch() and c_across_ch() where the argument .cols is always set to where(is_channel_dbl).

Gotchas

These functions emulate dplyr functionality but they are actually powered by the wrapper of data.table, tidytable and some times they might be behave a bit differently than the dplyr counterpart.

• The default values of the arguments might be different, and some arguments might not exist for the eeguana dplyr-like functions.

• Grouped mutations behave slightly different than ungrouped ones: Channel properties are removed if the data is ungrouped and one does eeg_mutate(data, channel = 0), but not if the data is grouped.

• eeguana's eeg_mutate doesn't allow to refer back to a recently created channel: data_eeg %>% eeg_mutate(X = F1 *2, Y = X) is not valid. One needs to do data_eeg %>% eeg_mutate(X = F1) %>% eeg_mutate(Y = X).

• eeguana's eeg_mutate doesn't use the most updated value of a column from the same call. If X is a channel, then data_eeg %>% eeg_mutate(X = X *2, Y = X+1) will add 1 to the original value of X, and not to the latest one.

• eeg_filter behaves similarly to dplyr's filter. If you want to filter the signal using IIR or FIR filters use eeg_filt* functions.

Pitfalls

These functions not only edit the eeg_lst objects but they also do book-keeping: They remove unnecessary channels, or update their information and they ensure that three tables (signal, segments, and events) match. It's then not recommended to edit the signal and segments table directly. (The events and channels table can be edited directly by doing events_tbl(data_eeg) <- ... or channels_tbl(data_eeg) <- ...).

Value

An eeg_lst object.

See Also

Other tidyverse-like functions: drop_incomplete_segments(), eeg_bind(), eeg_slice_signal()

Examples

library(dplyr)
# Create new channel in the signal table
data_faces_ERPs %>%
  eeg_mutate(tmp = Fz - Cz)

# Create a new condition in the segments table
data_faces_ERPs %>%
  eeg_mutate(code = ifelse(condition == "faces", 1, -1))

# Create a new channel and drop all others
data_faces_ERPs %>%
  eeg_transmute(Occipital = chs_mean(O1, O2, Oz,
    na.rm = TRUE
  ))

# Extract data associated with a condition
data_faces_ERPs %>%
  eeg_filter(condition == "faces")

# Group and summarize
data_faces_ERPs %>%
  # Convert samples to times, filter between timepoints
  eeg_filter(between(
    as_time(.sample, .unit = "ms"),
    100, 200
  )) %>%
  # Find mean amplitude of Fz for each condition
  eeg_group_by(condition) %>%
  eeg_summarize(mean.amplitude = mean(Fz))

# Mean of each channel
data_faces_ERPs %>%
  eeg_summarize(across_ch(mean))

# Select specific electrodes
data_faces_ERPs %>%
  eeg_select(O1, O2, P7, P8)

# Rename a variable
data_faces_ERPs %>%
  eeg_rename(Predictor = condition)

bnicenboim/eeguana documentation built on March 16, 2024, 7:21 a.m.