Package 'eegUtils'

Description

Electroencephalography data processing and visualization tools. Includes import functions for 'BioSemi' (.BDF), 'Neuroscan' (.CNT), 'Brain Vision Analyzer' (.VHDR), 'EEGLAB' (.set) and 'Fieldtrip' (.mat). Many preprocessing functions such as referencing, epoching, filtering, and ICA are available. There are a variety of visualizations possible, including timecourse and topographical plotting.

Author(s)

Maintainer: Matt Craddock [email protected]

Other contributors:

• Matti Vuorre [email protected] [contributor]

• ggplot2 authors (Routines borrowed from ggplot2 to allow contours to be drawn on topoplots) [copyright holder]

See Also

Useful links:

• https://github.com/craddm/eegUtils

• https://craddm.github.io/eegUtils

• https://craddm.github.io/eegUtils/

• Report bugs at https://github.com/craddm/eegUtils/issues

Description

This function can be used to either recreate "mixed" (i.e. channel level) timecourses from an ICA decomposition, or to apply a set of ICA weights to a given dataset for the purpose of removing specific ICA components from that dataset.

Usage

apply_ica(data, ...)

## S3 method for class 'eeg_ICA'
apply_ica(data, comps = NULL, ...)

## S3 method for class 'eeg_epochs'
apply_ica(data, decomp, comps, ...)

Arguments

Methods (by class)

• apply_ica(eeg_ICA): From given eeg_ICA object, recreate channel timecourses.

• apply_ica(eeg_epochs): Combine a specific set of ICA weights with any eeg_epochs object.

Author(s)

Matt Craddock [email protected]

Examples

test_ica <- run_ICA(demo_epochs, pca = 10)
plot_butterfly(demo_epochs)
# Reconstruct the original data from the ICA decomposition.
# Note that the ICA process subtracts the mean from each epoch,
# so the reconstructed plot may look slightly different to the original.
plot_butterfly(apply_ica(test_ica))
# Remove component 2 from the data
plot_butterfly(apply_ica(demo_epochs, test_ica, comps = 2))

Description

Low autocorrelation can be a sign of a poor quality channel or component. Often these are noisy, poor contact, or heavily contaminated with muscle noise. Low autocorrelation at a lag of 20ms is often associated with muscle noise.

Usage

ar_acf(data, ...)

## S3 method for class 'eeg_ICA'
ar_acf(data, ms = 20, plot = TRUE, verbose = TRUE, threshold = NULL, ...)

Arguments

Value

A character vector of component names that break the threshold.

Methods (by class)

• ar_acf(eeg_ICA): Autocorrelation checker for eeg_ICA objects

Author(s)

Matt Craddock [email protected]

References

Chaumon, M., Bishop, D.V., Busch, N.A. (2015). A practical guide to the selection of independent components of the electroencephalogram for artifact correction. J Neurosci Methods. Jul 30;250:47-63. doi: 10.1016/j.jneumeth.2015.02.025

Examples

demo_sobi <- run_ICA(demo_epochs, pca = 10)
ar_acf(demo_sobi)

Description

Detect components that load heavily on a single channel. Looks for components that have one particular channel that has a particularly high z-score.

Usage

ar_chanfoc(
  data,
  plot = TRUE,
  threshold = NULL,
  verbose = TRUE,
  measure = "max",
  ...
)

Arguments

Value

A character vector of component names that break the threshold.

Author(s)

Matt Craddock [email protected]

References

Chaumon, M., Bishop, D.V., Busch, N.A. (2015). A practical guide to the selection of independent components of the electroencephalogram for artifact correction. J Neurosci Methods. Jul 30;250:47-63. doi: 10.1016/j.jneumeth.2015.02.025

Examples

demo_sobi <- run_ICA(demo_epochs, pca = 10)
ar_chanfoc(demo_sobi)

Description

Checks the correlation between individual components of an eeg_ICA decomposition and the electrooculogram channels of an eeg_epochs dataset.

Usage

ar_eogcor(decomp, data, ...)

## S3 method for class 'eeg_ICA'
ar_eogcor(
  decomp,
  data,
  HEOG,
  VEOG,
  threshold = NULL,
  plot = TRUE,
  bipolarize = TRUE,
  method = c("pearson", "kendall", "spearman"),
  verbose = TRUE,
  ...
)

Arguments

Value

A character vector of component names that break the threshold.

Methods (by class)

• ar_eogcor(eeg_ICA): Method for eeg_ICA objects.

Author(s)

Matt Craddock, [email protected]

References

Chaumon, M., Bishop, D.V., Busch, N.A. (2015). A practical guide to the selection of independent components of the electroencephalogram for artifact correction. J Neurosci Methods. Jul 30;250:47-63. doi: 10.1016/j.jneumeth.2015.02.025

Description

Calculates and removes the contribution of eye movements to the EEG signal using least-squares regression. Specifically, it generate regression weights based on EOG channels that are used to estimate how much activity eye movements are responsible for across all channels.

Usage

ar_eogreg(data, heog, veog, bipolarize = TRUE)

## S3 method for class 'eeg_data'
ar_eogreg(data, heog, veog, bipolarize = TRUE)

## S3 method for class 'eeg_epochs'
ar_eogreg(data, heog, veog, bipolarize = TRUE)

Arguments

Value

An eeg_data or eeg_epochs object with corrections applied.

Author(s)

Matt Craddock, [email protected]

Description

An implementation of the FASTER artefact rejection method for EEG by Nolan, Whelan & Reilly (2010) FASTER: Fully Automated Statistical Thresholding for EEG artifact Rejection. J Neurosci Methods.

Usage

ar_FASTER(data, ...)

## S3 method for class 'eeg_epochs'
ar_FASTER(
  data,
  exclude = NULL,
  test_chans = TRUE,
  test_epochs = TRUE,
  test_cine = TRUE,
  ...
)

## S3 method for class 'eeg_group'
ar_FASTER(
  data,
  exclude = NULL,
  test_chans = TRUE,
  test_epochs = TRUE,
  test_cine = TRUE,
  EOG = NULL,
  ...
)

eeg_FASTER(data, ...)

Arguments

Value

An eeg_epochs object with artefact correction applied.

Methods (by class)

• ar_FASTER(eeg_epochs): Run FASTER on eeg_epochs

• ar_FASTER(eeg_group): Run FASTER on eeg_group objects

Author(s)

Matt Craddock [email protected]

References

Nolan, Whelan & Reilly (2010). FASTER: Fully Automated Statistical Thresholding for EEG artifact Rejection. J Neurosci Methods.

Examples

ar_FASTER(demo_epochs)

Description

Reject data based on a simple absolute amplitude threshold. This marks any timepoint from any electrode.

Usage

ar_thresh(data, threshold, reject = FALSE)

## S3 method for class 'eeg_data'
ar_thresh(data, threshold, reject = FALSE)

## S3 method for class 'eeg_epochs'
ar_thresh(data, threshold, reject = FALSE)

Arguments

Value

An object of class eeg_data or eeg_epochs

Methods (by class)

• ar_thresh(eeg_data): Reject data using a simple threshold.

• ar_thresh(eeg_epochs): Reject data using a simple threshold.

Author(s)

Matt Craddock [email protected]

Examples

ar_thresh(demo_epochs, c(100))

Description

Detect components that load heavily on a small number of trials. Looks for components that have one particular trial that has a particularly high z-score.

Usage

ar_trialfoc(data, plot = TRUE, threshold = NULL, verbose = TRUE)

Arguments

Value

A character vector of component names that break the threshold.

Author(s)

Matt Craddock [email protected]

References

Chaumon, M., Bishop, D.V., Busch, N.A. (2015). A practical guide to the selection of independent components of the electroencephalogram for artifact correction. J Neurosci Methods. Jul 30;250:47-63. doi: 10.1016/j.jneumeth.2015.02.025

Examples

demo_sobi <- run_ICA(demo_epochs, pca = 10)
ar_trialfoc(demo_sobi)

Description

Convert an object of class eeg_data into a standard data.frame.

Usage

## S3 method for class 'eeg_data'
as.data.frame(
  x,
  row.names = NULL,
  optional = FALSE,
  long = FALSE,
  events = FALSE,
  coords = FALSE,
  ...
)

Arguments

Author(s)

Matt Craddock [email protected]

Description

Convert an eeg_epochs object to a data.frame for use with whatever packages you desire.

Usage

## S3 method for class 'eeg_epochs'
as.data.frame(
  x,
  row.names = NULL,
  optional = FALSE,
  long = FALSE,
  events = FALSE,
  cond_labels,
  coords = TRUE,
  ...
)

