mvpure_py.simulation#

mvpure_py.simulation.simulate#

mvpure_py.simulation.simulate.add_leadfield_indices_info(labels_info: Dict, lh_vert_to_lf: Dict, rh_vert_to_lf: Dict) → Dict[source]#

Add leadfield indices corresponding to selected vertices for each label.

Parameters:

  • labels_info (dict) – Dictionary describing selected vertices for each label.

  • lh_vert_to_lf (dict) – Mapping from left-hemisphere vertex to leadfield index.

  • rh_vert_to_lf (dict) – Mapping from right-hemisphere vertex to leadfield index

Returns:

labels_info – Updated dictionary where each label entry additionally contains a 'leadfield_indices' field listing the leadfield indices corresponding to the selected vertices.

Return type:

dict

mvpure_py.simulation.simulate.add_simulated_epochs_to_stc(X_epochs: ndarray, src: SourceSpaces, n_times: int, lf_subset_indices, tmin: float, sfreq: float, subject: str) → SourceEstimate[source]#

Convert averaged simulated source activity to an MNE Source Estimate.

Parameters:

  • X_epochs (ndarray) – Simulated source activity with shape (n_epochs, n_sources, n_times)

  • src (mne.SourceSpaces) – Source space used in the forward model.

  • n_times (int) – Number of time points.

  • lf_subset_indices (ndarray) – Leadfield indices corresponding to simulated sources.

  • tmin (float) – Start time of the data.

  • sfreq (float) – Sampling frequency

  • subject (str) – Subject name used by MNE.

Returns:

stc_evoked – Source estimate containing the average simulated activity.

Return type:

mne.SourceEstimate

mvpure_py.simulation.simulate.assign_label_to_leadfield_index(labels_info: Dict, lh_vert_to_lf: Dict, rh_vert_to_lf: Dict) → Dict[source]#

Create a mapping from leadfield indices to anatomical labels.

Parameters:

  • labels_info (dict) – Dictionary describing selected vertices for each label.

  • lh_vert_to_lf (dict) – Mapping from left-hemisphere vertex to leadfield index.

  • rh_vert_to_lf (dict) – Mapping from right-hemisphere vertex to leadfield index.

Returns:

lf_to_label – Mapping from leadfield index to label name.

Return type:

dict

mvpure_py.simulation.simulate.erp_waveform(t: ndarray) → ndarray[source]#

Generate a synthetic ERP waveform (P1-N1-P2 complex).

Parameters:

t (ndarray) – Time vector in seconds.

Returns:

waveform – ERP waveform evaluated at times t.

Return type:

ndarray

mvpure_py.simulation.simulate.get_random_vertices(n_vertices_per_label_bg: int, n_vertices_per_poststimuli_label: int, noise_labels: List, poststimuli_labels: List, subject: str, subjects_dir: str, src: SourceSpaces, find_close: bool = False, max_distance_cm: float = 2.0, seed=None) → Dict[source]#

Randomly select cortical vertices from anatomical labels.

Vertices are drawn from FreeSurfer annotation labels and filtered to include only those present in the current source space.

Parameters:

  • n_vertices_per_label_bg (int) – Number of vertices selected per background label.

  • n_vertices_per_poststimuli_label (int) – Number of vertices selected per stimulus-active label.

  • noise_labels (List) – Labels used for activity.

  • poststimuli_labels (List) – Labels generating stimulus-locked activity.

  • subject (str) – Subject name.

  • subjects_dir (str) – FreeSurfer SUBJECTS_DIR.

  • src (mne.SourceSpaces) – Source space used for simulation.

  • find_close (bool) – If True and n_vertices_per_poststimuli_label is at least 2, selected sources are within max_distance_cm.

  • max_distance_cm (float) – Maximum allowed Euclidean distance in centimeters between the first randomly selected vertex and all remaining vertices.

  • seed (int | None) – Random seed for reproducibility.

Returns:

labels_info – Dictionary containing selected vertices and metadata.

Return type:

dict

