Source Simulation#

SSIM#

source_simulation.py Module for simulating synthetic brain activity data for source-level measurements.

Specifically simulating event-related potential (ERP)-like signals for use in neuroimaging research (e.g., MEG/EEG source simulation). It supports flexible configuration of ERP waveform properties, source orientation (fixed or free), and trial-based simulation with reproducible randomization.

class calibrain.source_simulation.SourceSimulator(ERP_config=None, logger=None)[source]#

Bases: object

Simulates synthetic brain activity data for source-level measurements.

__init__(ERP_config=None, logger=None)[source]#

Initialize the SourceSimulator with parameters for simulating dipole sources.

Parameters:

  • ERP_config (Optional[Dict[str, Any]]) –

    Configuration dictionary for the ERP simulation parameters. If None, default values are used. Default values include:

    • tmin: -0.5 (start time of the ERP segment in seconds)

    • tmax: 0.5 (end time of the ERP segment in seconds)

    • stim_onset: 0.0 (time of stimulus onset in seconds, relative to the start of the ERP segment)

    • sfreq: 250 (sampling frequency in Hz)

    • fmin: 1 (minimum frequency for the bandpass filter in Hz)

    • fmax: 5 (maximum frequency for the bandpass filter in Hz)

    • amplitude: 1.0 (amplitude of the ERP waveform)

    • random_erp_timing: True (if True, the exact start time and duration of the ERP waveform within the post-stimulus window are randomized)

    • erp_min_length : Optional[int] (minimum length of the ERP waveform in samples; if None, a default value is used)

  • logger (Optional[logging.Logger], optional) – Logger instance, by default None.

simulate(orientation_type='fixed', n_sources=100, nnz=5, n_trials=1, global_seed=42)[source]#

Simulate multiple trials of source time courses.

This function generates synthetic source activity for n_trials trials using ERP-like signals. Each trial uses a unique random seed derived from the provided global_seed for reproducibility.

Parameters:

  • orientation_type (str) – Orientation of the sources, either “fixed” or “free”. Default is “fixed”.

  • n_sources (int) – Total number of sources to simulate. Default is 100.

  • nnz (int) – Number of non-zero (active) sources in each trial. Must be less than or equal to n_sources. Default is 5.

  • n_trials (int) – Number of trials to simulate. Default is 1.

  • global_seed (int) – Seed for the random number generator to ensure reproducibility across trials. Default is 42.

Returns:

  • x_all_trialsnp.ndarray

    Array of shape (n_trials, …) containing simulated source time courses. Shape depends on source orientation: - fixed: (n_trials, n_sources, n_times) - free: (n_trials, n_sources, 3, n_times)

  • active_indices_all_trialsnp.ndarray

    Array of shape (n_trials, nnz) containing indices of active sources per trial.

Return type:

Tuple[np.ndarray, np.ndarray]

calibrain.source_simulation.main()[source]#