Package 'PhysioEEG'

Description

Computes the dispersion entropy (DispEn) of a one-dimensional signal (Rostaghi & Azami, 2016) – a fast, robust symbolic-dynamics complexity measure. Unlike the amplitude-histogram entropies (renyiEntropy, tsallisEntropy) and the ordinal permutation entropy, DispEn maps the signal to c amplitude classes through the normal cumulative distribution function (NCDF), forms embedding vectors of length dimension (the dispersion patterns), and takes the Shannon entropy of the pattern distribution, normalized by $\ln(c^{m})$. The NCDF mapping makes it insensitive to outliers and much cheaper than sample entropy, with no threshold-crossing boundary effects. Set reverse = TRUE to return the reverse dispersion entropy (RDEn), the mean-square deviation of the pattern distribution from uniformity (larger = more regular / less complex).

Usage

dispersionEntropy(x, c = 6L, dimension = 3L, delay = 1L, reverse = FALSE)

Arguments

Details

This implementation reproduces NeuroKit2's entropy_dispersion bit-for-bit, including its normalization convention (a base-2 Shannon term divided by the natural-log $\ln(c^{m})$, so DispEn ranges in $[0, 1/\ln 2]$).

Value

A single numeric value: the dispersion entropy (or, if reverse = TRUE, the reverse dispersion entropy).

References

Rostaghi, M., & Azami, H. (2016). "Dispersion entropy: A measure for time-series analysis." IEEE Signal Processing Letters, 23(5), 610–614. doi:10.1109/LSP.2016.2542881

See Also

renyiEntropy, tsallisEntropy, svdEntropy, petrosianFD.

Examples

set.seed(1)
dispersionEntropy(rnorm(1000))                 # DispEn (c = 6, m = 3)
dispersionEntropy(rnorm(1000), reverse = TRUE) # reverse dispersion entropy

Description

Separates each channel's power spectrum into an aperiodic (1/f) component and periodic (oscillatory) peaks, following the specparam / FOOOF model (Donoghue et al. 2020). The aperiodic exponent is a widely used index of the excitation/inhibition balance and cortical state. Delegates the fit to PhysioAnalysis::specparam().

Usage

eegAperiodic(
  pe,
  freq_range = c(1, 45),
  aperiodic_mode = c("fixed", "knee"),
  max_n_peaks = 6L,
  peak_width_limits = c(1, 12),
  min_peak_height = 0.05,
  peak_threshold = 2,
  assay_name = NULL
)

Arguments

Value

An eeg_aperiodic object: a list with aperiodic (per-channel data frame: channel, exponent, offset, optionally knee, r_squared, error), peaks (per-channel CF/PW/BW), exponent (a named per-channel vector, e.g. for eegPlotTopomap()), and the underlying specparam_result.

References

Donoghue et al. 2020, Nat Neurosci (specparam / FOOOF).

See Also

eegQEEG(), eegComplexity()

Examples

if (requireNamespace("PhysioAnalysis", quietly = TRUE)) {
  pe <- make_eeg(n_time = 2500, n_channels = 8, sr = 250)
  ap <- eegAperiodic(pe, freq_range = c(2, 40))
  ap$aperiodic          # per-channel exponent / offset
}

Description

Identifies and removes epochs contaminated by artifacts from 3D epoched EEG data. Supports multiple detection criteria: amplitude threshold, gradient (point-to-point voltage change), and joint probability.

Usage

eegArtifactReject(
  x,
  method = c("threshold", "gradient", "joint_probability"),
  threshold_uv = 100,
  gradient_uv_ms = 50,
  jp_threshold = 3,
  assay_name = NULL,
  output_assay = "clean"
)

Arguments

Value

A PhysioExperiment object with clean epochs in the specified output assay. Artifact log stored in metadata(x)$artifact_log.

Examples

pe <- make_eeg(n_time = 10000, n_channels = 19, sr = 500)
events <- data.frame(onset_sec = c(1, 3, 5, 7, 9))
pe_ep <- eegEpoch(pe, events, limits = c(-0.2, 0.8))
pe_clean <- eegArtifactReject(pe_ep, method = "threshold",
                               threshold_uv = 100, assay_name = "epoched")

Description

Computes frontal alpha asymmetry indices from paired electrode sites. For each pair (right, left), band power is computed via FFT and the asymmetry index is calculated as log(power_right) - log(power_left). Positive values indicate greater right-hemisphere alpha (typically associated with greater left-hemisphere cortical activity).

Usage

eegAsymmetry(x, pairs = NULL, band = c(8, 13), assay_name = NULL)

Arguments

Value

A data.frame with columns:

pair

Character label for the electrode pair.

left_channel

Character name of the left electrode.

right_channel

Character name of the right electrode.

left_power

Numeric band power for the left electrode.

right_power

Numeric band power for the right electrode.

asymmetry_index

Numeric asymmetry: log(right) - log(left).

References

Nuwer, M. R., et al. (1999). IFCN standards for digital recording of clinical EEG. Electroencephalography and Clinical Neurophysiology, 106(3), 259-261.

See Also

eegSpikeDetect(), eegQEEG(), eegSlowing()

Examples

pe <- make_eeg(n_time = 5000, n_channels = 19, sr = 500)
asym <- eegAsymmetry(pe)
print(asym)

Description

Implements the autoreject algorithm (Jas et al. 2017) for epoched EEG. Per-channel peak-to-peak rejection thresholds are chosen by cross-validation, then each epoch is kept, repaired by interpolating its worst bad channels, or dropped, according to two hyperparameters: consensus (the fraction of bad channels above which an epoch is dropped) and n_interpolate (the number of worst bad channels to interpolate in a repaired epoch). Either hyperparameter is chosen by cross-validation when not supplied. Bad channels are repaired with spherical-spline interpolation (the same weights used by eegInterpolate()), so electrode positions must be present (run eegMontage() first).

Usage

eegAutoReject(
  x,
  consensus = NULL,
  n_interpolate = NULL,
  cv_folds = 5L,
  thresh_range = NULL,
  n_thresh = 20L,
  assay_name = "epoched",
  output_assay = "autoreject_clean"
)

Arguments

Details

The cross-validation objective, at every stage, is the root-mean-square error between the mean of the good/cleaned training epochs and the median of the held-out test epochs - the criterion introduced by autoreject.

Value

The PhysioExperiment with cleaned 3D epoched data in metadata(x)[[output_assay]] (dropped epochs removed, repaired epochs interpolated) and a rejection log in metadata(x)$autoreject: the per-channel thresholds, chosen consensus and n_interpolate, the epoch-by-channel bad_matrix, the interpolated channel-epochs, and the dropped_epochs. The step is recorded in provenance.

References

Jas, M., Engemann, D. A., Bekhti, Y., Raimondo, F., & Gramfort, A. (2017). Autoreject: Automated artifact rejection for MEG and EEG data. NeuroImage, 159, 417-429.

See Also

eegArtifactReject(), eegInterpolate(), eegEpoch(), eegMontage()

Examples

pe <- make_eeg_erp(n_epochs = 40, n_channels = 19, sr = 250)
pe <- eegMontage(pe, system = "10-20")
pe <- eegAutoReject(pe, assay_name = "raw")
dim(S4Vectors::metadata(pe)$autoreject$bad_matrix)

Description

Identifies bad (noisy, flat, or poorly correlated) EEG channels using multiple automated criteria. Channels flagged as bad can subsequently be interpolated using eegInterpolate.

Usage

eegBadChannels(
  x,
  method = c("all", "flat", "noise", "correlation"),
  flat_threshold = 1e-06,
  noise_threshold = 4,
  corr_threshold = 0.4,
  assay_name = NULL
)

Arguments

Value

A data.frame with columns: channel (label), is_bad (logical), reason (character description), score (numeric metric value).

Examples

pe <- make_eeg(n_time = 5000, n_channels = 19, sr = 500)
bad_df <- eegBadChannels(pe)
bad_labels <- bad_df$channel[bad_df$is_bad]

Description

Classifies BCI features using Linear Discriminant Analysis (LDA) or shrinkage LDA. Implements Fisher's LDA with optional Ledoit-Wolf shrinkage regularization for robust classification with high-dimensional or small-sample data. Optionally performs k-fold cross-validation.

Usage

eegBCIclassify(
  x,
  features = NULL,
  labels,
  method = c("lda", "shrinkage_lda"),
  cv_folds = NULL,
  assay_name = NULL
)

Arguments

Value

A data.frame with columns: trial, predicted_class, confidence, and true_class. When cv_folds is not NULL, predictions are out-of-fold and attr(result, "cv_accuracy") contains the cross-validated accuracy. The trained LDA model (on all data) is stored in metadata(x)$bci_model, containing weights, threshold, classes, method, and class_means.

References

Blankertz, B., et al. (2008). Optimizing spatial filters for robust EEG single-trial analysis. IEEE Signal Processing Magazine, 25(1), 41-56.

See Also

eegCSP(), eegBCIfeatures(), eegMotorImagery()

Examples