Arguments

Author(s)

Matt Craddock [email protected]

Description

Convert eeg_evoked object to data frame

Usage

## S3 method for class 'eeg_evoked'
as.data.frame(
  x,
  row.names = NULL,
  optional = FALSE,
  long = FALSE,
  coords = TRUE,
  ...
)

Arguments

Author(s)

Matt Craddock [email protected]

Description

Convert eeg_ICA object to data frame

Usage

## S3 method for class 'eeg_ICA'
as.data.frame(
  x,
  row.names = NULL,
  optional = FALSE,
  long = FALSE,
  cond_labels,
  mixing = FALSE,
  coords = TRUE,
  ...
)

Arguments

Author(s)

Matt Craddock [email protected]

Description

Convert an object of class eeg_data into a standard data.frame.

Usage

## S3 method for class 'eeg_lm'
as.data.frame(
  x,
  row.names = NULL,
  optional = FALSE,
  long = FALSE,
  coords = TRUE,
  values = c("coefficients", "std_err", "t_stats", "r_sq"),
  ...
)

Arguments

Author(s)

Matt Craddock [email protected]

Description

Convert eeg_stats objects to data frames

Usage

## S3 method for class 'eeg_stats'
as.data.frame(
  x,
  row.names = NULL,
  optional = FALSE,
  long = FALSE,
  coords = FALSE,
  ...
)

Arguments

Author(s)

Matt Craddock [email protected]

Description

Convert eeg_tfr objects to a data.frame

Usage

## S3 method for class 'eeg_tfr'
as.data.frame(x, row.names = NULL, optional = FALSE, long = FALSE, ...)

Arguments

Value

A data.frame or tibble

Author(s)

Matt Craddock [email protected]

Description

A Shiny gadget for browsing EEG data and ICA decompositions interactively. With EEG data (epoched or continuous), data can be viewed as a butterfly plot (all electrodes overlaid) or as individual traces (electrodes "stacked"). For eeg_ICA objects, you will instead be shown a composite of multiple properties of the decomposition - a topography, an ERP image, an ERP, and a power spectral density plot from 4-50 Hz.

Usage

browse_data(data, ...)

## S3 method for class 'eeg_ICA'
browse_data(data, ...)

## S3 method for class 'eeg_data'
browse_data(data, sig_length = 5, downsample = TRUE, ...)

## S3 method for class 'eeg_epochs'
browse_data(data, sig_length = 5, downsample = FALSE, ...)

Arguments

Value

A character vector of component names selected for rejection.

Methods (by class)

• browse_data(eeg_ICA): View eeg_ICA component properties

• browse_data(eeg_data): Browse continuous EEG data.

• browse_data(eeg_epochs): Browse epoched EEG data.

Author(s)

Matt Craddock [email protected]

Description

Get the names of the signals element of eegUtils objects.

Usage

channel_names(.data)

Arguments

Examples

channel_names(demo_epochs)

Description

Channel statistics

Usage

channel_stats(data, ...)

## S3 method for class 'eeg_data'
channel_stats(data, ...)

Arguments

Value

A data frame with statistics for each channel.

Methods (by class)

• channel_stats(eeg_data): Calculate channel statistics for eeg_data objects.

Author(s)

Matt Craddock [email protected]

Examples

channel_stats(demo_epochs)

Description

Get or set the contents of the channel information inside eegUtils objects.

Usage

channels(.data)

channels(.data) <- value

Arguments

Author(s)

Matt Craddock [email protected]

Examples

channels(demo_epochs)

Description

Convert an eeg_data or eeg_epochs object to using Current Source Densities. This command uses a spherical spline algorithm (Perrin et al., 1989) to compute scalp surface Laplacian/current source density estimates of scalp potentials, a reference-free measure of electrical activity that emphasises more local spatial features

Usage

compute_csd(data, ...)

## Default S3 method:
compute_csd(data, ...)

## S3 method for class 'eeg_data'
compute_csd(data, m = 4, smoothing = 1e-05, scaling = 1, ...)

## S3 method for class 'eeg_epochs'
compute_csd(data, m = 4, smoothing = 1e-05, scaling = 1, ...)

Arguments

Methods (by class)

• compute_csd(default): Default method to detect unknown classes.

• compute_csd(eeg_data): Transform eeg_data to CSD

• compute_csd(eeg_epochs): Transform eeg_data to CSD

Author(s)

Matt Craddock [email protected]

References

• Perrin, F., Pernier, J., Bertrand, O., Echallier, J.F. (1989). Spherical splines for scalp potential and current density mapping. Electroencephalography and Clinical Neurophysiology, 72(2), 184-187. PMID: 2464490

• Kayser, J., Tenke, C.E. (2006). Principal components analysis of Laplacian waveforms as a generic method for identifying ERP generator patterns: I. Evaluation with auditory oddball tasks. Clinical Neurophysiology, 117(2), 348-368.

• Kayser, J., Tenke, C.E. (2015). Issues and considerations for using the scalp surface Laplacian in EEG/ERP research: A tutorial review. International Journal of Psycholphysiology, 97(3), 189-209

Examples

csd_epochs <- compute_csd(demo_epochs)
plot_butterfly(csd_epochs)

# Compare the topographies of the CSD vs average referenced data
topoplot(demo_epochs, c(.2, .21))
topoplot(csd_epochs, c(.2, .21))

Description

Calculates inter-trial coherence (ITC), a measure of phase consistency across single trial data. Input data must be provided as complex Fourier coefficients within an eeg_tfr object

Usage

compute_itc(data)

Arguments

Value

An eeg_tfr object

Description

compute_psd returns the PSD calculated using Welch's method for every channel in the data. The output is in microvolts-squared divided by Hertz - $\muV^2 / Hz$. If the object has multiple epochs, it will perform Welch's FFT separately for each epoch and then average them afterwards.

Usage

compute_psd(data, ...)

## S3 method for class 'eeg_data'
compute_psd(
  data,
  seg_length = NULL,
  noverlap = NULL,
  n_fft = NULL,
  method = "Welch",
  demean = TRUE,
  verbose = TRUE,
  ...
)

## S3 method for class 'eeg_epochs'
compute_psd(
  data,
  seg_length = NULL,
  noverlap = NULL,
  n_fft = 256,
  method = "Welch",
  keep_trials = TRUE,
  demean = TRUE,
  verbose = TRUE,
  ...
)

## S3 method for class 'eeg_evoked'
compute_psd(
  data,
  seg_length = NULL,
  noverlap = NULL,
  n_fft = 256,
  method = "Welch",
  demean = TRUE,
  verbose = TRUE,
  ...
)

Arguments

Details

Welch's FFT splits the data into multiple segments, calculates the FFT separately for each segment, and then averages over segments. Each segment is windowed with a Hanning window to counter spectral leakage. For epoched data, Welch's FFT is calculated separately for each trial.

The number of sampling points used for the FFT can be specified using n_fft. n_fft defaults to 256 sampling points for eeg_epochs data, or the minimum of 2048 or the length of the signal for continuous eeg_data.

seg_length defaults to be n_fft, and must be less than or equal to it.

noverlap specifies the amount of overlap between windows in sampling points. If NULL, it defaults to 50\

Value

Currently, a data frame with the PSD for each channel separately.

Methods (by class)

• compute_psd(eeg_data): Compute PSD for an eeg_data object

• compute_psd(eeg_epochs): Compute PSD for an eeg_epochs object

• compute_psd(eeg_evoked): Compute PSD for an eeg_evoked object

Author(s)

Matt Craddock [email protected]

Examples

out <- compute_psd(demo_epochs)

out <- compute_psd(demo_epochs, n_fft = 256, seg_length = 128)

Description

This function creates a time frequency representation of EEG time series data. Currently, it is possible to use either Morlet wavelets or Hanning tapers during the decomposition, which uses convolution in the frequency domain.

Usage

compute_tfr(data, ...)

## Default S3 method:
compute_tfr(data, ...)

## S3 method for class 'eeg_epochs'
compute_tfr(
  data,
  method = "morlet",
  foi,
  n_freq,
  spacing = "linear",
  n_cycles = 7,
  keep_trials = FALSE,
  output = "power",
  downsample = 1,
  trim_edges = TRUE,
  verbose = TRUE,
  ...
)

## S3 method for class 'eeg_evoked'
compute_tfr(
  data,
  method = "morlet",
  foi,
  n_freq,
  spacing = "linear",
  n_cycles = 7,
  keep_trials = FALSE,
  output = "power",
  downsample = 1,
  trim_edges = TRUE,
  verbose = TRUE,
  ...
)

