Simulator class reference

class multisim.Simulator(X: DataFrame, effects: List[Dict], noise_std: float, n_channels: int, n_subjects: int, tmin: float, tmax: float, sfreq: float, ch_cov: ndarray | None = None, kern: ndarray | None = None, intersub_noise_std: float = 0.0, random_state: object | None = None)

Simulate epoched MEG/EEG data with multivariate patterns.

This generator follows the general spirit of Friston & Zeidman’s SPM `DEMO_CVA_RSA.m` but adds time-resolved effects so that each experimental manipulation can switch on/off within an epoch.

Parameters:

• X (pandas.DataFrame, shape (n_epochs, n_conditions)) – Trial-by-trial design matrix. Must have named columns.

• effects (list[dict]) –

  Each dict describes one multivariate pattern. Required keys

  Key	Meaning
  condition	Column name in X.
  windows	List of (start, end) time pairs (seconds).
  effect_size	Mahalanobis distance (d′).
  effect_amp	Amplitude of β-weights directly.

  Specify either effect_size or effect_amp, not both.

  One dict → one pattern. To share a pattern across several windows, list them in a single dict. To have different patterns, provide multiple dicts with the same condition.

• noise_std (float) – Standard deviation of additive Gaussian noise

• n_channels (int) – Number of channels (sensors/components).

• n_subjects (int) – Number of subjects.

• tmin (float) – Epoch start and end (seconds).

• tmax (float) – Epoch start and end (seconds).

• sfreq (float) – Sampling frequency (Hz).

• ch_cov (ndarray | None, shape (n_channels, n_channels), default identity) – Channel covariance.

• kern (1-D ndarray | None) – Optional causal temporal kernel

• intersub_noise_std (float, default 0) – SD of between-subject variability in effect amplitude.

• random_state (int | numpy.random.Generator | None) – Seed or generator for reproducibility.

Notes

Mathematical relation between ``effect_size`` and β-amplitudes

For a single pattern v (vector across channels) with amplitude a, noise standard deviation σ and channel covariance Σ, the theoretical Mahalanobis distance between condition centroids is

\[d' = \frac{a}{\sigma} \cdot \sqrt{v^T \Sigma^{-1} v}\]

where \(\sigma\) = noise_std, \(\Sigma\) = ch_cov (channel covariance), and \(v\) = channel pattern (unit vector across channels).

We draw v from a standard normal and normalise it to unit Mahalanobis norm (\(‖v‖_{Σ^{-1}} = 1\)). Therefore the distance simplifies to

\[d' = \frac{a}{\sigma}\]

so the amplitude we must inject is

\[a = d'\sigma\]

If the user supplies effect_amp directly, that value is taken instead and the conversion above is skipped.

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 = pd.DataFrame(np.random.randn(100, 1), columns=["face-object"]) # 100 trials, 1 experimental condition
>>> t_win = np.array([[0.2, 0.5]])  # Effect between 200-500 ms
>>> effects = [
    {"condition": 'face-object',
     "windows": [0.1, 0.3],
     "effect_size": 0.5
    }
]
>>> sims = Simulator(
...   X, noise_std=0.1, n_channels=64, n_subjects=20,
...   tmin=-0.2, tmax=0.8, sfreq=250,
...   t_win=t_win, effects=effects
...   )
>>> sim.summary()  # Should return 20 subjects

Methods

export_to_eeglab([X, mapping, root, ...])	Export the simulated data to EEGLAB format (save to file).
export_to_mne([ch_type, X, mapping, verbose])	Export the simulated data to MNE-Python format.
generate_events([X, mapping])	Generate MNE-compatible events and event_id dictionary from a design matrix.
summary()	Textual summary of the simulated dataset.

export_to_eeglab(X: ndarray = None, mapping: dict = None, root: str = '.', fname_template: str = 'sub-{:02d}.set') → None

Export the simulated data to EEGLAB format (save to file).

Parameters:

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

• root (str) – Directory where the files will be saved. Default is current directory ‘.’.

• fname_template (str) – Filename template for each subject, with a placeholder for the subject index. Default is ‘subject_{:02d}.set’.

Return type:

None

Notes

Requires ‘mne’ and ‘eeglabio’ packages. Each subject’s data will be saved as a separate EEGLAB file.

export_to_mne(ch_type: str = 'eeg', X: ndarray = None, mapping: dict = None, verbose: str = 'ERROR') → list

Export the simulated data to MNE-Python format.

Parameters:

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

• X (np.ndarray, shape (n_trials, n_conditions), optional) – Design matrix to use. If None, defaults to self.X.

• mapping (dict, optional) – Dictionary specifying custom label mapping per condition. Format: {condition_name: {original_value: label, …}, …}

• verbose (string, optional) – Verbosity level for MNE, see https://mne.tools/stable/generated/mne.verbose.html

Returns:

List of MNE-Python EpochsArray objects for each subject.

Return type:

list of mne.EpochsArray

generate_events(X: ndarray = None, mapping: dict = None) → tuple

Generate MNE-compatible events and event_id dictionary from a design matrix.

Parameters:

• X (np.ndarray, shape (n_trials, n_conditions), optional) – Design matrix to use. If None, defaults to self.X.

• cond_names (list of str, optional) – Names of the experimental conditions (columns of X). If None, defaults to [“cond1”, “cond2”, …, “condN”].

• mapping (dict, optional) – Dictionary specifying custom label mapping per condition. Format: {condition_name: {original_value: label, …}, …}

Returns:

• events (np.ndarray, shape (n_trials, 3)) – Array of [onset_sample, 0, event_id] per trial.

• event_id (dict) – Dictionary mapping label string to event integer.

summary() → str

Textual summary of the simulated dataset.