pe <- make_eeg_bci(n_trials = 20, n_channels = 8, sr = 256)
labels <- S4Vectors::metadata(pe)$labels
features <- eegBCIfeatures(pe, method = "bandpower")
result <- eegBCIclassify(pe, features = features, labels = labels, method = "lda")

# With 5-fold cross-validation
result_cv <- eegBCIclassify(pe, features = features, labels = labels,
                            method = "lda", cv_folds = 5)
attr(result_cv, "cv_accuracy")

Description

Extracts features from epoched EEG data for Brain-Computer Interface classification. Supports band power, CSP, and Riemannian geometry methods.

Usage

eegBCIfeatures(
  x,
  method = c("bandpower", "csp", "riemannian"),
  labels = NULL,
  bands = NULL,
  assay_name = NULL
)

Arguments

Value

A numeric matrix with n_trials rows and feature columns. Number of columns depends on method:

• "bandpower": n_channels * n_bands

• "csp": 2 * n_filters (default: 6)

• "riemannian": n_channels * (n_channels + 1) / 2

References

Blankertz, B., et al. (2008). Optimizing spatial filters for robust EEG single-trial analysis. IEEE Signal Processing Magazine, 25(1), 41-56.

See Also

eegCSP(), eegMotorImagery(), eegBCIclassify()

Examples

pe <- make_eeg_bci(n_trials = 20, n_channels = 8, sr = 256)
features <- eegBCIfeatures(pe, method = "bandpower")

Description

Applies spatial filtering (beamforming) to localize neural source power. Linearly Constrained Minimum Variance (LCMV) beamformer operates in the time domain. Dynamic Imaging of Coherent Sources (DICS) operates in the frequency domain.

Usage

eegBeamformer(
  x,
  forward_model,
  method = c("lcmv", "dics"),
  freq_range = NULL,
  assay_name = NULL,
  output_assay = "beamformer"
)

Arguments

Value

Modified PhysioExperiment with source power stored in output_assay as a matrix with one column named "power" (n_sources rows). Each value represents the estimated source power at the corresponding dipole location. Plotting metadata, including source positions, the output name, method, and coordinate provenance, is stored in metadata(x)$beamformer_info.

References

Pascual-Marqui, R. D. (2002). Standardized low-resolution brain electromagnetic tomography (sLORETA). Methods and Findings in Experimental and Clinical Pharmacology, 24(Suppl D), 5-12.

Van Veen, B. D., et al. (1997). Localization of brain electrical activity via linearly constrained minimum variance spatial filtering. IEEE Transactions on Biomedical Engineering, 44(9), 867-880.

See Also

eegForwardModel(), eegSourceEstimate(), eegSourcePower(), eegPlotGlassBrain()

Examples

pe <- make_eeg(n_time = 1000, n_channels = 19, sr = 250)
fm <- eegForwardModel(pe, method = "spherical", n_sources = 50)
pe <- eegBeamformer(pe, fm, method = "lcmv")

Description

Quantifies left/right spectral asymmetry across hemispheric electrode pairs, a quantitative-EEG stroke marker (van Putten 2007; Sheorajpanday et al. 2011). The global bsi is the spectrum-averaged absolute relative difference between summed right- and left-hemisphere power, bounded from 0 (symmetric) to 1 (one hemisphere silent). The pairwise-derived pdbsi averages the same relative difference per hemispheric pair; with directed = TRUE it keeps the sign (positive = right-dominant). Both are returned as reliability-characterised physioBiomarker objects with provenance and, for the global BSI, a normative reference range.

Usage

eegBSI(
  x,
  pairs = NULL,
  band = c(1, 25),
  directed = FALSE,
  method = "welch",
  age = NULL,
  montage = NULL,
  reliability = list(icc = NA_real_, sem = NA_real_),
  assay_name = NULL
)

Arguments

Value

A named list with two PhysioBiomarker objects: bsi (global, from 0 to 1) and pdbsi (pairwise-derived, signed when directed = TRUE).

References

van Putten, M. J. A. M. (2007). The revised brain symmetry index. Clinical Neurophysiology, 118(11), 2362-2367.

Sheorajpanday, R. V. A., et al. (2011). Quantitative EEG in ischemic stroke: correlation with functional status after 6 months. Clinical Neurophysiology, 122(5), 874-883.

See Also

eegDAR(), eegAsymmetry(), PhysioExperiment::physioBiomarker()

Examples

pe <- make_eeg(n_time = 5000, n_channels = 19, sr = 250)
res <- eegBSI(pe, age = 60)
res$bsi

Description

Computes magnitude-squared coherence (MSC) or imaginary part of coherency between all EEG channel pairs using Welch's method. The signal is segmented into overlapping windows, each windowed with a Hanning function, and the cross-spectral density is averaged across windows.

Usage

eegCoherence(
  x,
  method = c("coherence", "imaginary"),
  window_sec = 2,
  overlap = 0.5,
  band = c(8, 13),
  assay_name = NULL
)

Arguments

Details

Magnitude-squared coherence is defined as:

$MSC(f) = |S_{xy}(f)|^2 / (S_{xx}(f) \cdot S_{yy}(f))$

Imaginary coherence uses the imaginary part of coherency to reduce volume conduction artifacts:

$ICoh(f) = |Im(S_{xy}(f) / \sqrt{S_{xx}(f) \cdot S_{yy}(f)})|$

Value

The input PhysioExperiment with connectivity results stored in metadata(x)$connectivity, a list containing:

matrix

Numeric n_channels x n_channels matrix of band-averaged coherence values.

method

Character string indicating the method used.

band

Numeric vector of the frequency band used.

freqs

Numeric vector of frequency bins.

spectra

3D array (n_freqs x n_channels x n_channels) of frequency-resolved coherence values.

References

Lachaux, J. P., et al. (1999). Measuring phase synchrony in brain signals. Human Brain Mapping, 8(4), 194-208.

See Also

eegPLV(), eegWPLI(), eegConnectivityMatrix(), eegPlotConnectivity()

Examples

pe <- make_eeg(n_time = 5000, n_channels = 4, sr = 500)
pe <- eegCoherence(pe, method = "coherence", band = c(8, 13))
coh_matrix <- S4Vectors::metadata(pe)$connectivity$matrix

Description

Computes phase-amplitude coupling over a grid of phase and amplitude frequencies for one EEG channel, yielding a comodulogram whose peak locates the dominant coupling. Delegates to PhysioCrossModal::comodulogram().

Usage

eegComodulogram(
  pe,
  channel = 1L,
  phase_freqs = seq(2, 14, by = 2),
  amp_freqs = seq(20, 100, by = 10),
  method = c("tort", "canolty", "ozkurt", "plv"),
  phase_bw = 2,
  amp_bw = 10,
  n_bins = 18L,
  assay_name = NULL
)

Arguments

Value

The comodulogram list from PhysioCrossModal::comodulogram() (a matrix of phase x amplitude frequencies, plus its peak).

See Also

eegPAC()

Examples

if (requireNamespace("PhysioCrossModal", quietly = TRUE)) {
  pe <- make_eeg(n_time = 7500, n_channels = 2, sr = 250)
  cm <- eegComodulogram(pe, channel = 1)
  cm$peak
}

Description

Computes per-channel entropy, fractal-dimension and detrended-fluctuation complexity measures — the nonlinear family that complements the spectral, connectivity and source tools. For epoched (3-D) data each measure is computed per epoch and averaged across epochs.

Usage

eegComplexity(
  pe,
  measures = c("sample_entropy", "permutation_entropy", "lempel_ziv", "higuchi_fd",
    "dfa", "hjorth_mobility", "spectral_entropy"),
  assay_name = NULL,
  m = 2L,
  r = 0.2,
  tau = 1L,
  perm_order = 3L,
  mse_scales = 1:8,
  max_samples = 4000L
)

Arguments

Details

Available measures: "sample_entropy" (Richman–Moorman), "approximate_entropy" (Pincus), "permutation_entropy" (Bandt–Pompe), "multiscale_entropy" (Costa; returns the scale-averaged SampEn as a summary plus the per-scale curve in the attribute), "lempel_ziv" (Kaspar–Schuster), "higuchi_fd", "katz_fd", "dfa" (scaling exponent alpha), "hurst" (R/S), "hjorth_mobility", "hjorth_complexity", "spectral_entropy".

Value

A data frame with one row per channel and one column per requested measure (plus a channel column). The multiscale-entropy per-scale curves are attached as attr(, "mse_scales") / attr(, "mse_curve").

References

Richman & Moorman 2000; Bandt & Pompe 2002; Costa 2002; Higuchi 1988; Katz 1988; Peng 1994; Hjorth 1970.

See Also

eegQEEG(), eegAperiodic()

Examples

pe <- make_eeg(n_time = 512, n_channels = 4, sr = 128)
cx <- eegComplexity(pe, measures = c("permutation_entropy", "hjorth_mobility",
                                     "spectral_entropy"))
cx

Description

Computes conditional Granger causality from source to target given a set of conditioning channels, using the log ratio of the target's residual variance in a VAR fitted without the source (target + conditioning) versus with it (target + source + conditioning); both VARs share the same order (Geweke; Barnett & Seth 2014). Unlike the pairwise eegGrangerCausality(), conditioning removes indirect influences, so for a chain the conditional GC along a purely indirect path is near zero.