Arguments

Value

An object of class eeg_tfr

Methods (by class)

• compute_tfr(default): Default method for compute_tfr

• compute_tfr(eeg_epochs): Default method for compute_tfr

• compute_tfr(eeg_evoked): Method for eeg_evoked objects.

Author(s)

Matt Craddock [email protected]

Examples

out <- compute_tfr(demo_epochs, method = "morlet", foi = c(4, 30), n_freq = 10, n_cycles = 3)
out
out$freq_info$morlet_resolution
out <- compute_tfr(demo_epochs, method = "morlet", foi = c(4, 30),
 n_freq = 10, n_cycles = c(3, 10))
out$freq_info$morlet_resolution
plot_tfr(out)
out <- compute_tfr(demo_epochs, method = "morlet", foi = c(4, 30),
 n_freq = 10, n_cycles = c(3, 10), trim_edges = FALSE)
plot_tfr(out)

Description

A helper function for calculating the appropriate min-max cycles for a fixed time window/frequency resolution for use with compute_tfr. For some analyses you may wish to keep a fixed frequency resolution across the range being analysed, which requires using a fixed time window. compute_tfr expects the minimum and maximum number of cycles to be supplied. Use this function to calculate the equivalent number of cycles at each frequency.

Usage

cycle_calc(time_win, frex)

Arguments

Value

the number of cycles for each frequency of interest

See Also

compute_tfr

Examples

cycle_calc(.5, seq(3, 30, length.out = 10))
no_scale_tfr <- compute_tfr(demo_epochs, foi = c(3, 30),
 n_cycles = range(cycle_calc(0.5, seq(3, 30, length.out = 10))),
  n_freq = 10)

Description

This is a small dataset with 11 electrodes and 80 epochs used for demonstrating some features of the eegUtils package.

Usage

demo_epochs

Format

An eeg_epochs object

Description

This is a small dataset with 23 electrodes and 80 epochs used for demonstrating some features of the eegUtils package. It is part of a recording from a visual spatial cueing task.

Usage

demo_spatial

Format

An eeg_epochs object

Description

This function is used to create an eeg_evoked object from eeg_epochs. By default, it will try to keep different conditions in the data separate using the epochs metadata from the object, thus yielding one average per condition. Alternatively, the user can specify which averages they want using the cols argument.

Usage

eeg_average(data, ...)

## Default S3 method:
eeg_average(data, ...)

## S3 method for class 'eeg_epochs'
eeg_average(data, cols = NULL, verbose = TRUE, ...)

## S3 method for class 'eeg_evoked'
eeg_average(data, cols = NULL, weighted = TRUE, verbose = TRUE, ...)

## S3 method for class 'eeg_tfr'
eeg_average(data, cols = NULL, weighted = TRUE, verbose = TRUE, ...)

Arguments

Value

An object of class eeg_evoked if applied to eeg_epochs; eeg_tfr if applied to eeg_tfr.

Methods (by class)

• eeg_average(default): Default method for averaging EEG objects

• eeg_average(eeg_epochs): Create evoked data from eeg_epochsobjects

• eeg_average(eeg_evoked): average an eeg_evoked object over epochs.

• eeg_average(eeg_tfr): average an eeg_tfr object over epochs.

Author(s)

Matt Craddock [email protected]

Examples

eeg_average(demo_spatial)
eeg_average(demo_spatial, cols = "everything")

Description

Combine multiple eeg_epochs, eeg_data, or eeg_evoked objects into a single object. The function will check the participant_id entry in the epochs structure of each object to see if the objects come from a single participant or from multiple participants. If the data are from multiple participants, it will create an eeg_group object. For individual participants, it will check for duplicate epochs. For most objects, it will concatenate the objects if none are found. However, for eeg_data it will instead try to correct the epoch numbers. Check the details below for further advice.

Usage

eeg_combine(data, ...)

## S3 method for class 'list'
eeg_combine(data, ...)

## S3 method for class 'eeg_data'
eeg_combine(data, ..., check_timings = TRUE)

## S3 method for class 'eeg_epochs'
eeg_combine(data, ..., check_timings = TRUE)

## S3 method for class 'eeg_evoked'
eeg_combine(data, ...)

Arguments

Value

If all objects have the same participant_id, returns an object of the same class as the original input object. If the objects have different participant_id numbers, an object of both class eeg_group and the same class as the original input object.

Methods (by class)

• eeg_combine(list): Method for combining lists of eeg_data and eeg_epochs objects.

• eeg_combine(eeg_data): Method for combining eeg_data objects.

• eeg_combine(eeg_epochs): Method for combining eeg_epochs objects

• eeg_combine(eeg_evoked): Method for combining eeg_evoked objects

Combining eeg_data objects

Combining eeg_data is mainly intended to be used for combining multiple recordings from a single participant prior to subsequent epoching. Thus, check_timings defaults to true, and the function will change the epochs and timing structures of the resulting combined object to be as if it were a single recording. The objects will be combined in the input order, so ensure that the objects are input in chronological order.

Combining eeg_epochs objects

There are several scenarios where you might wish to combine eeg_epochs. For example, a user may have processed continuous data in smaller chunks reflecting short recording blocks before epoching. They then wish to combine these into a single object. In that case, the epoch numbering should reflect chronological ordering and needs to be corrected.

If check_timings == TRUE, the function will perform several checks before combining objects. First, it will check for duplicate epochs in the epochs structure of each object. If each object only has unique epochs, the objects will be combined without correction. Thus, combining across separate recordings or separate participants will not elicit correction. The user should ensure

If there are any duplicates (e.g. a participant has more than one epoch numbered one from the same recording), it will then check if there are any missing epochs. If there are, the new trial numbering cannot be automatically determined, so the objects cannot be combined without further manual intervention. If there are no missing epochs, it will then check if there is any decreases in epoch numbers across objects. If there are any, then the epoch numbers and timings for the objects will be adjusted.

Alternatively, the user may wish to combine eeg_epochs objects from different participants or from entirely different recording sessions of the same participant. In this case, no correction of timings or epoch numbers is desirable. check_timings == TRUE should detect this and skip correction, but can be explicitly set to FALSE.

Author(s)

Matt Craddock, [email protected]

Description

Implements a selection of Generalized Eigenvalue based decomposition methods for EEG signals. Intended for isolating oscillations at specified frequencies, decomposing channel-based data into components reflecting distinct or combinations of sources of oscillatory signals. Currently, spatio-spectral decomposition (Nikulin, Nolte, & Curio, 2011) and Rhythmic Entrainment Source Separation (Cohen & Gulbinate, 2017) are implemented. The key difference between the two is that the former returns the results of the data-derived spatial filters applied to the bandpass-filtered "signal" data, whereas the latter returns the results of the filters applied to the original, broadband data.

Usage

eeg_decompose(data, ...)

## S3 method for class 'eeg_epochs'
eeg_decompose(
  data,
  sig_range,
  noise_range,
  method = c("ssd", "ress"),
  verbose = TRUE,
  order = 2,
  ...
)

Arguments

Value

An eeg_ICA object.

Methods (by class)

• eeg_decompose(eeg_epochs): method for eeg_epochs objects

Author(s)

Matt Craddock [email protected]

References

Cohen, M. X., & Gulbinate, R. (2017). Rhythmic entrainment source separation: Optimizing analyses of neural responses to rhythmic sensory stimulation. NeuroImage, 147, 43-56. https://doi.org/10.1016/j.neuroimage.2016.11.036

Haufe, S., Dähne, S., & Nikulin, V. V. (2014). Dimensionality reduction for the analysis of brain oscillations. NeuroImage, 101, 583–597. https://doi.org/10.1016/j.neuroimage.2014.06.073

Nikulin, V. V., Nolte, G., & Curio, G. (2011). A novel method for reliable and fast extraction of neuronal EEG/MEG oscillations on the basis of spatio-spectral decomposition. NeuroImage, 55(4), 1528–1535. https://doi.org/10.1016/j.neuroimage.2011.01.057

See Also

Other decompositions: run_ICA()

Examples

# The default method is Spatio-Spectral Decomposition, which returns
# spatially and temporally filtered source timecourses.
 decomposed <-
   eeg_decompose(demo_epochs,
                 sig_range = c(9, 11),
                 noise_range = c(8, 12),
                 method = "ssd")
 plot_psd(decomposed)
 # We can plot the spatial filters using `topoplot()`
 topoplot(decomposed, 1:2)
 plot_timecourse(decomposed, 1)