mvpure_py.simulation.simulate.simulate_mvar_for_dipoles(n_sources: int, n_samples: int, order: int = 6, target_std: float = 1e-08, coupling_strength: float = 0.2, noise_level: float = 1.0, gaussian_filter_sigma: float = 2.0, seed=None) → ndarray[source]#

Simulate multivariate autoregresive (MVAR) signals for cortical dipoles.

A MVAR process is generated with random coeefficients and optional cross-source coupling. The resulting time series are smoothed and scaled to a target physical amplitude.

Parameters:

  • n_sources (int) – Number of simulated sources.

  • n_samples (int) – Number of time samples.

  • order (int) – MVAR order

  • target_std (float) – Target standard deviation of simulated signals.

  • coupling_strength (float) – Scaling factor for cross-source coupling coefficients.

  • noise_level (float) – Innovation noise amplitude.

  • gaussian_filter_sigma (float) – Temporal smoothing applied to each source.

  • seed (int | None) – Random seed.

Returns:

X – Simulated source activity.

Return type:

ndarray, shape (n_sources, n_samples)

mvpure_py.simulation.simulate.simulate_sensor_epochs(X_epochs: ndarray, leadfield: ndarray, lf_subset_indices: ndarray, src: SourceSpaces, tmin: float, sfreq: float, noise_factor: float = 0.1, info: Info = None, seed=None) → EpochsArray[source]#

Project simulated source activity to EEG sensors.

The function inserts simulated sources into the full cortical source space, applied the forward model, and adds sensor noise and slow drift to produce EEG epochs.

Parameters:

  • X_epochs (ndarray) – Source-space activity with shape (n_epochs, n_sources, n_times)

  • leadfield (ndarray) – Forward model matrix mapping sources to sensors.

  • lf_subset_indices (ndarray) – Leadfield indices corresponding to the simulated sources.

  • src (mne.SourceSpaces) – MNE source space used for the forward model.

  • tmin (float) – Epoch start time in seconds.

  • sfreq (float) – Sampling frequency.

  • noise_factor (float) – Scaling factor controlling sensor noise amplitude.

  • info (mne.Info) – MNE measurement info structure for creating EpochsArray.

  • seed (int | None) – Random seed for reproducibility.

Returns:

sim_epochs – Simulated EEG sensor data.

Return type:

mne.EpochsArray

mvpure_py.simulation.simulate.simulate_source_epochs(n_epochs: int, lf_subset_indices: ndarray, n_times: int, poststimuli_mask: ndarray, bg_lf_subset_indices: ndarray, poststimuli_lf_subset_indices: ndarray, lf_to_label: Dict, sfreq: float, erp_factor: float = None, snr_db: float = 10.0, order_bg: int = 6, order: int = 6, target_std_bg: float = 1e-08, target_std: float = 3e-08, coupling_bg: float = 0.1, coupling: float = 0.4, noise_bg: float = 1.0, noise: float = 0.3, gaussian_filter_sigma_bg: float = 1.0, gaussian_filter_sigma: float = 4.0, n_dominant_eigvals: int = 3, seed=None)[source]#

Simulate source-space EEG activity for multiple epochs (n_epochs).

The simulation generates background activity using a multivariate autoregressive (MVAR) process and adds post-stimulus activity within a defined time window. Post-stimulus activity is generated from a low-rank latent MVAR process and projected onto selected cortical sources.

Optionally, an ERP waveform (P1-N1-P2) can be added to the active sources with amplitude and latency jitter.