Usage

eegConditionalGC(
  x,
  target,
  source,
  conditioning = NULL,
  order = NULL,
  method = "ols",
  assay_name = NULL
)

Arguments

Value

A list with the conditional GC value (in nats, non-negative in theory), the target, source, and conditioning labels, and the VAR order used.

References

Barnett, L., & Seth, A. K. (2014). The MVGC multivariate Granger causality toolbox. Journal of Neuroscience Methods, 223, 50-68.

See Also

eegGrangerCausality(), eegDTF(), eegPDC()

Examples

pe <- make_eeg(n_time = 4000, n_channels = 3, sr = 250)
eegConditionalGC(pe, target = 3, source = 1, conditioning = 2)

Description

Convenience wrapper that computes a symmetric n_channels x n_channels connectivity matrix using the specified method. Dispatches to the appropriate connectivity function and returns a named matrix suitable for visualization or graph-theoretic analysis.

Usage

eegConnectivityMatrix(
  x,
  method = c("coherence", "plv", "wpli", "dtf", "pdc"),
  band = c(8, 13),
  ...
)

Arguments

Value

A named numeric matrix of dimension n_channels x n_channels with channel labels as row and column names. Diagonal elements are 1. Off-diagonal elements represent the band-averaged connectivity between channel pairs.

References

Lachaux, J. P., et al. (1999). Measuring phase synchrony in brain signals. Human Brain Mapping, 8(4), 194-208.

See Also

eegCoherence(), eegPLV(), eegWPLI(), eegGrangerCausality(), eegPlotConnectivity()

Examples

pe <- make_eeg(n_time = 5000, n_channels = 4, sr = 500)
conn <- eegConnectivityMatrix(pe, method = "plv", band = c(8, 13))
print(conn)

Description

Computes Common Spatial Pattern filters for two-class EEG discrimination. CSP maximizes the variance ratio between two conditions, making it a standard spatial filtering technique for motor imagery BCI.

Usage

eegCSP(x, labels, n_filters = 3, assay_name = NULL, output_assay = "csp")

Arguments

Value

Modified PhysioExperiment with CSP log-variance features in output_assay (a matrix of trials x 2 * n_filters) and CSP filter information stored in metadata(x)$csp as a list containing filters (spatial filter matrix), eigenvalues (selected eigenvalues), and classes (unique class labels).

References

Blankertz, B., et al. (2008). Optimizing spatial filters for robust EEG single-trial analysis. IEEE Signal Processing Magazine, 25(1), 41-56.

See Also

eegBCIfeatures(), eegBCIclassify(), eegMotorImagery()

Examples

pe <- make_eeg_bci(n_trials = 30, n_channels = 8, sr = 256)
labels <- S4Vectors::metadata(pe)$labels
result <- eegCSP(pe, labels = labels, n_filters = 3)
# CSP filters and log-variance features are stored in metadata
csp_features <- S4Vectors::metadata(result)$csp_features
dim(csp_features)  # trials x (2 * n_filters)

Description

Computes the delta-to-alpha band-power ratio per channel (or per region), a quantitative-EEG stroke marker whose elevation tracks ischaemic slowing (Finnigan et al. 2016). Band powers use a Welch estimator for a stable spectrum. Each ratio is returned as a reliability-characterised physioBiomarker carrying provenance (band, method, software version), reliability placeholders, and - when age (and montage) are supplied - a published reference range from normativeLookup so the value prints its normative percentile.

Usage

eegDAR(
  x,
  delta = c(1, 4),
  alpha = c(8, 13),
  regions = NULL,
  method = "welch",
  age = NULL,
  montage = NULL,
  reliability = list(icc = NA_real_, sem = NA_real_),
  assay_name = NULL
)

Arguments

Value

A named list of PhysioBiomarker objects, one per channel or region.

References

Finnigan, S., Wong, A., & Read, S. (2016). Defining abnormal slow EEG activity in acute ischaemic stroke: Delta/alpha ratio as an optimal QEEG index. Clinical Neurophysiology, 127(2), 1452-1459.

See Also

eegBSI(), eegSlowing(), eegQEEG(), PhysioExperiment::physioBiomarker(), PhysioExperiment::normativeLookup()

Examples

pe <- make_eeg(n_time = 5000, n_channels = 19, sr = 250)
dar <- eegDAR(pe, age = 60)
dar[["C3"]]

Description

Decodes trial class labels from epoched EEG with a strictly fold-safe pipeline: the spatial filter (CSP), feature extraction, feature scaling and classifier are all estimated on the training fold only and applied, frozen, to the test fold (Varoquaux et al., 2017). This avoids the label/data leakage of fitting CSP or scaling on the full dataset before cross-validation. Folds may respect a run/block grouping to avoid temporally-contiguous-epoch leakage.

Usage

eegDecode(
  x,
  labels = NULL,
  pipeline = c("csp+lda", "bandpower+lda", "riemannian"),
  cv = c("stratified-kfold", "leave-one-run-out"),
  n_folds = 5,
  groups = NULL,
  n_permutations = 200,
  inner_cv = NULL,
  assay_name = NULL,
  n_csp = 3,
  bands = NULL,
  seed = NULL
)

Arguments

Value

A list of class "eeg_decode" with:

accuracy

pooled out-of-fold accuracy.

accuracy_ci

95 percent Wilson confidence interval for the accuracy.

fold_accuracy

per-fold accuracy.

auc

binary area under the ROC curve.

confusion

confusion matrix (true x predicted).

permutation

list with p_value, null_accuracy, n_permutations.

predictions

a data.frame (trial, fold, true, predicted, score).

csp_filters

per-fold CSP filters ("csp+lda" only).

References

Varoquaux, G., et al. (2017). "Assessing and tuning brain decoders: cross-validation, caveats, and guidelines." NeuroImage, 145, 166-179. doi:10.1016/j.neuroimage.2016.10.038

Lemm, S., et al. (2011). "Introduction to machine learning for brain imaging." NeuroImage, 56(2), 387-399. doi:10.1016/j.neuroimage.2010.11.004

See Also

eegCSP, eegBCIfeatures. The older eegBCIclassify cross-validation path is leakage-prone and deprecated in favour of eegDecode.

Examples

pe <- make_eeg_bci(n_trials = 20, n_channels = 8, sr = 128, trial_sec = 3)
res <- eegDecode(pe, pipeline = "csp+lda", n_permutations = 0, seed = 1)
res$accuracy

Description

Localizes the single equivalent current dipole that best explains a scalp topography, by nonlinearly optimizing the dipole position (a grid search inside the head sphere refined with Nelder-Mead) while the dipole moment is the closed-form least-squares fit at each candidate position. Uses the same forward physics as eegForwardModel() and the electrode positions from colData / the montage. This is the classic focal-source complement to the distributed inverses in eegSourceEstimate().

Usage

eegDipoleFit(
  x,
  time = NULL,
  method = c("spherical", "bem_simplified"),
  n_grid = 8L,
  assay_name = NULL
)

Arguments

Value

An eeg_dipole_fit object: position (x, y, z in normalized head radius), moment, orientation (unit), amplitude, gof (goodness of fit, variance explained), residual, and the fitted/observed topographies.

References

Scherg (1990); Mosher, Lewis & Leahy (1992).

See Also

eegSourceEstimate(), eegForwardModel()

Examples

pe <- make_eeg(n_time = 100, n_channels = 19, sr = 100)
fit <- eegDipoleFit(pe)
fit$gof

Description

Estimates frequency-resolved directed connectivity between EEG channels with the Directed Transfer Function (Kaminski & Blinowska 1991), computed from the transfer function $H(f)$ of a multivariate autoregressive (MVAR) model fitted with PhysioExperiment::mvarFit(). Because $H(f)$ inverts the whole VAR system, DTF reflects both direct and indirect pathways. The (default) normalized DTF satisfies $\sum_j \mathrm{DTF}_{ij}(f)^2 = 1$ for each target $i$ (inflow normalization); ffDTF normalizes across all frequencies instead (Korzeniewska 2003).

Usage

eegDTF(
  x,
  order = NULL,
  freqs = NULL,
  normalized = TRUE,
  ffDTF = FALSE,
  band = NULL,
  method = "ols",
  assay_name = NULL
)

Arguments

Value

The PhysioExperiment with metadata(x)$connectivity set to a list containing the band-averaged directed matrix (rows = targets, columns = sources), the frequency-resolved array (n_channels x n_channels x n_freqs), the frequencies, and the settings used.

References

Kaminski, M. J., & Blinowska, K. J. (1991). A new method of the description of the information flow in the brain structures. Biological Cybernetics, 65(3), 203-210.

See Also

eegPDC(), eegConditionalGC(), eegConnectivityMatrix(), PhysioExperiment::mvarFit()

Examples

pe <- make_eeg(n_time = 4000, n_channels = 5, sr = 250)
pe <- eegDTF(pe, order = 5)
dim(S4Vectors::metadata(pe)$connectivity$array)

Description