# method = "ress" returns spatially but not temporally filtered timecourses.
 with_RESS <-
   eeg_decompose(demo_epochs,
                 sig_range = c(9, 11),
                 noise_range = c(8, 12),
                 method = "ress")
 plot_psd(with_RESS)
 # The topographical plots are identical to those using "ssd", as the
 # spatial filters are the same.
 topoplot(with_RESS, 1:2)
 plot_timecourse(with_RESS, 1)

Description

Performs low-pass anti-aliasing filtering and downsamples EEG data by a specified factor. This is a wrapper for decimate from the signal package. Note that this will also adjust the event table, moving events to the nearest time remaining after downsampling

Usage

eeg_downsample(data, ...)

## S3 method for class 'eeg_data'
eeg_downsample(data, q, ...)

## S3 method for class 'eeg_epochs'
eeg_downsample(data, q, ...)

Arguments

Methods (by class)

• eeg_downsample(eeg_data): Downsample eeg_data objects

• eeg_downsample(eeg_epochs): Downsample eeg_epochs objects

Author(s)

Matt Craddock [email protected]

Examples

eeg_downsample(demo_epochs, 2)

Description

Function to create an S3 object of class eeg_epochs.

Usage

eeg_epochs(
  data,
  srate,
  events = NULL,
  chan_info = NULL,
  timings = NULL,
  reference = NULL,
  epochs = NULL
)

Arguments

Author(s)

Matt Craddock [email protected]

Description

Perform IIR or FIR filtering on input EEG data of class eeg_data or eeg_epochs. WARNING: with epoched data, epoch boundaries are currently ignored, which can result in minor edge artifacts.

Usage

eeg_filter(data, ...)

## S3 method for class 'eeg_data'
eeg_filter(
  data,
  low_freq = NULL,
  high_freq = NULL,
  filter_order = "auto",
  trans_bw = "auto",
  method = "fir",
  window = "hamming",
  demean = TRUE,
  ...
)

## S3 method for class 'eeg_epochs'
eeg_filter(
  data,
  low_freq = NULL,
  high_freq = NULL,
  filter_order = "auto",
  trans_bw = "auto",
  method = "fir",
  window = "hamming",
  demean = TRUE,
  ...
)

## S3 method for class 'eeg_group'
eeg_filter(
  data,
  low_freq = NULL,
  high_freq = NULL,
  filter_order = "auto",
  trans_bw = "auto",
  method = "fir",
  window = "hamming",
  demean = TRUE,
  ...
)

Arguments

Details

low_freq and high_freq are the low and high cutoff frequencies. Pass low freq or high freq alone to perform high-pass or low-pass filtering respectively. For band-pass or band-stop filters, pass both low_freq and high_freq.

If low_freq < high_freq, bandpass filtering is performed.

If low_freq > high_freq, bandstop filtering is performed.

Note that it is recommended to first zero-mean the signal using either channel means or by-channel epoch means.

The function allows parallelization using the future package, e.g. using plan(multisession)

Value

An object of the original class with signals filtered according to the user's specifications

FIR versus IIR filtering

Finite Impulse Response (FIR) filtering is performed using an overlap-add FFT method. Note that this only performs a single-pass; the data is shifted back in time by the group delay of the filter to compensate for the phase delay imposed by the linear filtering process. Infinite Impulse Response (IIR) filtering is performed using a two-pass (once forwards, once reversed) method to correct for phase alignment. Note that the Butterworth filter designs used here can become numerically unstable with only a small increase in filter order. For most purposes, use FIR filters.

Examples

plot_psd(eeg_filter(demo_epochs, low_freq = 1, high_freq = 30))
plot_psd(eeg_filter(demo_epochs, low_freq = 12, high_freq = 8))
plot_psd(eeg_filter(demo_epochs, low_freq = 12, high_freq = 8, method = "iir"))

Description

Function to create an S3 object of class eeg_ICA.

Usage

eeg_ICA(
  mixing_matrix,
  unmixing_matrix,
  signals,
  timings,
  events,
  chan_info,
  srate,
  epochs,
  algorithm,
  contents
)

Arguments

Value

An object of class eeg_ICA.

Author(s)

Matt Craddock [email protected]

Description

Used to reference the EEG data to a specified electrode or electrodes. Defaults to average reference. When specific electrodes are used, they are removed from the data. Meta-data about the referencing scheme is held in the eeg_data structure.

Usage

eeg_reference(data, ...)

## Default S3 method:
eeg_reference(data, ...)

## S3 method for class 'eeg_data'
eeg_reference(
  data,
  ref_chans = "average",
  exclude = NULL,
  robust = FALSE,
  implicit_ref = NULL,
  verbose = TRUE,
  ...
)

## S3 method for class 'eeg_epochs'
eeg_reference(
  data,
  ref_chans = "average",
  exclude = NULL,
  robust = FALSE,
  implicit_ref = NULL,
  verbose = TRUE,
  ...
)

Arguments

Value

object of class eeg_data, re-referenced as requested.

Methods (by class)

• eeg_reference(default): Default method

• eeg_reference(eeg_data): Rereference objects of class eeg_data

• eeg_reference(eeg_epochs): Rereference objects of class eeg_epochs

Author(s)

Matt Craddock [email protected]

Examples

# demo_epochs is average referenced by default
demo_epochs
# Rereference it but exclude B5 from calculation of the average
eeg_reference(demo_epochs, exclude = "B5")
# Reference data using the median of the reference channels rather than the mean
eeg_reference(demo_epochs, robust = TRUE)

eeg_reference(demo_spatial)
eeg_reference(demo_spatial, ref_chans = "Fz")
eeg_reference(demo_spatial, implicit_ref = "LM")

Description

Calculate the timepoint-by-timepoint mean, standard deviation, standard error, or variance eeg_epochs objects.

Usage

eeg_summarise(data, ...)

## S3 method for class 'eeg_epochs'
eeg_summarise(
  data,
  statistic = c("sem", "mean", "sd", "var"),
  conditions = NULL,
  time_lim = NULL,
  ...
)

Arguments

Value

A tibble

Methods (by class)

• eeg_summarise(eeg_epochs): Calculate summary statistics for eeg_epochs objects

Examples

eeg_summarise(demo_spatial, statistic = "sem")

Description

Joins standard electrode locations to EEG data from eegUtils internal data.

Usage

electrode_locations(data, ...)

## S3 method for class 'data.frame'
electrode_locations(
  data,
  electrode = "electrode",
  drop = FALSE,
  montage = NULL,
  overwrite = TRUE,
  ...
)

## S3 method for class 'eeg_data'
electrode_locations(data, drop = FALSE, montage = NULL, overwrite = FALSE, ...)

## S3 method for class 'eeg_epochs'
electrode_locations(data, drop = FALSE, montage = NULL, overwrite = FALSE, ...)

## S3 method for class 'eeg_tfr'
electrode_locations(data, drop = FALSE, montage = NULL, overwrite = FALSE, ...)

Arguments

Details

The standard locations are from the 10-05 system derived by Oostenveld & Praamstra (2001). In addition, there are multiple specific montages for BioSemi systems included. These can be added using the montage parameter: "biosemi16", "biosemi32", biosemi64", "biosemi64alpha", "biosemi128", "biosemi160", "biosemi256"

Value

A tibble (or data.frame), or ggplot2 object if plot = TRUE.

Methods (by class)

• electrode_locations(data.frame): Adds standard locations to a data frame in long format

• electrode_locations(eeg_data): Adds standard locations to the chan_info field of an eeg_data object.

• electrode_locations(eeg_epochs): Adds standard locations to the chan_info field of an eeg_data object.

• electrode_locations(eeg_tfr): Adds standard locations to the chan_info field of an eeg_tfr object.

References

Oostenveld, R. & Praamstra, P. (2001). The five percent electrode system for high-resolution EEG and ERP measurements. Clinical Neurophysiology, 112, 4, 713-719

Examples

channels(demo_epochs)
electrode_locations(demo_epochs, overwrite = TRUE, montage = "biosemi64alpha")

Description

Creates epochs around specified event triggers. Requires data of class eeg_data. Where multiple events are specified, epochs will be created around each event.

Usage

epoch_data(data, ...)

## S3 method for class 'eeg_data'
epoch_data(
  data,
  events,
  time_lim = c(-1, 1),
  baseline = "none",
  epoch_labels = NULL,
  ...
)

Arguments

Value

Returns an epoched object of class eeg_epochs

Methods (by class)

• epoch_data(eeg_data): Epoch eeg_data objects

