meeg_simulator package#

Submodules#

meeg_simulator.simulator module#

meeg_simulator.simulator.simulate_data(X: ndarray, noise_std: float, n_modes: int, n_subjects: int, tmin: float, tmax: float, sfreq: float, t_win: ndarray, effects: ndarray, effects_amp: ndarray | None = None, spat_cov: ndarray | None = None, ch_type: str | None = 'eeg') → List[ndarray]#

Simulate epoched MEG/EEG data with multivariate patterns.

This function generates simulated EEG/MEG data with predefined experimental effects, allowing for controlled evaluation of analysis methods. Effects are introduced at specified time windows, serving as ground truth signals. The data is structured into epochs, making it compatible with mne.Epochs.

The method used here is based on the approach implemented in SPM’s `DEMO_CVA_RSA.m` function, originally developed by Karl Friston and Peter Zeidman [1]. Our implementation extends their method by incorporating time-resolved effects, allowing for dynamic experimental manipulations over specified time windows.

Parameters:

  • X (array, shape (n_trials, n_experimental_conditions)) – Between-trial design matrix specifying experimental manipulations.

  • noise_std (float) – Standard deviation of additive Gaussian noise (applied before spatial covariance).

  • n_modes (int) – Number of spatial modes (e.g., sensors or components) in the simulated data.

  • n_subjects (int) – Number of subjects to simulate.

  • tmin (float) – Start time (in seconds) of each epoch.

  • tmax (float) – End time (in seconds) of each epoch.

  • sfreq (float) – Sampling frequency in Hz.

  • t_win (array, shape (n_effects, 2)) – Time windows (start, end) in seconds where each experimental effect is nonzero.

  • effects (array, shape (n_effects,)) – Indices of the experimental conditions (columns of X) associated with time-locked effects. Each entry corresponds to a row in t_win.

  • effects_amp (array, shape (n_effects,) | None, optional) – Amplitudes of the effects. Effects are simulated by sampling beta parameters from a normal distribution across channels, with effects_amp defining the variance of the distribution. Default is None (scales are uniform).

  • spat_cov (array, shape (n_modes, n_modes) | None, optional) – Spatial covariance matrix for the simulated data. If None, an identity matrix is used (i.e., no cross-channel correlations).

  • ch_type (str, optional) – Type of simulated channels, e.g., ‘eeg’ or ‘meg’. Default is ‘eeg’.

Returns:

epochs_list – A list of mne.Epochs objects, one per subject (length n_subjects).

Return type:

list of mne.Epochs

Raises:

ValueError – If the number of rows in t_win does not match the length of effects.

Notes

  • This function follows the same methodological principles as DEMO_CVA_RSA.m from SPM, but extends it by adding time-resolved experimental effects.

  • The original implementation in SPM was developed by Karl Friston and Peter Zeidman.

  • The generated data follows an event-related structure, suitable for classification and decoding analyses.

  • Effects are injected into selected experimental conditions based on X.

References

[1]

Friston, K., & Zeidman, P. “DEMO_CVA_RSA.m”, Statistical Parametric Mapping (SPM). Available at: spm/spm

Examples

Simulating a simple dataset with 20 subjects and a single experimental effect:

>>> import numpy as np
>>> from meeg_simulator import simulate_data
>>> X = np.random.randn(100, 2)  # 100 trials, 2 experimental conditions
>>> t_win = np.array([[0.2, 0.5]])  # Effect between 200-500 ms
>>> effects = np.array([1])  # Effect corresponds to second column of X
>>> epochs_list = simulate_data(X, noise_std=0.1, n_modes=64, n_subjects=20,
...                             tmin=-0.2, tmax=0.8, sfreq=250,
...                             t_win=t_win, effects=effects)
>>> print(len(epochs_list))  # Should return 20 subjects

Module contents#