R Package: TensorEEG

Package: TensorEEG (Physics-Constrained Tensor Simulation Engine)
Title: Physics-Constrained Tensor EEG Simulation Engine
Version: 0.9.1
Author: Yiming Shen
License: MIT + file LICENSE

Overview

TensorEEG is a comprehensive simulation engine designed to generate physically consistent, high-dimensional EEG data. Unlike statistical noise generators, this package models the underlying biophysics of brain signal generation, including volume conduction, source dynamics, and non-stationary manifold drifts. It produces 3rd-order tensors ($\mathcal{X} \in \mathbb{R}^{T \times C \times K}$) suitable for benchmarking advanced tensor decomposition (CP, PARAFAC2) and Riemannian geometry algorithms.

Key Methodologies (DESCRIPTION)

The package implements a rigorous generative pipeline:

1. Physically Constrained Mixing: Constructs a lead field using spherical geometry and Normalized Laplacian Smoothing to simulate realistic volume conduction.
2. Manifold Drift: Models inter-trial non-stationarity via random walks on the rotation group $SO(S)$, simulating dipole orientation shifts over time.
3. Source Dynamics: Generates task-related potentials using time-warped Gabor wavelets and background activity via structured VAR(2) processes (Alpha/Beta rhythms).
4. Closed-Loop SNR: Implements an energy-based feedback loop to precisely calibrate the Signal-to-Noise Ratio (SNR) despite high-amplitude low-frequency drifts.

Dependency Snapshot

• Imports: expm, signal, stats, graphics, grDevices.
• Suggests: testthat.

Installation & Usage

You can install the development version from GitHub:

# install.packages("devtools")
devtools::install_github("Yiming-S/TensorEEG")

Quick Start

library(TensorEEG)

# 1. Define spectral targets (e.g., 10Hz Alpha, 20Hz Beta)
freqs <- c(10, 12, 10, 10, 20, 20, 22, 20, 10, 20)

# 2. Run simulation (10 trials, 64 channels)
sim_res <- sim_eeg_master(
  n_trials = 10, 
  n_time = 500, 
  n_channels = 64,
  target_freqs = freqs,
  drift_power_ratio = 0.5
)

# 3. Access the generated tensor
# Dimensions: [500 x 64 x 10]
tensor_data <- sim_res$data

View on GitHub