Author(s)

Matt Craddock [email protected]

Description

Create epochs from EEG data

Usage

## Default S3 method:
epoch_data(data, ...)

Arguments

Description

Calculate various statistics for each epoch in the data

Usage

epoch_stats(data, ...)

## S3 method for class 'eeg_epochs'
epoch_stats(data, ...)

Arguments

Methods (by class)

• epoch_stats(eeg_epochs): Calculate statistics for each epoch.

Author(s)

Matt Craddock [email protected]

Examples

epoch_stats(demo_epochs)

Description

Get or set the epochs structure of an eegUtils object.

Usage

epochs(data)

epochs(data) <- value

Arguments

Author(s)

Matt Craddock [email protected]

Examples

epochs(demo_spatial)

Description

Plot an ERP image from a single electrode. Uses a boxcar smooth over a series of trials in order to make across-trial patterns more apparent.

Usage

erp_image(data, ...)

## S3 method for class 'data.frame'
erp_image(
  data,
  electrode = "Cz",
  time_lim = NULL,
  smoothing = 10,
  clim = NULL,
  interpolate = FALSE,
  na.rm = TRUE,
  ...
)

## S3 method for class 'eeg_epochs'
erp_image(
  data,
  electrode = "Cz",
  time_lim = NULL,
  smoothing = 10,
  clim = NULL,
  interpolate = FALSE,
  na.rm = TRUE,
  ...
)

## S3 method for class 'eeg_ICA'
erp_image(
  data,
  component = "Comp001",
  smoothing = 10,
  clim = NULL,
  interpolate = FALSE,
  na.rm = TRUE,
  ...
)

## S3 method for class 'eeg_tfr'
erp_image(
  data,
  electrode = "Cz",
  time_lim = NULL,
  smoothing = 10,
  clim = NULL,
  interpolate = FALSE,
  freq_range = NULL,
  na.rm = TRUE,
  ...
)

Arguments

Value

A ggplot object

Methods (by class)

• erp_image(data.frame): Default function operates on normal data frames

• erp_image(eeg_epochs): Create an erp_image from eeg_epochs

• erp_image(eeg_ICA): Plot component image from eeg_ICA

• erp_image(eeg_tfr): Plot component image from eeg_tfr

Author(s)

Matt craddock [email protected]

Examples

erp_image(demo_epochs, electrode = "A31")
erp_image(demo_epochs, electrode = "A31", interpolate = TRUE)
erp_image(demo_epochs, electrode = "A31", smoothing = 5)
erp_image(compute_tfr(demo_epochs,
 foi = c(4, 30), n_cycles = 3, n_freq = 20, verbose = FALSE, keep_trials = TRUE),
 electrode = "A31", freq_range = c(8, 12))

Description

Create a plot showing the ERP at every channel as a single ERP image. By default, this attempts to find channel locations and rearrange the channels such that spatial patterns on the scalp are more discernible. It orders the rows from the most posterior electrode on the right hemisphere to the most anterior electrode on the left hemisphere, with midline electrodes in the middle. If no locations are found, it simply displays the data in its original order.

Usage

erp_raster(
  data,
  anat_order = TRUE,
  time_lim = NULL,
  clim = NULL,
  interpolate = FALSE
)

Arguments

Value

A ggplot object

Author(s)

Matt Craddock, [email protected]

Examples

library(ggplot2)
erp_raster(demo_epochs)
erp_raster(demo_epochs, interpolate = TRUE)
erp_raster(rm_baseline(demo_epochs, c(-.1, 0)), interpolate = TRUE)
erp_raster(demo_spatial) + facet_wrap(~epoch_labels)

Description

Creates a ggplot2 figure showing the ERP at each electrode, with each electrode placed according to its location on the scalp.

Usage

erp_scalp(data, ...)

## Default S3 method:
erp_scalp(
  data,
  electrode = "electrode",
  amplitude = "amplitude",
  time = "time",
  color = NULL,
  colour = NULL,
  size = 0.8,
  linewidth = 0.8,
  baseline = NULL,
  show_guide = TRUE,
  chan_info = NULL,
  montage = NULL,
  ...
)

Arguments

Value

Returns a ggplot2 plot object.

Methods (by class)

• erp_scalp(default): Plot an ERP scalp map

Author(s)

Matti Vuorre, [email protected]

Matt Craddock, [email protected]

See Also

interactive_scalp() for interactive plots of ERPs in a scalp-based layout.

Other scalp-based maps: interactive_scalp(), topoplot()

Examples

erp_scalp(demo_epochs, montage = "biosemi64alpha")

Description

Get or set the values in the events structure of an eegUtils object.

Usage

events(.data)

events(.data) <- value

## S3 replacement method for class 'eeg_epochs'
events(.data) <- value

## S3 replacement method for class 'eeg_data'
events(.data) <- value

Arguments

Author(s)

Matt Craddock [email protected]

See Also

Other event handlers: list_epochs(), list_events(), tag_events()

Examples

events(demo_epochs)
events(demo_epochs) <- mutate(events(demo_epochs),
 sf = dplyr::case_when(
         event_type %% 2 == 0 ~ "HSF",
         event_type %% 2 == 1 ~ "LSF",
 ))
events(demo_epochs)

Description

Export continuous EEG data in Brain Vision Analyzer format. This is one of the recommended formats for BIDS https://bids-specification.readthedocs.io/en/stable/04-modality-specific-files/03-electroencephalography.html

Usage

export_bva(.data, filename, orientation, verbose = TRUE)

## S3 method for class 'eeg_data'
export_bva(.data, filename, orientation = "VECTORIZED", verbose = TRUE)

Arguments

Methods (by class)

• export_bva(eeg_data): Method for eeg_data

Description

Fits a linear model to each timepoint separately for each electrode.

Usage

fit_glm(formula, data, ...)

## S3 method for class 'eeg_epochs'
fit_glm(formula, data, baseline = NULL, ...)

Arguments

Methods (by class)

• fit_glm(eeg_epochs): GLM fitting for eeg_epochs

Notes On Usage

The fit_glm function will fit a linear model to each timepoint for each electrode in the input dataset.

The formula is a standard R formula. Specify only the right-hand side of the formula i.e. any predictors.

The function allows flexible fitting of a baseline covariate, recognising the term baseline in the specified formula.

Author(s)

Matt Craddock, [email protected]

Examples

fit_glm(~epoch_labels, demo_spatial)
fit_glm(~epoch_labels + baseline, demo_spatial, baseline = c(-.1, 0))

Description

geom_topo() creates a topographical plot as a ggplot2 object. This function automatically combines a number of distinct geom_* and stat_* functions to create a default topographical scalp map. Since geom_raster does not allow unevenly spaced grids, the function creates an interpolated surface.

Usage

geom_topo(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  show.legend = NA,
  na.rm = TRUE,
  inherit.aes = TRUE,
  interpolate = FALSE,
  interp_limit = "skirt",
  chan_markers = "point",
  chan_size = rel(2),
  head_size = rel(1.5),
  r = NULL,
  grid_res = 200,
  method = "biharmonic",
  bins = 6,
  ...
)

Arguments

See Also

Other topoplot functions: stat_scalpcontours(), stat_scalpmap()

Examples

library(ggplot2)
ggplot(demo_epochs, aes(x = x, y = y, fill = amplitude, z = amplitude)) + geom_topo()

Description

These functions are used to query and set the participant_id and recording fields of an epochs structure within any eegUtils object. Note that the two ⁠set_*⁠ functions do not operate on eeg_group objects.

Usage

get_participant_id(data)

get_recording(data)

set_participant_id(data, participant_id)

set_recording(data, recording)

Arguments

Value

• get_participant_id() returns a character vector containing the participant_id

• get_recording() returns a character vector containing the recording from values of recording from the eegUtils object

• set_participant_id() returns the full eegUtils object with the participant_id field modified in the epochs structure

• set_recording() returns the full eegUtilsobject with the recording field modified in the epochs structure

Author(s)

Matt Craddock [email protected]

Examples

get_participant_id(demo_epochs)
get_recording(demo_epochs)
set_participant_id(demo_epochs, "002")
set_recording(demo_epochs, "test_recording")

Description

Calculate and return an interpolated scalpmap from a data.frame or eeg_epochs object. This provides the basis for a raster plot, as used to create topographical plots.

Usage

get_scalpmap(data, ...)

## S3 method for class 'data.frame'
get_scalpmap(
  data,
  method = "biharmonic",
  grid_res = 100,
  interp_limit = "skirt",
  quantity = "amplitude",
  facets = NULL,
  r = 95,
  k = -1,
  ...
)