Segments continuous 2D EEG data into fixed-length epochs around events, producing a 3D array (time x channels x epochs). Optionally performs baseline correction by subtracting the mean of a pre-stimulus window.

Usage

eegEpoch(
  x,
  events,
  limits = c(-0.2, 0.8),
  baseline = c(-0.2, 0),
  assay_name = NULL,
  output_assay = "epoched"
)

Arguments

Value

A PhysioExperiment object with a 3D array (time x channels x epochs) in the specified output assay. Event information is stored in metadata(x)$epoch_events.

Examples

pe <- make_eeg(n_time = 10000, n_channels = 19, sr = 500)
events <- data.frame(onset_sec = c(1.0, 3.0, 5.0, 7.0))
pe_ep <- eegEpoch(pe, events, limits = c(-0.2, 0.8))
# the epoched array is stored in metadata(x)$epoched
dim(S4Vectors::metadata(pe_ep)$epoched)  # time x channels x epochs

Description

Subtracts the mean amplitude of a pre-stimulus baseline period from each epoch. This is an essential preprocessing step before ERP measurement.

Usage

eegERPbaseline(
  x,
  baseline = c(-200, 0),
  epoch_start = 0,
  assay_name = NULL,
  output_assay = "baseline_corrected"
)

Arguments

Value

Modified PhysioExperiment with baseline-corrected data in output_assay. Creates a new 3D assay (time x channels x epochs) where each epoch has had the mean of its baseline period subtracted.

References

Luck, S. J. (2014). An Introduction to the Event-Related Potential Technique (2nd ed.). MIT Press.

See Also

eegERPdetect(), eegERPmeasure(), eegEpoch(), eegFilter()

Examples

pe <- make_eeg_erp(n_epochs = 40, sr = 250)
result <- eegERPbaseline(pe, baseline = c(-200, 0), epoch_start = -200)

Description

Detects known event-related potential (ERP) components in epoched (3D) EEG data. Averages across epochs and finds peaks within predefined time windows.

Usage

eegERPdetect(
  x,
  component = c("N100", "P300", "N400", "P600", "MMN", "LPP"),
  channels = NULL,
  epoch_start = 0,
  assay_name = NULL
)

Arguments

Value

A data.frame with columns: channel (character label), component (character name), latency_ms (numeric peak latency in milliseconds), and amplitude (numeric peak amplitude).

References

Luck, S. J. (2014). An Introduction to the Event-Related Potential Technique (2nd ed.). MIT Press.

See Also

eegERPmeasure(), eegERPlatency(), eegERPbaseline(), eegEpoch(), eegPlotERP()

Examples

pe <- make_eeg_erp(n_epochs = 40, sr = 250)
result <- eegERPdetect(pe, component = "P300")

Description

Computes the difference waveform between two PhysioExperiment objects by subtracting the assay data of y from x.

Usage

eegERPdifference(x, y, assay_name = NULL, output_assay = "difference")

Arguments

Value

Modified x with difference waveform stored in output_assay. The difference assay has the same dimensions as the input assay.

References

Luck, S. J. (2014). An Introduction to the Event-Related Potential Technique (2nd ed.). MIT Press.

See Also

eegERPdetect(), eegERPmeasure(), eegERPtest(), eegERPgrandAverage()

Examples

pe1 <- make_eeg_erp(n_epochs = 20, sr = 250)
pe2 <- make_eeg_erp(n_epochs = 20, sr = 250)
result <- eegERPdifference(pe1, pe2)

Description

Averages ERP waveforms across multiple PhysioExperiment objects (participants). Each input should already be averaged across trials.

Usage

eegERPgrandAverage(..., assay_name = NULL, output_assay = "grand_average")

Arguments

Value

A PhysioExperiment (the first input object) with the grand average waveform stored in output_assay. The grand average assay has the same dimensions as the input assays.

References

Luck, S. J. (2014). An Introduction to the Event-Related Potential Technique (2nd ed.). MIT Press.

See Also

eegERPdetect(), eegERPmeasure(), eegERPtest(), eegERPdifference()

Examples

pe1 <- make_eeg_erp(n_epochs = 20, sr = 250)
pe2 <- make_eeg_erp(n_epochs = 20, sr = 250)
result <- eegERPgrandAverage(pe1, pe2)

Description

Computes the fractional area latency of an ERP component. This is the time point at which a specified fraction of the total area under the curve (in the given window) has accumulated.

Usage

eegERPlatency(
  x,
  window,
  fraction = 0.5,
  polarity = c("positive", "negative"),
  epoch_start = 0,
  assay_name = NULL
)

Arguments

Value

A data.frame with columns: channel (character label), latency_ms (numeric fractional area latency in milliseconds), and fraction (numeric fraction used).

References

Luck, S. J. (2014). An Introduction to the Event-Related Potential Technique (2nd ed.). MIT Press.

See Also

eegERPdetect(), eegERPmeasure(), eegERPbaseline(), eegPlotERP()

Examples

pe <- make_eeg_erp(n_epochs = 40, sr = 250)
result <- eegERPlatency(pe, window = c(250, 500), fraction = 0.5,
                        polarity = "positive")

Description

Measures ERP amplitude in a specified time window using peak, mean, or adaptive mean methods. For epoched (3D) data, averages across epochs first.

Usage

eegERPmeasure(
  x,
  window,
  method = c("peak", "mean", "adaptive_mean"),
  polarity = c("positive", "negative"),
  epoch_start = 0,
  assay_name = NULL
)

Arguments

Value

A data.frame with columns: channel (character label), amplitude (numeric measured amplitude), latency_ms (numeric latency in milliseconds), and method (character measurement method used).

References

Luck, S. J. (2014). An Introduction to the Event-Related Potential Technique (2nd ed.). MIT Press.

See Also

eegERPdetect(), eegERPlatency(), eegERPbaseline(), eegPlotERP()

Examples

pe <- make_eeg_erp(n_epochs = 40, sr = 250)
result <- eegERPmeasure(pe, window = c(250, 500), method = "peak",
                        polarity = "positive")

Description

Performs permutation testing or cluster-based permutation testing to compare ERP waveforms between conditions.

Usage

eegERPtest(
  x,
  y,
  method = c("permutation", "cluster"),
  n_perm = 1000,
  alpha = 0.05,
  cluster_alpha = 0.05,
  assay_name = NULL
)

Arguments

Value

A data.frame with columns: time_sample (integer), t_statistic (numeric observed t-value), p_value (numeric permutation-based p-value), and significant (logical). For the "cluster" method, also includes cluster_id (integer cluster assignment) and cluster_p (numeric cluster-level corrected p-value).

References

Luck, S. J. (2014). An Introduction to the Event-Related Potential Technique (2nd ed.). MIT Press.

Maris, E., & Oostenveld, R. (2007). Nonparametric statistical testing of EEG- and MEG-data. Journal of Neuroscience Methods, 164(1), 177-190.

See Also

eegERPdetect(), eegERPmeasure(), eegERPdifference(), eegERPgrandAverage()

Examples

pe1 <- make_eeg_erp(n_epochs = 20, sr = 250)
pe2 <- make_eeg_erp(n_epochs = 20, sr = 250)
result <- eegERPtest(pe1, pe2, method = "permutation", n_perm = 500)

Description

Computes Event-Related Spectral Perturbation for epoched (3D) EEG data. ERSP quantifies event-related changes in spectral power relative to a baseline period, expressed in decibels (dB). Uses the Morlet wavelet transform to compute time-frequency decomposition for each epoch, then averages power across epochs and normalizes to baseline.

Usage

eegERSP(
  x,
  baseline = c(1, 50),
  frequencies = NULL,
  n_cycles = 7,
  assay_name = NULL,
  output_assay = "ersp_data"
)

Arguments

Value

Modified PhysioExperiment with:

• 3D ERSP array (time x frequencies x channels) in dB in output_assay

• Baseline info and frequency vector in metadata(x)$ersp, a list containing frequencies (numeric vector), baseline (numeric vector), n_cycles (integer), and n_epochs (integer)

References

Tallon-Baudry, C., et al. (1997). Oscillatory gamma-band activity during conscious perception. Trends in Cognitive Sciences, 3(4), 151-162.

Makeig, S. (1993). Auditory event-related dynamics of the EEG spectrum and effects of exposure to tones. Electroencephalography and Clinical Neurophysiology, 86(4), 283-293.

See Also

eegITC(), eegMorletWavelet(), eegPlotSpectrogram()

Examples

pe <- make_eeg_erp(n_epochs = 20, n_channels = 2, sr = 250)
pe_ersp <- eegERSP(pe, baseline = c(1, 50), frequencies = seq(5, 30, by = 5))
# results are stored in metadata(x)$ersp
str(S4Vectors::metadata(pe_ersp)$ersp, max.level = 1)

Description

Applies frequency-domain filtering to EEG data stored in a PhysioExperiment object. Supports bandpass, highpass, lowpass, and notch filtering using either FIR (windowed-sinc) or IIR (Butterworth) methods.

Usage

eegFilter(
  x,
  lowcut = NULL,
  highcut = NULL,
  notch = NULL,
  method = c("fir", "iir"),
  order = NULL,
  assay_name = NULL,
  output_assay = "filtered"
)