Parameters:

  • n_epochs (int) – Number of epochs to simulate.

  • lf_subset_indices (array-like) – Leadfield indices corresponding to the simulated sources.

  • n_times (int) – Number of time samples per epoch.

  • poststimuli_mask (ndarray (bool)) – Boolean mask indicating the time window where stimulus-locked activity occurs.

  • bg_lf_subset_indices (ndarray) – Leadfield indices of sources that should contain background activity.

  • poststimuli_lf_subset_indices (array-like) – Leadfield indices of sources that should contain post-stimulus activity.

  • lf_to_label (dict) – Mapping from leadfield index to anatomical label name.

  • sfreq (float) – Sampling frequency in Hz.

  • erp_factor (float | None) – Scaling factor for ERP waveform amplitude. If None, no ERP is added.

  • snr_db (float) – Desired signal-to-noise ratio (in dB) between post-stimulus activity and background activity.

  • order_bg (int) – MVAR order for background activity.

  • order (int) – MVAR order for post-stimulus activity.

  • target_std_bg (float) – Target standard deviation of background source activity (Am).

  • target_std (float) – Target standard deviation of post-stimulus activity (Am).

  • coupling_bg (float) – Cross-source coupling strength for background MVAR model.

  • coupling (float) – Cross-source coupling strength for stimulus-driven MVAR model.

  • noise_bg (float) – Innovation noise amplitude for background activity.

  • noise (float) – Innovation noise amplitude for stimulus-driven activity.

  • gaussian_filter_sigma_bg (float) – Temporal smoothing (Gaussian sigma) for background activity.

  • gaussian_filter_sigma (float) – Temporal smoothing for stimulus activity.

  • n_dominant_eigvals (int) – Dimensionality of latent sources used to generated correlated stimulus-locked activity.

  • seed (int | None) – Random seed for reproducibility.

Returns:

X_epochs – Simulated source-space time series for all epochs.

Return type:

ndarray, shape (n_epochs, n_sources, n_times)

mvpure_py.simulation.simulate.split_vertices(labels_info: Dict, poststimuli_labels: List) → Tuple[List, List][source]#

Separate vertices by hemisphere and by stimulus activity role.

Parameters:

  • labels_info (dict) – Dictionary describing labels and selected vertices.

  • poststimuli_labels (list) – Labels designated as stimulus-active regions.

Returns:

  • noise_vertices with noise activity split into left/right hemisphere.

  • post_vertices (list) – Vertices belonging only to stimulus-active labels.

mvpure_py.simulation.validate#

Validation of results achieved on synthetic data.

mvpure_py.simulation.validate.compare_with_strongest_sources_lcmv(signal, n_sources: int, true_vertices: list[list[int]], forward: Forward, R: Covariance, N: Covariance, reg: float = 0.05, pick_ori=None)[source]#

Identify the strongest sources based on LCMV reconstruction and compare them to ground-truth sources.

Parameters:

  • signal – Sensor space data

  • n_sources (int) – Number of sources to localize.

  • true_vertices (list[list[int]]) – Ground-truth vertices in the format [lh_vertices, rh_vertices].

  • forward (mne.Forward) – Forward solution used for creating ground-truth data.

  • R (mne.Covariance) – Data covariance matrix

  • N (mne.Covariance) – Noise covariance matrix

  • reg (float) – The regularization for the whitened data covariance. Default to 0.05.

  • pick_ori – Orientation specification. Default to None.

mvpure_py.simulation.validate.evaluate_localization_for_each_rank(subject: str, subjects_dir: str, n_sources: int, R: Covariance, N: Covariance, forward: Forward, true_vertices: list[list[int]], localizer_to_use: list | str, plot_correct_sources_by_rank: bool = True, plot_sum_error_by_rank: bool = False, plot_mean_error_by_rank: bool = True, show_progress: bool = True)[source]#

Evaluate source localization performance for different rank parameters.

The function iteratively runs a source localization method for ranks 1 ... n_sources and compared the localized vertices with ground-truth vertices. For each rank, the number of correctly localized sources and localization error metrics are computed.