## S3 method for class 'eeg_epochs'
get_scalpmap(
  data,
  method = "biharmonic",
  grid_res = 100,
  interp_limit = "skirt",
  quantity = "amplitude",
  facets = NULL,
  r = 95,
  ...
)

Arguments

Value

A tibble with the columns x, y, fill

Methods (by class)

• get_scalpmap(data.frame): Get scalpmap from a data.frame

• get_scalpmap(eeg_epochs): Get scalpmap from an eeg_epochs object.

Examples

head(get_scalpmap(demo_epochs))

Description

Currently only ASA .elc format with Cartesian x-y-z coordinates is supported.

Usage

import_chans(file_name, format = "spherical", file_format = "auto")

Arguments

Value

A tibble containing electrode names and locations in several different coordinate systems.

Author(s)

Matt Craddock [email protected]

Description

ERPLAB is a toolbox for Event Related Potential analysis associated with EEGLAB. It exports files in Matlab v6.5 format, either with an .erp or .mat extension. Note that ERPLAB files can contain data from multiple subjects, individual subjects, or averaged over multiple subjects. The files do not distinguish between these possibilities, so users will need to apply their own knowledge of the contents to import them correctly.

Usage

import_erplab(
  file_name,
  df_out = FALSE,
  participant_id = NULL,
  recording = NULL
)

Arguments

Value

An object of class eeg_epochs or a data.frame.

Author(s)

Matt Craddock [email protected]

Examples

## Not run: import_set("your_data.set")

Description

Fieldtrip is a Matlab package for EEG/MEG processing and analysis.

Usage

import_ft(file_name, participant_id = NULL, recording = NULL, verbose = TRUE)

Arguments

Value

An object of class eeg_data, eeg_epochs, or eeg_tfr, depending on the type of input data.

Author(s)

Matt Craddock [email protected]

Examples

## Not run: import_ft("fieldtrip_test.mat")

Description

Currently BDF/EDF, 32-bit .CNT, and Brain Vision Analyzer files are supported. Filetype is determined by the file extension.The edfReader package is used to load BDF/EDF files, whereas custom code is used for .CNT and BVA files. The function creates an eeg_data structure for subsequent use.

Usage

import_raw(
  file_name,
  file_path = NULL,
  recording = NULL,
  participant_id = NA,
  fast_bdf = TRUE
)

Arguments

Value

An object of class eeg_data

Author(s)

Matt Craddock, [email protected]

Examples

## Not run: 
import_raw("test_bdf.bdf")

## End(Not run)

Description

Load EEGLAB .set files and convert them to eeg_epochs objects. Supports import of files saved in either Matlab v6.5 or Matlab v7.3 formats. Currently, any ICA weights or decompositions are discarded.

Usage

import_set(
  file_name,
  df_out = FALSE,
  participant_id = NULL,
  recording = NULL,
  drop_custom = FALSE,
  verbose = TRUE
)

Arguments

Value

An object of class eeg_epochs

Author(s)

Matt Craddock [email protected]

Examples

## Not run: import_set("your_data.set")

Description

Launches a Shiny Gadget for an interactive version of erp_scalp, allowing clicking of individual electrodes to plot them in a separate panel. In that panel, they can be averaged over or plotted as individual electrodes.

Usage

interactive_scalp(data, ...)

## S3 method for class 'eeg_epochs'
interactive_scalp(data, colour = NULL, baseline = NULL, montage = NULL, ...)

Arguments

Methods (by class)

• interactive_scalp(eeg_epochs): Method for eeg_epochs objects

Author(s)

Matt Craddock, [email protected]

See Also

erp_scalp() for non-interactive plots of ERPs in a scalp-based layout.

Other scalp-based maps: erp_scalp(), topoplot()

Description

Interpolate EEG channels using a spherical spline (Perrin et al., 1989; 1990). The data must have channel locations attached.

Usage

interp_elecs(data, bad_elecs, ...)

## S3 method for class 'eeg_data'
interp_elecs(data, bad_elecs, ...)

Arguments

Methods (by class)

• interp_elecs(eeg_data): Interpolate EEG channel(s)

Author(s)

Matt Craddock [email protected]

References

• Perrin, F., Pernier, J., Bertrand, O., & Echallier, J. F. (1989). Spherical splines for scalp potential and current density mapping. Electroencephalography and Clinical Neurophysiology, 72, 184-187

• Perrin, F., Pernier, J., Bertrand, O., & Echallier, J. F. (1990). Corrigenda EEG 02274. Electroencephalography and Clinical Neurophysiology, 76, 565

Description

Check if object is of class eeg_epochs.

Usage

is.eeg_epochs(x)

Arguments

Author(s)

Matt Craddock [email protected]

Description

Check if object is of class eeg_evoked

Usage

is.eeg_evoked(x)

Arguments

Author(s)

Matt Craddock [email protected]

Description

Check if object is of class eeg_group

Usage

is.eeg_group(x)

Arguments

Description

Check if object is of class eeg_ICA

Usage

is.eeg_ICA(x)

Arguments

Author(s)

Matt Craddock [email protected]

Description

Check if object is of class eeg_stats

Usage

is.eeg_stats(x)

Arguments

Description

Check if object is of class eeg_tfr

Usage

is.eeg_tfr(x)

Arguments

Author(s)

Matt Craddock [email protected]

Description

List trigger types and any labels found in an eeg_epochs object.

Usage

list_epochs(data, ...)

## S3 method for class 'eeg_epochs'
list_epochs(data, ...)

## S3 method for class 'eeg_ICA'
list_epochs(data, ...)

Arguments

Methods (by class)

• list_epochs(eeg_epochs): List epochs and associated events from eeg_epochs objects

• list_epochs(eeg_ICA): List epochs and associated events from eeg_ICA objects

Author(s)

Matt Craddock [email protected]

See Also

tag_events() and list_events()

Other event handlers: events(), list_events(), tag_events()

Description

List trigger types and any labels found in an eeg_data object.

Usage

list_events(data)

Arguments

Author(s)

Matt Craddock [email protected]

See Also

tag_events() and list_epochs()

Other event handlers: events(), list_epochs(), tag_events()

Examples

list_events(demo_epochs)

Description

Typically event-related potentials/fields, but could also be timecourses from frequency analyses for single frequencies. Output is a ggplot2 object. CIs not possible.

Usage

plot_butterfly(data, ...)

## Default S3 method:
plot_butterfly(
  data,
  time_lim = NULL,
  baseline = NULL,
  legend = TRUE,
  continuous = FALSE,
  browse_mode = FALSE,
  allow_facets = FALSE,
  ...
)

## S3 method for class 'eeg_evoked'
plot_butterfly(
  data,
  time_lim = NULL,
  baseline = NULL,
  legend = TRUE,
  continuous = FALSE,
  browse_mode = FALSE,
  allow_facets = FALSE,
  ...
)

## S3 method for class 'eeg_data'
plot_butterfly(
  data,
  time_lim = NULL,
  baseline = NULL,
  legend = TRUE,
  allow_facets = FALSE,
  browse_mode = FALSE,
  ...
)

## S3 method for class 'eeg_epochs'
plot_butterfly(
  data,
  time_lim = NULL,
  baseline = NULL,
  legend = TRUE,
  allow_facets = FALSE,
  browse_mode = FALSE,
  ...
)

## S3 method for class 'eeg_stats'
plot_butterfly(
  data,
  time_lim = NULL,
  baseline = NULL,
  legend = TRUE,
  allow_facets = FALSE,
  browse_mode = FALSE,
  quantity = "statistic",
  ...
)

## S3 method for class 'eeg_lm'
plot_butterfly(
  data,
  time_lim = NULL,
  baseline = NULL,
  legend = TRUE,
  allow_facets = FALSE,
  browse_mode = FALSE,
  quantity = "coefficients",
  ...
)

Arguments

Value

ggplot2 object showing ERPs for all electrodes overlaid on a single plot.

Methods (by class)

• plot_butterfly(default): Default plot_butterfly method for data.frames, eeg_data

• plot_butterfly(eeg_evoked): Plot butterfly for eeg_evoked objects

• plot_butterfly(eeg_data): Create butterfly plot for eeg_data objects

• plot_butterfly(eeg_epochs): Create butterfly plot for eeg_epochs objects

• plot_butterfly(eeg_stats): Create butterfly plot for eeg_stats objects

• plot_butterfly(eeg_lm): Create butterfly plot for eeg_lm objects

Notes on ggplot2 facetting