Arguments

Details

For FIR mode, the function uses windowed-sinc filters with a Hamming window. For IIR mode, zero-phase Butterworth filtering is applied via signal::filtfilt(), with automatic fallback to FIR if the signal package is not available.

Value

A PhysioExperiment object with filtered data in the specified output assay.

Examples

pe <- make_eeg(n_time = 5000, n_channels = 19, sr = 500)
# Bandpass filter
pe_filt <- eegFilter(pe, lowcut = 1, highcut = 40)
# Highpass only
pe_hp <- eegFilter(pe, lowcut = 0.1)
# With notch at 50 Hz
pe_notch <- eegFilter(pe, lowcut = 1, highcut = 40, notch = 50)
# IIR Butterworth
pe_iir <- eegFilter(pe, lowcut = 1, highcut = 40, method = "iir", order = 4)

Description

Constructs a leadfield matrix that maps brain source activity to scalp electrode potentials. Uses electrode positions from colData(x) if available, otherwise falls back to standard 10-20 system positions on a unit sphere.

Usage

eegForwardModel(
  x,
  method = c("spherical", "bem_simplified", "bem", "sphere_analytic", "nyhead",
    "fsaverage"),
  n_sources = 500,
  assay_name = NULL
)

Arguments

Value

A list with components:

leadfield

Numeric matrix of dimensions n_electrodes x (n_sources * 3). Each source has 3 orientation columns (x, y, z).

source_positions

Data frame with columns x, y, z for each source location.

electrode_positions

Data frame with columns label, x, y, z for each electrode.

n_sources

Integer number of source dipoles.

source_normals

For the realistic methods, an n_sources x 3 matrix of cortical surface normals (absent for the legacy methods).

method

The resolved forward-model method.

coordinate_provenance

Source-space origin, units, and anatomical fidelity used by coordinate-aware plotting functions.

References

Pascual-Marqui, R. D. (2002). Standardized low-resolution brain electromagnetic tomography (sLORETA). Methods and Findings in Experimental and Clinical Pharmacology, 24(Suppl D), 5-12.

See Also

eegSourceEstimate(), eegBeamformer(), eegSourcePower()

Examples

pe <- make_eeg(n_time = 1000, n_channels = 19, sr = 250)
fm <- eegForwardModel(pe, method = "spherical", n_sources = 100)
dim(fm$leadfield)

Description

Computes spectral Granger causality between all EEG channel pairs by fitting bivariate autoregressive (AR) models using Yule-Walker equations and computing the transfer function in the frequency domain. Unlike coherence-based measures, Granger causality is directional: GC from channel A to channel B is generally different from GC from B to A.

Usage

eegGrangerCausality(x, order = 5, band = NULL, assay_name = NULL)

Arguments

Details

The spectral Granger causality from channel x to channel y at frequency f is defined as:

$GC_{x \to y}(f) = \log(S_{yy}(f) / (S_{yy}(f) - |H_{xy}(f)|^2 \cdot \Sigma_{xx}))$

Value

A data.frame with columns:

from_channel

Character or integer identifier of the source channel.

to_channel

Character or integer identifier of the target channel.

gc_value

Numeric Granger causality value (>= 0). Higher values indicate stronger directed influence.

References

Lachaux, J. P., et al. (1999). Measuring phase synchrony in brain signals. Human Brain Mapping, 8(4), 194-208.

Granger, C. W. J. (1969). Investigating causal relations by econometric models and cross-spectral methods. Econometrica, 37(3), 424-438.

See Also

eegCoherence(), eegPLV(), eegWPLI(), eegConnectivityMatrix()

Examples

pe <- make_eeg(n_time = 5000, n_channels = 4, sr = 500)
gc_df <- eegGrangerCausality(pe, order = 5, band = c(8, 13))
head(gc_df)

Description

Decomposes multi-channel EEG into independent components using ICA. Supports FastICA, Infomax, and JADE algorithms. Results are stored in the output assay (component activations) and in metadata(x)$ica (mixing and unmixing matrices).

Usage

eegICA(
  x,
  n_components = NULL,
  method = c("fastica", "infomax", "jade"),
  max_iter = 200L,
  tol = 1e-06,
  assay_name = NULL,
  output_assay = "ica_components"
)

Arguments

Value

Modified PhysioExperiment with component activations in output_assay and ICA metadata in metadata(x)$ica. The ICA metadata list contains: mixing (mixing matrix A), unmixing (unmixing matrix), mean (channel means), whiten (whitening matrix), and method (algorithm used). The output assay has dimensions n_time x n_components.

References

Hyvarinen, A., & Oja, E. (2000). Independent component analysis: algorithms and applications. Neural Networks, 13(4-5), 411-430.

Bell, A. J., & Sejnowski, T. J. (1995). An information-maximization approach to blind separation and blind deconvolution. Neural Computation, 7(6), 1129-1159.

See Also

eegICAremove(), eegICAdetect(), eegICAmix(), eegFilter(), eegPreprocess()

Examples

pe <- make_eeg(n_time = 5000, sr = 500)
result <- eegICA(pe, n_components = 4, method = "fastica")

Description

Automatically identifies artifact components using one of four methods: correlation with frontal channels, kurtosis, spatial weight pattern, or the ICLabel-style seven-class classifier (eegICLabel()). The "iclabel" method delegates to eegICLabel() and collapses its result to the two-class contract (any non-brain argmax is an "artifact"), with the score being one minus the brain probability.

Usage

eegICAdetect(
  x,
  method = c("correlation", "kurtosis", "spatial", "iclabel"),
  threshold = 0.3,
  ica_assay = "ica_components"
)

Arguments

Value

A data.frame with columns: component (integer index), type ("artifact" or "neural"), method (detection method used), and score (numeric detection score).

References

Hyvarinen, A., & Oja, E. (2000). Independent component analysis: algorithms and applications. Neural Networks, 13(4-5), 411-430.

Bell, A. J., & Sejnowski, T. J. (1995). An information-maximization approach to blind separation and blind deconvolution. Neural Computation, 7(6), 1129-1159.

See Also

eegICA(), eegICAremove(), eegICAmix()

Examples

pe <- make_eeg(n_time = 5000, sr = 500)
pe <- eegICA(pe, n_components = 4, method = "fastica")
artifacts <- eegICAdetect(pe, method = "kurtosis")

Description

Returns the ICA results stored in metadata(x)$ica, including the mixing matrix, unmixing matrix, channel means, and whitening matrix.

Usage

eegICAmix(x)

Arguments

Value

A list containing: mixing (mixing matrix A, n_channels x n_components), unmixing (unmixing matrix, n_components x n_channels), mean (channel mean vector), whiten (whitening matrix), and method (character, algorithm used).

References

Hyvarinen, A., & Oja, E. (2000). Independent component analysis: algorithms and applications. Neural Networks, 13(4-5), 411-430.

Bell, A. J., & Sejnowski, T. J. (1995). An information-maximization approach to blind separation and blind deconvolution. Neural Computation, 7(6), 1129-1159.

See Also

eegICA(), eegICAremove(), eegICAdetect()

Examples

pe <- make_eeg(n_time = 5000, sr = 500)
pe <- eegICA(pe, n_components = 4, method = "fastica")
ica_info <- eegICAmix(pe)

Description

Reconstructs EEG data with specified independent components removed. The removed components are zeroed out in the mixing matrix before back-projecting to channel space.

Usage

eegICAremove(
  x,
  components,
  ica_assay = "ica_components",
  output_assay = "ica_cleaned"
)

Arguments

Value

Modified PhysioExperiment with cleaned data in output_assay. The cleaned assay contains reconstructed channel data with specified components removed. Dimensions match the original data.

References

Hyvarinen, A., & Oja, E. (2000). Independent component analysis: algorithms and applications. Neural Networks, 13(4-5), 411-430.

Bell, A. J., & Sejnowski, T. J. (1995). An information-maximization approach to blind separation and blind deconvolution. Neural Computation, 7(6), 1129-1159.

See Also

eegICA(), eegICAdetect(), eegICAmix()

Examples

pe <- make_eeg(n_time = 5000, sr = 500)
pe <- eegICA(pe, n_components = 4, method = "fastica")
pe <- eegICAremove(pe, components = c(1, 2))

Description

Classifies independent components (from eegICA()) into seven classes - brain, muscle, eye, heart, line_noise, channel_noise, and other - and returns a calibrated probability for each class per component together with the argmax label. The approach follows the ICLabel framework: interpretable spatial, spectral, and temporal features are extracted from each component and mapped to class probabilities by a lightweight multinomial-logistic (softmax) head.

Usage

eegICLabel(
  x,
  ica_assay = "ica_components",
  assay_name = NULL,
  line_freq = 50,
  backend = c("heuristic", "iclabel")
)

Arguments

Details

Features per component:

• Spatial: frontal energy (eye/blink topography), focality (single channel dominance), topography kurtosis.

• Spectral: 1/f slope, high- versus low-frequency band ratio, low-frequency fraction, a genuine alpha-peak measure (8-12 Hz power above its theta/low-beta neighbours), and a line-noise power ratio and fraction.

