rERP	EEG visualisation	EEG Simulations	BIDS pipeline	Decode EEG data	Statistical testing

A Julia package to simulate multivariate time series, e.g. model-based ERPs, fMRI activity, pupil dilation etc. UnfoldSim.jl provides multi-channel support via EEG-forward models. Moreover, it is possible to simulate overlapping event-related activity and to add noise of a certain type e.g. Pink noise.

Many tutorials, guides, how-tos and references are available in the documentation!

Installation

Julia

Click to expand

The recommended way to install julia is juliaup.

TL;DR: If you don't want to read the explicit instructions, just copy the following command:

• Windows: winget install julia -s msstore
• Mac/Linux: curl -fsSL https://install.julialang.org | sh

UnfoldSim.jl

using Pkg
Pkg.add("UnfoldSim")

Quickstart

We offer some predefined (EEG) signals to get started.

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

Produces continuous "EEG" with PinkNoise and some overlap between 20 events (2 conditions * 10 levels of the continuous variable).

Slightly longer

All simulation ingredients (design, components, onsets, noise) can be easily modified and you can simply plugin your own!

using UnfoldSim
using Random

# Start by defining the design / events data frame.
design =
    SingleSubjectDesign(; conditions = Dict(:condA => ["levelA", "levelB"])) |>
    d -> RepeatDesign(d, 10)

# Next define a ground truth signal + relation to events/design with Wilkinson formulas.
signal = LinearModelComponent(;
    basis = [0, 0, 0, 0.5, 1, 1, 0.5, 0, 0],
    formula = @formula(0 ~ 1 + condA),
    β = [1, 0.5],
)
# Finally, define some inter-onset distance distribution and noise, and simulate data!
data, events = simulate(
    Random.MersenneTwister(1),
    design,
    signal,
    UniformOnset(; offset = 5, width = 4),
    PinkNoise(),
)    

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.

Contributions

Contributions of any kind are very welcome. Please have a look at CONTRIBUTING.md for guidance on contributing to UnfoldSim.jl.

Contributors

Maanik Marathe 📖 💻

Benedikt Ehinger 🐛 💻 📖 🤔 🚇 🚧 👀 ⚠️ ✅

Luis 🐛 💻 📖 🤔

Judith Schepers 🤔 🐛 📖 ✅ 💻 ⚠️

Vladimir Mikheev 🐛

Manpa Barman 🚇

René Skukies 📖 💻 ⚠️ 🤔 ✅

This project follows the all-contributors specification. Please reach out, if you have contributed to UnfoldSim.jl but we have not listed you as a contributor yet.

Citation

TBA

Acknowledgements

Funded by Deutsche Forschungsgemeinschaft (DFG, German Research Foundation) under Germany´s Excellence Strategy – EXC 2075 – 390740016. Furthermore, the authors thank the International Max Planck Research School for Intelligent Systems (IMPRS-IS) for supporting Judith Schepers.