In order for ggplot2 facetting to work, the data has to be plotted using stat_summary() rather than geom_line(), so that the plots can still be made when not all categorical variables are reflected in the facets. e.g. if there are two variables with two levels each, but you want to average over one of those variables, stat_summary() is required. However, stat_summary() can be extremely slow with a large number of timepoints, electrodes, and epochs.

Author(s)

Matt Craddock, [email protected]

Examples

plot_butterfly(demo_epochs)
plot_butterfly(demo_epochs,
time_lim = c(-.1, .4),
legend = FALSE)

Description

Calculates the difference between the event-related potentials from two conditions and plots it.

Usage

plot_difference(data, ...)

## S3 method for class 'eeg_epochs'
plot_difference(
  data,
  electrode = NULL,
  time_lim = NULL,
  baseline = NULL,
  colour = NULL,
  color = NULL,
  mapping = NULL,
  conditions = "epoch_labels",
  ...
)

Arguments

Value

Returns a ggplot2 plot object

Methods (by class)

• plot_difference(eeg_epochs): Plot an ERP difference wave from an eeg_epochs object

Author(s)

Matt Craddock, [email protected]

Examples

plot_difference(demo_spatial, conditions = "epoch_labels", electrode = "P8")

Description

Produces either a 2D plot of the electrode locations or an interactive plot of electrode locations in 3D space.

Usage

plot_electrodes(data, interact = FALSE)

## Default S3 method:
plot_electrodes(data, interact = FALSE)

## S3 method for class 'eeg_data'
plot_electrodes(data, interact = FALSE)

## S3 method for class 'eeg_evoked'
plot_electrodes(data, interact = FALSE)

## S3 method for class 'eeg_tfr'
plot_electrodes(data, interact = FALSE)

Arguments

Value

A ggplot or plotly figure showing the locations of the electrodes

Methods (by class)

• plot_electrodes(default): generic plot electrodes function

• plot_electrodes(eeg_data): Plot electrodes associated with an eeg_data object.

• plot_electrodes(eeg_evoked): Plot electrodes associated with an eeg_evoked object.

• plot_electrodes(eeg_tfr): Plot electrodes associated with an eeg_data object.

Author(s)

Matt Craddock [email protected]

Examples

plot_electrodes(demo_epochs)

Description

Global Field Power (Lehmann & Skrandies, 1980) is a way to quantify the amount of activity in the overall electroencephalographic signal at a given timepoint. It corresponds to the spatial standard deviation.

Usage

plot_gfp(data, cols = NULL, keep_trials = FALSE)

Arguments

Author(s)

Matt Craddock [email protected]

Examples

plot_gfp(demo_spatial)
plot_gfp(demo_spatial, keep_trials = TRUE)
plot_gfp(demo_spatial, cols = "epoch_labels")
plot_gfp(demo_spatial, cols = "epoch_labels", keep_trials = TRUE)

Description

Calculate and plot the PSD for ⁠eeg_*⁠ objects. Output units are dB. The PSD is calculated using Welch's method.

Usage

plot_psd(data, freq_range = NULL, ...)

## S3 method for class 'eeg_epochs'
plot_psd(
  data,
  freq_range = NULL,
  n_fft = 256,
  seg_length = NULL,
  noverlap = NULL,
  demean = TRUE,
  keep_trials = TRUE,
  ...
)

## S3 method for class 'eeg_data'
plot_psd(
  data,
  freq_range = NULL,
  n_fft = 2048,
  noverlap = NULL,
  seg_length = NULL,
  ...
)

## S3 method for class 'eeg_ICA'
plot_psd(
  data,
  freq_range = NULL,
  components = NULL,
  seg_length = NULL,
  noverlap = NULL,
  n_fft = 256,
  ...
)

## S3 method for class 'data.frame'
plot_psd(data, freq_range = NULL, ...)

## S3 method for class 'eeg_evoked'
plot_psd(
  data,
  freq_range = NULL,
  n_fft = 256,
  seg_length = NULL,
  noverlap = NULL,
  keep_trials = TRUE,
  ...
)

## S3 method for class 'eeg_group'
plot_psd(
  data,
  freq_range = NULL,
  n_fft = 256,
  seg_length = NULL,
  noverlap = NULL,
  demean = TRUE,
  ...
)

Arguments

Details

Welch's method splits the data into multiple segments and then averages over those segments. For epoched data, Welch's FFT is calculated separately for each trial.

Specific parameters such as the number of FFT points and the amount of overlap between segments can be passed to Welch's FFT.

Value

A ggplot object.

Methods (by class)

• plot_psd(eeg_epochs): Plot PSD for eeg_epochs.

• plot_psd(eeg_data): Plot PSD for eeg_data.

• plot_psd(eeg_ICA): Plot PSD for eeg_ICA objects

• plot_psd(data.frame): Plot PSD for data.frames.

• plot_psd(eeg_evoked): Plot PSD for eeg_evoked objects

• plot_psd(eeg_group): Plot PSD for eeg_group objects is not currently supported

Author(s)

Matt Craddock, [email protected]

Examples

plot_psd(demo_epochs)
 plot_psd(demo_epochs, seg_length = 256)

Description

Creates a time-frequency plot of an eeg_tfr object. The plot has time on the x-axis and frequency on the y-axis. If no electrode is supplied, it will average over all electrodes.

Usage

plot_tfr(
  data,
  electrode = NULL,
  time_lim = NULL,
  freq_range = NULL,
  baseline_type = "none",
  baseline = NULL,
  fill_lims = NULL,
  interpolate = FALSE,
  na.rm = TRUE,
  fun.data = mean
)

Arguments

Details

Various different baseline options can be applied here (e.g. "db" for decibels, "pc" for percent change, "divide" for division; see rm_baseline for details).

Value

A ggplot object

Author(s)

Matt Craddock [email protected]

See Also

rm_baseline()

Description

Typically event-related potentials/fields, but could also be timecourses from frequency analyses for single frequencies. Averages over all submitted electrodes. For group data, plot_timecourse will average within-participants first, using weighted averaging where possible, then across participants using unweighted averaging. Output is a ggplot2 object.

Usage

plot_timecourse(data, ...)

## S3 method for class 'data.frame'
plot_timecourse(
  data,
  electrode = NULL,
  time_lim = NULL,
  add_CI = FALSE,
  baseline = NULL,
  colour = NULL,
  color = NULL,
  mapping = NULL,
  facets = NULL,
  ...
)

## S3 method for class 'eeg_evoked'
plot_timecourse(
  data,
  electrode = NULL,
  time_lim = NULL,
  add_CI = FALSE,
  baseline = NULL,
  colour = NULL,
  color = NULL,
  mapping = NULL,
  facets = NULL,
  ...
)

## S3 method for class 'eeg_ICA'
plot_timecourse(
  data,
  component = NULL,
  time_lim = NULL,
  add_CI = FALSE,
  baseline = NULL,
  colour = NULL,
  color = NULL,
  mapping = NULL,
  facets = NULL,
  ...
)

## S3 method for class 'eeg_epochs'
plot_timecourse(
  data,
  electrode = NULL,
  time_lim = NULL,
  add_CI = FALSE,
  baseline = NULL,
  colour = NULL,
  color = NULL,
  mapping = NULL,
  facets = NULL,
  ...
)

## S3 method for class 'eeg_group'
plot_timecourse(
  data,
  electrode = NULL,
  time_lim = NULL,
  add_CI = FALSE,
  baseline = NULL,
  colour = NULL,
  color = NULL,
  mapping = NULL,
  facets = NULL,
  ...
)

## S3 method for class 'eeg_tfr'
plot_timecourse(
  data,
  electrode = NULL,
  time_lim = NULL,
  add_CI = FALSE,
  baseline = NULL,
  colour = NULL,
  color = NULL,
  mapping = NULL,
  freq_range = NULL,
  type = "divide",
  ...
)

Arguments

Value

Returns a ggplot2 plot object

Methods (by class)

• plot_timecourse(data.frame): Plot a data.frame timecourse

• plot_timecourse(eeg_evoked): plot eeg_evoked timecourses

• plot_timecourse(eeg_ICA): Plot individual components from eeg_ICA components

• plot_timecourse(eeg_epochs): Plot timecourses from eeg_epochs objects.

• plot_timecourse(eeg_group): Plot timecourses from eeg_group objects.

• plot_timecourse(eeg_tfr): Plot timecourses from eeg_tfr objects.

Author(s)

Matt Craddock, [email protected]

Examples