• Temporal: lag-1 autocorrelation, activation kurtosis (spiky blink or ECG signatures), and a roughly 1 Hz periodicity measure for cardiac components.

The softmax weights are read from inst/extdata/iclabel_weights.csv; if that file is unavailable an identical built-in weight table is used, so the classifier always works.

Value

A data.frame with one row per component: component (integer index), one numeric column per class (brain, muscle, eye, heart, line_noise, channel_noise, other) holding probabilities that sum to 1 across the classes, and label (character argmax class).

References

Pion-Tonachini, L., Kreutz-Delgado, K., & Makeig, S. (2019). ICLabel: An automated electroencephalographic independent component classifier, dataset, and website. NeuroImage, 198, 181-197.

Winkler, I., Haufe, S., & Tangermann, M. (2011). Automatic classification of artifactual ICA-components for artifact removal in EEG signals. Behavioral and Brain Functions, 7, 30.

See Also

eegICA(), eegICLabelFlag(), eegICAdetect(), eegICAremove()

Examples

pe <- make_eeg(n_time = 5000, sr = 500)
pe <- eegICA(pe, n_components = 10, method = "fastica")
probs <- eegICLabel(pe)

Description

Convenience wrapper over eegICLabel() that returns the indices of the components most likely to be artifacts, ready to pass to eegICAremove(). A component is flagged when its probability in any of the requested artifact classes exceeds prob_threshold.

Usage

eegICLabelFlag(
  x,
  prob_threshold = 0.5,
  classes = c("muscle", "eye", "heart", "line_noise", "channel_noise"),
  ica_assay = "ica_components",
  line_freq = 50
)

Arguments

Value

An integer vector of flagged component indices (possibly empty), with an attribute "labels" giving the corresponding class of each.

See Also

eegICLabel(), eegICAremove(), eegICAdetect()

Examples

pe <- make_eeg(n_time = 5000, sr = 500)
pe <- eegICA(pe, n_components = 10, method = "fastica")
bad <- eegICLabelFlag(pe, prob_threshold = 0.5)
pe <- eegICAremove(pe, components = bad)

Description

Replaces data in bad channels by interpolating from remaining good channels using either spherical spline interpolation (Perrin et al., 1989) or nearest-neighbor weighted averaging.

Usage

eegInterpolate(
  x,
  bad_channels,
  method = c("spline", "nearest"),
  assay_name = NULL,
  output_assay = "interpolated"
)

Arguments

Details

Requires electrode positions (pos_x, pos_y, pos_z) in colData. Apply eegMontage first if positions are not set.

Value

A PhysioExperiment object with interpolated channels in the specified output assay.

Examples

pe <- make_eeg(n_time = 5000, n_channels = 19, sr = 500)
pe <- eegMontage(pe, system = "10-20")
# interpolate two named channels from their neighbours
pe_clean <- eegInterpolate(pe, bad_channels = c("C3", "C4"))
pe_clean

Description

Computes Inter-Trial Coherence (also known as phase-locking factor or phase-locking value) for epoched (3D) EEG data. ITC measures the consistency of oscillatory phase across trials at each time-frequency point. Values range from 0 (completely random phase) to 1 (perfectly phase-locked across all trials).

Usage

eegITC(
  x,
  frequencies = NULL,
  n_cycles = 7,
  assay_name = NULL,
  output_assay = "itc_data"
)

Arguments

Value

Modified PhysioExperiment with:

• 3D ITC array (time x frequencies x channels) in output_assay, values in [0, 1]

• Frequency vector and parameters in metadata(x)$itc, a list containing frequencies (numeric vector), n_cycles (integer), and n_epochs (integer)

References

Tallon-Baudry, C., et al. (1997). Oscillatory gamma-band activity during conscious perception. Trends in Cognitive Sciences, 3(4), 151-162.

Makeig, S. (1993). Auditory event-related dynamics of the EEG spectrum and effects of exposure to tones. Electroencephalography and Clinical Neurophysiology, 86(4), 283-293.

See Also

eegERSP(), eegMorletWavelet(), eegPlotSpectrogram()

Examples

pe <- make_eeg_erp(n_epochs = 20, n_channels = 2, sr = 250)
pe_itc <- eegITC(pe, frequencies = seq(5, 30, by = 5))
# results are stored in metadata(x)$itc
str(S4Vectors::metadata(pe_itc)$itc, max.level = 1)

Description

Identifies K-complexes in EEG data by lowpass filtering at 4 Hz, finding negative peaks exceeding a threshold amplitude, and verifying the characteristic negative-positive waveform morphology.

Usage

eegKcomplexDetect(
  x,
  min_neg_amplitude = 75,
  min_duration_ms = 500,
  max_duration_ms = 1500,
  assay_name = NULL
)

Arguments

Value

A data.frame with columns:

channel

Integer channel index.

negative_peak_sample

Integer sample of the negative peak.

positive_peak_sample

Integer sample of the positive peak.

negative_amplitude

Numeric amplitude at the negative peak.

positive_amplitude

Numeric amplitude at the positive peak.

duration_ms

Numeric total duration in milliseconds.

References

Berry, R. B., et al. (2017). AASM Scoring Manual Updates for 2017. Journal of Clinical Sleep Medicine, 13(5), 665-666.

See Also

eegSleepStage(), eegSpindleDetect(), eegSlowWaveDetect(), eegSleepMetrics()

Examples

pe <- make_eeg_sleep(n_time = 150000, n_channels = 2, sr = 500)
kcomplexes <- eegKcomplexDetect(pe)
head(kcomplexes)

Description

Quantifies the hemispheric asymmetry of sensorimotor-rhythm activity during motor imagery, a rehabilitation-relevant index of affected- versus unaffected-hemisphere engagement. For each trial a laterality index $LI = (R - L) / (|R| + |L|)$ is computed from a right- and a left-hemisphere channel (or ROI), bounded from -1 to 1. With method = "erd" the activation is the event-related desynchronization magnitude from eegMotorImagery() (a positive LI means the right hemisphere desynchronizes more, i.e. is more active); with method = "power" it is the raw band power (a positive LI means the right hemisphere has more power). A symmetric input gives $LI \approx 0$.

Usage

eegLateralization(
  x,
  left_ch = "C3",
  right_ch = "C4",
  band = c(8, 13),
  method = c("erd", "power"),
  baseline_fraction = 0.25,
  conf_level = 0.95,
  reliability = list(icc = NA_real_, sem = NA_real_),
  assay_name = NULL
)

Arguments

Value

A list with per_trial (an n_trials x 1 matrix of laterality indices) and summary (a PhysioBiomarker holding the mean LI with its confidence interval, reliability, and provenance).

References

Pfurtscheller, G., & Lopes da Silva, F. H. (1999). Event-related EEG/MEG synchronization and desynchronization: basic principles. Clinical Neurophysiology, 110(11), 1842-1857.

Bai, O., et al. (2005). Asymmetric spatiotemporal patterns of event-related desynchronization preceding voluntary sequential finger movements. Clinical Neurophysiology, 116(5), 1213-1221.

See Also

eegMotorImagery(), eegCSP(), PhysioExperiment::physioBiomarker()

Examples

pe <- make_eeg_bci(n_trials = 20, n_channels = 8, sr = 256)
li <- eegLateralization(pe, method = "power")
li$summary

Description

Assigns each time point to the microstate template map with the highest absolute spatial correlation. This allows applying microstate maps derived from one dataset to another dataset.

Usage

eegMicrostateBackfit(x, maps, assay_name = NULL)

Arguments

Value

Modified PhysioExperiment with updated microstate labels in metadata(x)$microstates$labels. Also stores the template maps in metadata(x)$microstates$maps and the number of states in metadata(x)$microstates$n_states.

References

Michel, C. M., & Koenig, T. (2018). EEG microstates as a tool for studying the temporal dynamics of whole-brain neuronal networks. NeuroImage, 180, 577-593.

See Also

eegMicrostates(), eegMicrostateStats(), eegMicrostateSequence()

Examples

pe1 <- make_eeg(n_time = 5000, n_channels = 19, sr = 500)
pe1 <- eegMicrostates(pe1, n_states = 4)
maps <- S4Vectors::metadata(pe1)$microstates$maps

pe2 <- make_eeg(n_time = 3000, n_channels = 19, sr = 500)
pe2 <- eegMicrostateBackfit(pe2, maps)

Description

Performs microstate analysis on EEG data by identifying dominant scalp topographies at Global Field Power (GFP) peaks and assigning each time point to the best-matching microstate map. Supports polarity-invariant K-means, atomize-and-agglomerate hierarchical clustering (AAHC), and PCA-based extraction.

Usage

eegMicrostates(
  x,
  n_states = 4,
  method = c("kmeans", "aahc", "pca"),
  min_gfp = 1,
  assay_name = NULL
)

Arguments

Value

Modified PhysioExperiment with microstate results stored in metadata(x)$microstates, a list containing:

maps

Numeric matrix of dimensions n_channels x n_states, each column a microstate topography.

labels

Integer vector of length n_time, microstate assignment (1 to n_states) for each time point.

gfp

Numeric vector of GFP values per time point.

