calibrain.SensorSimulator#

class calibrain.SensorSimulator(logger=None)[source]#

Simulates synthetic sensor-level measurements from source-level activity.

This class performs two steps:

  1. Forward projection (clean signal): y_clean = L * x

  2. Additive Gaussian white noise with controlled SNR level: y_noisy = y_clean + eta * eps, where eps ~ N(0, sigma^2 I)

Supported orientation conventions#

Fixed orientation:

  • x: (n_sources, n_times) [nAm]

  • L: (n_sensors, n_sources) [sensor_unit / nAm]

  • y: (n_sensors, n_times) [sensor_unit]

Free orientation:

  • x: (n_sources, K, n_times) [nAm] (3 components of dipole moment)

  • L: (n_sensors, n_sources, K) [sensor_unit / nAm]

  • y: (n_sensors, n_times) [sensor_unit]

with K = 2 for MEG (tangential components) and K = 3 for EEG (full 3D).

Units#

By default, metadata assumes MEG magnetometers:

  • kind = FIFFV_MEG_CH

  • units = FIFF_UNIT_T

  • unitmult= FIFF_UNITM_F (femto; 1e-15)

These are metadata fields; numerical outputs depend on your L units.

Methods

set_sensor_metadata(*[, kind, units, ...])

Update sensor metadata (FIFF kind/unit/multiplier) atomically.

simulate(x, L[, alpha_SNR, ...])

Simulate sensor data by (1) forward projection and (2) noise addition.
__init__(logger=None)[source]#
Parameters:

logger (logging.Logger, optional) – Logger instance. If None, uses module logger.

set_sensor_metadata(*, kind=None, units=None, unitmult=None, coil_type=None)[source]#

Update sensor metadata (FIFF kind/unit/multiplier) atomically.

Return type:

None

simulate(x, L, alpha_SNR=0.5, sensor_white_noise_std=1.0, seed=42)[source]#

Simulate sensor data by (1) forward projection and (2) noise addition.

Parameters:

  • x (np.ndarray) –

    Source activity:

    • fixed: (n_sources, n_times)

    • free : (n_sources, K, n_times), with K = 2 for MEG (tangential) and K = 3 for EEG (full 3D).

    Typically in nAm for dipole moments.

  • L (np.ndarray) –

    Leadfield:

    • fixed: (n_sensors, n_sources)

    • free : (n_sensors, n_sources, K), with K = 2 for MEG and K = 3 for EEG.

      Units depend on modality and construction, e.g. fT/nAm for MEG or µV/nAm for EEG.

  • alpha_SNR (float) – Noise mixing parameter in [0, 1].

  • sensor_white_noise_std (float) – Base noise standard deviation.

  • seed (int) – Noise seed (used only for sensor noise).

Return type:

Tuple[ndarray, ndarray, ndarray, float]

Returns:

  • y_clean (np.ndarray) – Noiseless sensor measurements, shape (n_sensors, n_times). Units depend on L and x, e.g. fT for MEG or µV for EEG.

  • y_noisy (np.ndarray) – Noisy sensor measurements, shape (n_sensors, n_times). Units depend on L and x, e.g. fT for MEG or µV for EEG.

  • noise (np.ndarray) – Added noise term (eta * eps), shape (n_sensors, n_times).

  • noise_eta (float) – Noise scaling factor eta.