library(ggplot2)
plot_timecourse(demo_epochs, "A29")
plot_timecourse(demo_epochs, "A29", baseline = c(-.1, 0))
plot_timecourse(demo_epochs, "A29", baseline = c(-.1, 0), add_CI = TRUE)
plot_timecourse(demo_spatial, "Oz", baseline = c(-.1, 0), mapping = aes(colour = epoch_labels))
plot_timecourse(demo_spatial, "Oz", baseline = c(-.1, 0), facets = ~epoch_labels)

Description

Print a basic summary of the contents of an eeg_data object

Usage

## S3 method for class 'eeg_data'
print(x, ...)

Arguments

Description

Print a basic summary of the contents of an eeg_epochs object

Usage

## S3 method for class 'eeg_epochs'
print(x, ...)

Arguments

Description

Print a basic summary of the contents of an eeg_epochs object

Usage

## S3 method for class 'eeg_evoked'
print(x, ...)

Arguments

Description

Print a basic summary of the contents of an eeg_group object

Usage

## S3 method for class 'eeg_group'
print(x, ...)

Arguments

Description

Print a basic summary of the contents of an eeg_epochs object

Usage

## S3 method for class 'eeg_ICA'
print(x, ...)

Arguments

Description

Print a basic summary of the contents of an eeg_lm object

Usage

## S3 method for class 'eeg_lm'
print(x, ...)

Arguments

Description

Print a basic summary of the contents of an eeg_stats object

Usage

## S3 method for class 'eeg_stats'
print(x, ...)

Arguments

Description

Print a basic summary of the contents of an eeg_tfr object

Usage

## S3 method for class 'eeg_tfr'
print(x, ...)

Arguments

Description

Print a basic summary of the contents of a tfr_average object

Usage

## S3 method for class 'tfr_average'
print(x, ...)

Arguments

Description

Used to correct data using the mean of a specified time period. For time-domain data, this will subtract the mean from all data. For eeg_tfr objects, a variety of methods are available, including subtraction, and conversion to "dB" change. With a data frame, it will search for "electrode" and "epoch" columns, and groups on these when found. An electrode column is always required; an epoch column is not. Note that baseline correction is always applied on single-trial basis. For baseline correction based on subtraction, this makes no difference compared to averaging first and then baseline correcting, but for divisive measures used with time-frequency data, this distinction can be very important, and can lead to counterintuitive results.

Usage

rm_baseline(data, time_lim = NULL, ...)

## S3 method for class 'eeg_data'
rm_baseline(data, time_lim = NULL, verbose = TRUE, ...)

## S3 method for class 'eeg_epochs'
rm_baseline(data, time_lim = NULL, verbose = TRUE, ...)

## S3 method for class 'data.frame'
rm_baseline(data, time_lim = NULL, verbose = TRUE, ...)

## S3 method for class 'eeg_tfr'
rm_baseline(data, time_lim = NULL, type = "divide", verbose = TRUE, ...)

## S3 method for class 'eeg_evoked'
rm_baseline(data, time_lim = NULL, verbose = TRUE, ...)

Arguments

Value

An eegUtils object or a data.frame, depending on the input.

Methods (by class)

• rm_baseline(eeg_data): remove baseline from continuous eeg_data

• rm_baseline(eeg_epochs): Remove baseline from eeg_epochs

• rm_baseline(data.frame): Legacy method for data.frames

• rm_baseline(eeg_tfr): Method for eeg_tfr objects

• rm_baseline(eeg_evoked): Method for eeg_evoked objects

Author(s)

Matt Craddock [email protected]

Examples

rm_baseline(demo_epochs)
rm_baseline(demo_epochs, c(-.1, 0))

Description

On import, channel locations may be rotated (e.g. Fpz pointing towards ears.)

Usage

rotate_angle(chan_info, degrees)

Arguments

Value

A tibble()

Examples

plot_electrodes(demo_epochs)
channels(demo_epochs) <- rotate_angle(channels(demo_epochs), 90)
plot_electrodes(demo_epochs)

rotate_angle(channels(demo_epochs), 90)

Description

Performs Independent Component Analysis for electroencephalographic data. Currently only available with on epoched data. Implements three different methods of ICA - 'fastica', 'extended Infomax', and 'Second-Order Blind Identification (SOBI)'. The resulting eeg_ICA objects can be used largely like eeg_epochs objects.

Usage

run_ICA(data, ...)

## S3 method for class 'eeg_epochs'
run_ICA(
  data,
  method = "sobi",
  maxit = 1000,
  tol = 1e-06,
  pca = NULL,
  centre = TRUE,
  alg = "gradient",
  rateanneal = c(60, 0.9),
  rate = 0.1,
  verbose = TRUE,
  return = c("full", "weights"),
  ...
)

Arguments

Value

An eeg_ICA object containing an ICA decomposition

Methods (by class)

• run_ICA(eeg_epochs): Run ICA on an eeg_epochs object

Notes on ICA usage

It is recommended to mean-centre your data appropriately before running ICA. The implementations of FASTICA and extended-Infomax from the ica package, and of SOBI ICA have this as an option which is enabled by default, while the implementation of FASTICA in the fICA package enforces mean-centring of the columns of the data. With epoched data, it is recommended to centre each epoch on zero, rather than centre on the overall channel mean. This can be achieved with the rm_baseline() function. SOBI ICA will do this automatically, whereas the other ICA implementations will centre on the channel means, not the epoch means.

In addition, PCA will be required if the data is not full rank. This is typical when using average reference, when the data rank will be n_electrodes - 1.

Author(s)

Matt Craddock [email protected]

See Also

Other decompositions: eeg_decompose()

Examples

sobi_demo <-
  run_ICA(demo_epochs,
          pca = 10)
 sobi_demo
 # We can plot the resulting spatial filters using `topoplot()`
 topoplot(sobi_demo, 1:2)
 ## Not run:  view_ica(sobi_demo)

Description

This is a generic function for selection of electrodes from an EEG dataset.

Usage

select_elecs(data, ...)

## Default S3 method:
select_elecs(data, electrode = NULL, keep = TRUE, ...)

## S3 method for class 'eeg_data'
select_elecs(data, electrode, keep = TRUE, df_out = FALSE, ...)

## S3 method for class 'eeg_evoked'
select_elecs(data, electrode = NULL, keep = TRUE, df_out = FALSE, ...)

## S3 method for class 'eeg_ICA'
select_elecs(data, component, keep = TRUE, df_out = FALSE, ...)

## S3 method for class 'eeg_tfr'
select_elecs(data, electrode, keep = TRUE, df_out = FALSE, ...)

Arguments

Value

Data frame with only data from the chosen electrodes

eeg_data object with selected electrodes removed/kept.

Methods (by class)

• select_elecs(default): Select electrodes from a generic data frame.

• select_elecs(eeg_data): Select electrodes from a eeg_data object.

• select_elecs(eeg_evoked): Select electrode from an eeg_evoked object

• select_elecs(eeg_ICA): Select components from eeg_ICA objects.

• select_elecs(eeg_tfr): Select electrodes from eeg_tfr objects.

Author(s)

Matt Craddock, [email protected]

See Also

select_times() and select_epochs()

Other Data selection functions: select_times()

Examples

names(demo_epochs$signals)
keep_A5 <- select_elecs(demo_epochs, electrode = "A5")
remove_A5 <- select_elecs(demo_epochs, electrode = "A5", keep = FALSE)

select_elecs(demo_epochs, c("A21", "A29"))

Description

This is a generic function for selecting epochs from an epoched data set.

Usage

select_epochs(data, ...)

## Default S3 method:
select_epochs(data, ...)

## S3 method for class 'eeg_epochs'
select_epochs(
  data,
  epoch_events = NULL,
  epoch_no = NULL,
  keep = TRUE,
  df_out = FALSE,
  ...
)

## S3 method for class 'eeg_ICA'
select_epochs(
  data,
  epoch_events = NULL,
  epoch_no = NULL,
  keep = TRUE,
  df_out = FALSE,
  ...
)

## S3 method for class 'eeg_tfr'
select_epochs(
  data,
  epoch_events = NULL,
  epoch_no = NULL,
  keep = TRUE,
  df_out = FALSE,
  ...
)

Arguments

Methods (by class)

• select_epochs(default): Select from generic object

• select_epochs(eeg_epochs): Selection of epochs from eeg_epochs objects.

• select_epochs(eeg_ICA): Selection of epochs from eeg_ICA objects.

• select_epochs(eeg_tfr): Selection of epochs from eeg_tfr objects.

Author(s)

Matt Craddock, [email protected]

See Also

select_times() and select_elecs()