Parameters:

  • subject (str) – Subject identifier the analysis is performed for

  • subjects_dir (str) – Directory where subject folder is being stored

  • n_sources (int) – Number of sources to localize

  • R (mne.Covariance) – Data covariance matrix

  • N (mne.Covariance) – Noise covariance matrix

  • forward (mne.Forward) – Forward solution used for source localization.

  • true_vertices (list[list[int]]) – Ground-truth vertices in the format [lh_vertices, rh_vertices].

  • localizer_to_use (list | str) – Type of localizer index to use. Options are: ‘mai’, ‘mpz’, ‘mai_mvp’, ‘mpz_mvp’.

  • plot_correct_sources_by_rank (bool, optional) – Whether to plot the number of correctly localized sources per rank. Default is True.

  • plot_sum_error_by_rank (bool, optional) – Whether to plot the sum of localization errors per rank. Default is False.

  • plot_mean_error_by_rank (bool, optional) – Whether to plot the mean localization error per rank. Default is True.

  • show_progress (bool, optional) – Whether to display progress during localization. Default is True.

Returns:

summary_dict – Dictionary summarizing results for each rank. Each entry contains:

  • localized : localization result object

  • n_correctly_localized : int Number of correctly identified vertices.

  • correctly_localized : list[list[int]] Intersection between estimated and true vertices.

  • error_info : dict Localization error statistics returned by localization_error().

Return type:

dict

mvpure_py.simulation.validate.evaluate_reconstruction(summary_dict: dict, signal, sim_stc: SourceEstimate, fwd: Forward, R: Covariance, N: Covariance, reg=0.05, pick_ori=None, rank=None, **kwargs)[source]#

Evaluate reconstruction quality using LCMV beamforming.

For each rank entr in the localization summary, two reconstructions are computed:

  • LCMV using the full forward model

  • LCMV using a forward model restricted to the localized sources.

Reconstruction performance is evaluated using the mean squared error (MSE) between the simulated source activity and the reconstructed activity for the correctly localized vertices.

Parameters:

  • summary_dict (dict) – Localization summary returned by evaluate_localization_for_each_rank().

  • signal (mne.Epochs) – Sensor-space data used for beamforming.

  • sim_stc (mne.SourceEstimate) – Simulated ground-truth source time course.

  • fwd (mne.Forward) – Full forward solution.

  • R (mne.Covariance) – Data covariance

  • N (mne.Covariance) – Noise covariance

  • reg (float, optional) – Regularization parameter for LCMV. Default is 0.05.

  • pick_ori (str | None, optional) – Orientation selection for beamformer weights.

  • rank (int | None, optional) – Rank used in beamformer computation.

  • **kwargs – Additional arguments passed to mne.beamformer.make_lcmv.

mvpure_py.simulation.validate.get_stc_data_for_vertices(stc: SourceEstimate, vertices: list[list[int]])[source]#

Extract source time courses for specific vertices from a SourceEstimate.

Parameters:

  • stc (mne.SourceEstimate) – Source estimate containing source time courses.

  • vertices ([list[list[int]]) – Vertices of interest in the format [lh_vertices, rh_vertices]

Returns:

  • data (ndarray) – Source time courses corresponding to the selected vertices with shape (n_vertices, n_times).

  • indices (ndarray) – Indices of the selected vertices within stc.data.

mvpure_py.simulation.validate.localization_error(vertices_true: list[list[int]], localized_vertices: list[list[int]], src: SourceSpaces) → dict[source]#

Compute localization error between true and estimated source vertices.

The function converts vertex indices to 3D coordinated using the provided source space and computes pairwise Euclidean distances between true and localized sources. The Hungarian algorithm is used to determine the optimal one-to-one assignment that minimizes total distance error.

Parameters:

  • vertices_true (list[list[int]]) – Ground-truth vertices for each hemisphere in the form [lh_vertices, rh_vertices]

  • localized_vertices (list[list[int]]) – Localized vertices for each hemisphere in the form [lh_vertices, rh_vertices]

  • src (mne.SourceSpaces) – Source space used to map vertices to 3D coordinates

Returns:

results – Dictionary containing localization error statistics:

  • mean_error : float Mean distance error (mm).

  • median_error : float Median distance error (mm).

  • sum_error : float Sum of all matched vertex errors (mm).

  • max_error : float Maximum error among matched vertices (mm).

  • min_error : float Minimum error among matched vertices (mm).

  • errors_per_vertex : ndarray Distance error for each matched vertex (mm).

Return type:

dict