n_states

Integer number of microstate classes.

References

Michel, C. M., & Koenig, T. (2018). EEG microstates as a tool for studying the temporal dynamics of whole-brain neuronal networks. NeuroImage, 180, 577-593.

See Also

eegMicrostateStats(), eegMicrostateBackfit(), eegMicrostateSequence()

Examples

pe <- make_eeg(n_time = 5000, n_channels = 19, sr = 500)
pe <- eegMicrostates(pe, n_states = 4, method = "kmeans")
ms <- S4Vectors::metadata(pe)$microstates

Description

Converts integer microstate labels to character labels ("A", "B", "C", ...).

Usage

eegMicrostateSequence(x)

Arguments

Value

Character vector of length n_time with labels "A", "B", "C", etc. Each element corresponds to the microstate class assigned to that time point.

References

Michel, C. M., & Koenig, T. (2018). EEG microstates as a tool for studying the temporal dynamics of whole-brain neuronal networks. NeuroImage, 180, 577-593.

See Also

eegMicrostates(), eegMicrostateStats(), eegMicrostateBackfit()

Examples

pe <- make_eeg(n_time = 2000, n_channels = 19, sr = 500)
pe <- eegMicrostates(pe, n_states = 4)
seq_labels <- eegMicrostateSequence(pe)
table(seq_labels)

Description

Calculates temporal statistics for each microstate class from a segmented EEG recording: mean duration, occurrence rate, and time coverage. Also computes the transition probability matrix between states.

Usage

eegMicrostateStats(x)

Arguments

Value

A data.frame with columns:

state

Integer microstate class (1 to n_states).

duration_ms

Mean duration of consecutive runs in milliseconds.

occurrence_per_sec

Number of state occurrences (runs) per second.

coverage_pct

Percentage of total time spent in this state.

The transition probability matrix (n_states x n_states) is stored as an attribute "transition_matrix".

References

Michel, C. M., & Koenig, T. (2018). EEG microstates as a tool for studying the temporal dynamics of whole-brain neuronal networks. NeuroImage, 180, 577-593.

See Also

eegMicrostates(), eegMicrostateBackfit(), eegMicrostateSequence()

Examples

pe <- make_eeg(n_time = 5000, n_channels = 19, sr = 500)
pe <- eegMicrostates(pe, n_states = 4, method = "kmeans")
stats <- eegMicrostateStats(pe)
print(stats)
attr(stats, "transition_matrix")

Description

Maps channel labels to standard electrode positions from a known montage system (10-20, 10-10, BioSemi64) or from a custom positions data.frame. Sets pos_x, pos_y, pos_z columns in colData for use by interpolation, topographic mapping, and source localization functions.

Usage

eegMontage(
  x,
  system = c("10-20", "10-10", "biosemi64", "custom"),
  positions = NULL
)

Arguments

Value

A PhysioExperiment object with updated colData containing position columns.

Examples

pe <- make_eeg(n_time = 5000, n_channels = 19, sr = 500)
pe <- eegMontage(pe, system = "10-20")
head(SummarizedExperiment::colData(pe))

Description

Computes the continuous Morlet wavelet transform for multi-channel EEG data. For each specified frequency, a complex Morlet wavelet is constructed and convolved with each channel using FFT-based convolution for efficiency. Returns time-resolved power (and optionally phase) across frequencies.

Usage

eegMorletWavelet(
  x,
  frequencies = NULL,
  n_cycles = 7,
  assay_name = NULL,
  output_assay = "wavelet_power"
)

Arguments

Value

Modified PhysioExperiment with:

• 3D power array (time x frequencies x channels) in output_assay

• Frequency vector and phase array in metadata(x)$wavelet, a list containing frequencies (numeric vector), n_cycles (integer), and phase (3D array of instantaneous phase values)

References

Tallon-Baudry, C., et al. (1997). Oscillatory gamma-band activity during conscious perception. Trends in Cognitive Sciences, 3(4), 151-162.

See Also

eegSTFT(), eegMultitaper(), eegPlotSpectrogram(), eegERSP()

Examples

pe <- make_eeg(n_time = 1000, n_channels = 4, sr = 250)
pe_wt <- eegMorletWavelet(pe, frequencies = seq(5, 40, by = 5))
# results are stored in metadata(x)$wavelet
str(S4Vectors::metadata(pe_wt)$wavelet, max.level = 1)

Description

Computes event-related desynchronization (ERD) and event-related synchronization (ERS) for motor imagery BCI analysis. ERD/ERS is expressed as a percentage change from baseline power in specified frequency bands.

Usage

eegMotorImagery(
  x,
  bands = NULL,
  baseline_fraction = 0.25,
  assay_name = NULL,
  output_assay = "erd_ers"
)

Arguments

Value

Modified PhysioExperiment with ERD/ERS percentage values in output_assay. The output is a matrix of n_trials rows x n_channels * n_bands columns. Sets metadata(x)$erd_ers_bands with the band definitions used.

References

Blankertz, B., et al. (2008). Optimizing spatial filters for robust EEG single-trial analysis. IEEE Signal Processing Magazine, 25(1), 41-56.

See Also

eegCSP(), eegBCIfeatures(), eegBCIclassify()

Examples

pe <- make_eeg_bci(n_trials = 20, n_channels = 8, sr = 256)
result <- eegMotorImagery(pe)
# ERD/ERS features are stored in metadata(x)$erd_ers
erd_data <- S4Vectors::metadata(result)$erd_ers
dim(erd_data)  # trials x (channels * bands)

Description

Computes the multitaper power spectral density (PSD) estimate for multi-channel EEG data using Discrete Prolate Spheroidal Sequences (DPSS, Slepian tapers). The multitaper method provides an optimal bias-variance trade-off for spectral estimation compared to single-window methods.

Usage

eegMultitaper(
  x,
  bandwidth = 4,
  n_tapers = NULL,
  assay_name = NULL,
  output_assay = "multitaper_psd"
)

Arguments

Value

Modified PhysioExperiment with:

• PSD matrix (frequencies x channels) in output_assay

• Frequency vector and taper parameters in metadata(x)$multitaper, a list containing frequencies (numeric vector), bandwidth (numeric NW parameter), and n_tapers (integer)

References

Tallon-Baudry, C., et al. (1997). Oscillatory gamma-band activity during conscious perception. Trends in Cognitive Sciences, 3(4), 151-162.

Thomson, D. J. (1982). Spectrum estimation and harmonic analysis. Proceedings of the IEEE, 70(9), 1055-1096.

See Also

eegMorletWavelet(), eegSTFT(), eegPlotSpectrogram()

Examples

pe <- make_eeg(n_time = 2000, n_channels = 4, sr = 250)
pe_mt <- eegMultitaper(pe, bandwidth = 4)
# results are stored in metadata(x)$multitaper
str(S4Vectors::metadata(pe_mt)$multitaper, max.level = 1)

Description

Measures how the phase of a slow oscillation modulates the amplitude of a fast oscillation — within a single channel (amp_channel = NULL) or across two channels. Delegates the estimator to PhysioCrossModal::phaseAmplitudeCoupling().

Usage

eegPAC(
  pe,
  phase_channel = 1L,
  amp_channel = NULL,
  phase_band = c(4, 8),
  amp_band = c(30, 80),
  method = c("tort", "canolty", "ozkurt", "plv"),
  n_bins = 18L,
  assay_name = NULL
)

Arguments

Value

The PAC result from PhysioCrossModal::phaseAmplitudeCoupling() (a list with pac and, for "tort", the phase-amplitude distribution).

References

Tort et al. 2010; Canolty et al. 2006.

See Also

eegComodulogram(), eegConnectivityMatrix()

Examples

if (requireNamespace("PhysioCrossModal", quietly = TRUE)) {
  pe <- make_eeg(n_time = 5000, n_channels = 4, sr = 250)
  eegPAC(pe, phase_channel = 1, phase_band = c(4, 8), amp_band = c(30, 80))
}

Description

Estimates frequency-resolved directed connectivity with Partial Directed Coherence (Baccala & Sameshima 2001), computed from the frequency-domain coefficient matrix $\bar{A}(f)$ of an MVAR model (PhysioExperiment::mvarFit()). Unlike DTF, PDC reflects only direct channel-to-channel influences, so a purely indirect pathway gives PDC near zero. The (default) generalized PDC weights each row by the inverse residual standard deviation to make the measure scale-invariant (Baccala 2007). PDC satisfies $\sum_i \mathrm{PDC}_{ij}(f)^2 = 1$ for each source $j$ (outflow normalization).

Usage

eegPDC(
  x,
  order = NULL,
  freqs = NULL,
  generalized = TRUE,
  band = NULL,
  method = "ols",
  assay_name = NULL
)

Arguments

Value

The PhysioExperiment with metadata(x)$connectivity set as in eegDTF() (a band-averaged directed matrix, the frequency-resolved array, frequencies, and settings).

References

Baccala, L. A., & Sameshima, K. (2001). Partial directed coherence: a new concept in neural structure determination. Biological Cybernetics, 84(6), 463-474.

See Also

eegDTF(), eegConditionalGC(), eegConnectivityMatrix()

