GitHub

UnfoldSim.jl Documentation

Welcome to UnfoldSim.jl: a Julia package for simulating multivariate timeseries data with a focus on EEG, especially event-related potentials (ERPs). The user provides four ingredients: 1) an experimental design, with both categorical and continuous variables, 2) event basis functions specified via linear or hierarchical models, 3) an inter-event onset distribution, and 4) a noise specification.

Key features

  • Modularity: Choose or implement different designs, components, onset distributions or noise types
  • Multi-subject & complex experimental designs
  • Multi-channel via EEG-forward models
  • Continuous or epoched data with potentially overlapping signals
  • Potential support for other modalities, e.g. single-voxel fMRI or pupil dilation

Installation

julia> using Pkg; Pkg.add("UnfoldSim")

For more detailed instructions please refer to Installing Julia & UnfoldSim.jl.

Usage example

Start simulating time series data

We offer some predefined (EEG) signals, check them out! For instance, a P1/N170/P300 complex (containing three typical ERP components).

using UnfoldSim
data, events = UnfoldSim.predef_eeg(; n_repeats = 1, noiselevel = 0.8)
Example block output

Or simulate epoched data directly

data, events = UnfoldSim.predef_eeg(; n_repeats = 20, noiselevel = 0.8, return_epoched = true)
Example block output

Where to start: Learning roadmap

1. First steps

📌 Goal: Learn about the simulation workflow and run your first simulation
🔗 Quickstart | Simulate event-related potentials (ERPs)

2. Intermediate topics

📌 Goal: Learn about multi-subject and multi-channel simulations
🔗 Multi-subject simulation | Generate multi channel data

3. Advanced topics

📌 Goal: Learn how to implement your own experimental designs, components, etc.
🔗 Define a new (imbalanced) design | Define a new component (with variable duration and shift) | Use existing experimental designs & onsets in the simulation

Statement of need

EEG researchers often analyze data containing (temporally) overlapping events (e.g. stimulus onset and button press, or consecutive eye-fixations), non-linear effects, and complex experimental designs. For a multitude of reasons, we often need to simulate such kinds of data: Simulated EEG data is useful to test preprocessing and analysis tools, validate statistical methods, illustrate conceptual issues, test toolbox functionalities, and find limitations of traditional analysis workflows. For instance, such simulation tools allow for testing the assumptions of new analysis algorithms and testing their robustness against any violation of these assumptions.