Examples

pe <- make_eeg(n_time = 4000, n_channels = 5, sr = 250)
pe <- eegPDC(pe, order = 5)
S4Vectors::metadata(pe)$connectivity$matrix

Description

Displays the selected continuous EEG channels as a butterfly plot above their Global Field Power (GFP). GFP is the spatial dispersion across the displayed channels at each time point, so its magnitude depends on the selected channels and EEG reference. It is not source-localized power.

Usage

eegPlotButterflyGFP(
  x,
  channels = NULL,
  time_range = NULL,
  show_events = FALSE,
  assay_name = NULL,
  gfp_definition = c("population", "sample"),
  heights = c(3, 1)
)

Arguments

Value

A patchwork object containing two ggplot panels.

Examples

if (requireNamespace("ggplot2", quietly = TRUE) && requireNamespace("patchwork", quietly = TRUE)) {
  pe <- make_eeg(n_time = 1500, n_channels = 19, sr = 250)
  eegPlotButterflyGFP(pe, channels = c("Fz", "Cz", "Pz"))
}

Description

Visualizes EEG connectivity as either a heatmap (matrix) or a circular connectivity plot (circle). The connectivity matrix can be provided directly or read from metadata(x)$connectivity$matrix.

Usage

eegPlotConnectivity(
  x,
  method = c("heatmap", "circle"),
  matrix = NULL,
  threshold = 0,
  labels = NULL,
  palette = "RdBu"
)

Arguments

Value

A ggplot2 object.

Examples

if (requireNamespace("ggplot2", quietly = TRUE)) {
  mat <- matrix(runif(16), 4, 4)
  diag(mat) <- 1
  pe <- make_eeg(n_time = 1000, n_channels = 4, sr = 250)
  eegPlotConnectivity(pe, method = "heatmap", matrix = mat)
}

Description

Draws a deterministic circular view of a connectivity matrix stored in metadata(x)$connectivity$matrix. Symmetric matrices are represented by one edge per unordered channel pair. Asymmetric matrices retain every ordered entry, following the PhysioEEG directed-matrix convention of rows as targets and columns as sources.

Usage

eegPlotConnectogram(
  x,
  order = c("hemisphere", "lobe", "cluster"),
  modules = NULL,
  threshold = NULL,
  bundle = TRUE
)

Arguments

Details

The threshold is a strict absolute display threshold (abs(value) > threshold); it is not a p-value or a corrected significance mask. Hemisphere and lobe are inferred only for recognized 10-20/10-10 labels. Other labels remain "unknown" unless explicit colData columns are supplied. Label tie-breaking uses a stable UTF-8 byte key. Edge identifiers length-prefix both endpoint labels so labels containing the visible " -- " or " -> " separators cannot collide.

Value

A ggplot2 object. Resolved node, edge, path, module-arc, and setting tables are available in attr(plot, "connectogram_data").

See Also

eegPlotConnectivity(), eegConnectivityMatrix()

Examples

if (requireNamespace("ggplot2", quietly = TRUE)) {
  pe <- make_eeg(n_time = 1000, n_channels = 4, sr = 250)
  mat <- matrix(c(
    1, 0.5, 0, -0.4,
    0.5, 1, 0.3, 0,
    0, 0.3, 1, 0.6,
    -0.4, 0, 0.6, 1
  ), 4, 4)
  labels <- SummarizedExperiment::colData(pe)$label
  dimnames(mat) <- list(labels, labels)
  S4Vectors::metadata(pe)$connectivity <- list(
    matrix = mat, method = "coherence", band = c(8, 13)
  )
  eegPlotConnectogram(pe, threshold = 0.2)
}

Description

Plots event-related potential waveforms averaged across epochs, with optional confidence interval ribbons. Supports condition-based comparisons when metadata(x)$conditions is available.

Usage

eegPlotERP(
  x,
  channels = NULL,
  conditions = NULL,
  ci = 0.95,
  show_ci = TRUE,
  epoch_start = 0,
  assay_name = NULL
)

Arguments

Value

A ggplot2 object.

Examples

if (requireNamespace("ggplot2", quietly = TRUE)) {
  pe <- make_eeg_erp(n_epochs = 40, sr = 250)
  eegPlotERP(pe, channels = "Cz")
}

Description

Creates deterministic sagittal, axial, and coronal maximum-intensity projections from source amplitudes with real three-dimensional coordinates. The bundled outline is schematic and is not an MRI, patient anatomy, or a validation of the inverse solution.

Usage

eegPlotGlassBrain(
  x,
  source_data = NULL,
  views = c("sagittal", "axial", "coronal"),
  threshold_pct = 90
)

Arguments

Details

Projection axes are sagittal y-z with depth x, axial x-y with depth z, and coronal x-z with depth y. Free-orientation source estimates are reduced by root-sum-square over orientations at each time and RMS over time. This non-negative summary is not a signed instantaneous current. A fixed 80 by 80 display grid retains the greatest absolute amplitude in each projected bin, with exact ties resolved by the smallest source ID. The affine display transform comes from the complete unthresholded coordinate cloud and does not modify amplitudes. The bundled outline is schematic: the plot is not MRI registration, patient anatomy, or validation of localization accuracy. Bare amplitude vectors and two-dimensional coordinates are rejected.

Value

A patchwork object for normal projections. When fewer than three rows survive thresholding, returns the first requested view as an eegPlotSource() ggplot fallback without applying a second threshold. Immutable "glassbrain_data" attributes retain the resolved sources, panel data, display transform, and threshold settings.

See Also

eegForwardModel(), eegSourceEstimate(), eegBeamformer(), eegPlotSource()

Examples

if (requireNamespace("ggplot2", quietly = TRUE) && requireNamespace("patchwork", quietly = TRUE)) {
  pe <- make_eeg(n_time = 500, n_channels = 19, sr = 250)
  fm <- eegForwardModel(pe, method = "spherical", n_sources = 50)
  localized <- eegSourceEstimate(pe, fm, method = "mne")
  eegPlotGlassBrain(localized)
}

Description

Displays a sleep hypnogram showing sleep stage transitions over time. Stages are ordered with Wake at the top and N3 at the bottom, with a characteristic staircase pattern.

Usage

eegPlotHypnogram(x, stages = NULL, epoch_sec = 30, colors = NULL)

Arguments

Value

A ggplot2 object.

Examples

if (requireNamespace("ggplot2", quietly = TRUE)) {
  pe <- make_eeg_sleep(n_time = 150000, n_channels = 2, sr = 500)
  stages <- eegSleepStage(pe)
  S4Vectors::metadata(pe)$sleep_stages <- stages
  eegPlotHypnogram(pe)
}

Description

Displays ICA component time courses in a stacked layout similar to eegPlotSignal. Optionally shows topographic maps of the mixing matrix weights as a side panel annotation.

Usage

eegPlotICA(
  x,
  components = NULL,
  time_range = NULL,
  show_topography = TRUE,
  assay_name = NULL
)

Arguments

Value

A ggplot2 object.

Examples

if (requireNamespace("ggplot2", quietly = TRUE)) {
  pe <- make_eeg(n_time = 5000, n_channels = 19, sr = 500)
  pe <- eegICA(pe, n_components = 10)
  eegPlotICA(pe, components = 1:5)
}

Description

Displays multi-channel EEG time series in stacked, butterfly, or grid layout. Supports channel selection, time range restriction, and optional event markers.

Usage

eegPlotSignal(
  x,
  channels = NULL,
  time_range = NULL,
  mode = c("stacked", "butterfly", "grid"),
  scale = 1,
  show_events = FALSE,
  assay_name = NULL
)

Arguments

Value

A ggplot2 object.

Examples

if (requireNamespace("ggplot2", quietly = TRUE)) {
  pe <- make_eeg(n_time = 2500, n_channels = 4, sr = 500)
  eegPlotSignal(pe, mode = "stacked")
}

Description

Visualizes source localization results as a 2D scatter plot or flat map projection. Sources are sized and colored by amplitude, with optional thresholding to show only the strongest activations.

Usage

eegPlotSource(
  x,
  source_data = NULL,
  method = c("scatter", "flatmap"),
  threshold_pct = 80
)

Arguments

Value

A ggplot2 object.

Examples

if (requireNamespace("ggplot2", quietly = TRUE) && requireNamespace("patchwork", quietly = TRUE)) {
  pe <- make_eeg(n_time = 1000, n_channels = 19, sr = 250)
  src <- data.frame(x = runif(50, -1, 1), y = runif(50, -1, 1),
                    amplitude = rnorm(50)^2)
  eegPlotSource(pe, source_data = src, method = "scatter")
}

Description

Displays a time-frequency representation of EEG data as a heatmap. It uses an unambiguous stored STFT, Morlet, or ERSP product when available. For a continuous 2D assay, it computes the established sliding-window FFT.

Usage

eegPlotSpectrogram(
  x,
  channel = 1,
  freq_range = NULL,
  time_range = NULL,
  log_power = TRUE,
  palette = "viridis",
  assay_name = NULL,
  mask = NULL,
  mask_alpha = 0.4,
  contour = TRUE
)