mvpure_py.localizer

mvpure_py.localizer.localizer_utils

Functions used during sources localization.

mvpure_py.localizer.localizer_utils.get_activity_index(localizer_to_use: str, H: ndarray, R: ndarray, N: ndarray, n_sources_to_localize: int, r: int, batch_size: int = 16384, show_progress: bool = True) → Tuple[List[int], ndarray, int, ndarray]

Greedy source localization algorithm.

Parameters:

• localizer_to_use (str) – Which localizer to use: ‘mai’, ‘mpz’, ‘mai_mvp’, ‘mpz_mvp’.

• H (np.ndarray) – Leadfield matrix (channels x sources).

• R (np.ndarray) – Measurement covariance matrix.

• N (np.ndarray) – Noise covariance matrix.

• n_sources_to_localize (int) – Number of sources to select.

• r (int) – Rank parameter.

• batch_size (int) – Number of candidates processed per batch.

• show_progress (bool) – Whether to show a progress bar.

Returns:

• index_max (List[int]) – Indices of selected sources.

• act_values (np.ndarray) – Activity index values for each selected source.

• r (int) – Rank parameter (unchanged).

• H_res (np.ndarray) – Selected columns of H.

mvpure_py.localizer.localizer_utils.suggest_n_sources_and_rank(R: ndarray, N: ndarray, show_plot: bool = True, subject: str = None, n_sources_threshold: float = 1, rank_threshold: float = 1.5, **kwargs) → tuple[int, int]

Automatically propose number of sources to localize and rank based on Proposition 3 in [1].

Parameters:

• R (array-like) – Data covariance matrix

• N (array-like) – Noise covariance matrix

• show_plot (bool) – Whether to display a graph of the eigenvalues of the \(RN^{-1}\) matrix. Default to True.

• subject (str) – Subject name the analysis is performed for. Optional.

• n_sources_threshold (float) – Number of eigenvalues of the \(RN^{-1}\) matrix below this threshold corresponds to the suggested number of sources to localize. Default to 1.0. For more details see Observation 1 in [1].

• rank_threshold (float) – Number of eigenvalues of the \(RN^{-1}\) matrix below this threshold corresponds to the suggested rank optimization parameter. Default to 1.5. For more details see Proposition 3 in [1].

Returns:

• n_sources (int) – Suggested number of sources to localize.

• rank (int) – Suggested rank optimization parameter.

References

mvpure_py.localizer.mvpure_localizer

Localizing sources.

class mvpure_py.localizer.mvpure_localizer.Localized(subject: str, subjects_dir: str, **kwargs)

Bases: dict

Class to handle localized sources.

add_power_of_reconstructed(stc: SourceEstimate = None)

Compute power of reconstructed sources. By default, adds key power_of_reconstructed with power of localized sources. If stc (type: mne.SourceEstimate) has data for specific hemisphere (lh_data/rh_data), computes also power just for given hemisphere.

Parameters:

stc (mne.SourceEstimate) – source estimate for given subject Can be None if key stc already exists in Localized object, then uses source estimate object saved there.

add_stc(stc: SourceEstimate)

Add mne.SourceEstimate to class keys in order to perform power analysis.

Parameters:

stc (mne.SourceEstimate) – source estimate for given subject

add_vertices_info(lh_vertices: list = None, lh_indices: list = None, rh_vertices: list = None, rh_indices: list = None)

Add key vertices that saves the information about:

• hemisphere of vertex [hemi]

• original leadfield index [lf_idx]

• ordinal position of the activity index for given vertex [activity_index_order]

• sub-leadfield index for data of given source [lf_order]

It will be in a form:

self['vertices'] = dict(
    {vertex_number}: dict(
        'hemi': 'lh' | 'rh',
        'lf_idx': {lf_idx},
        'activity_index_order': {activity_index_order},
        'lf_order': {activity_index_order - 1}
    )
)

Note

After using assign_brain_regions() function there will be key ‘brain_region’ with the appropriate brain region assigned based on the atlas.

Parameters:

• lh_vertices (list | None) – vertex numbers of localized sources in the left hemisphere

• lh_indices (list | None) – original leadfield indies of localized sources in the left hemisphere

• rh_vertices (list | None) – vertex numbers of localized sources in the right hemisphere

• rh_indices (list | None) – original leadfield indies of localized sources in the right hemisphere

assign_brain_regions(parc: str)

Assign label from given parcellation parc to each source in source estimate. If requested parcellation is present in FreeSurfer folder for given subject, labels from there are being read. If not code checks presence of ‘fsaverage’ folder in subjects_dir directory and try to read labels from there. If successful, labels are then morphed to given subject.

Parameters:

parc (str) – Name of parcellation to be performed

plot_by_brain_region(hemi: str = 'both', cmap: str = 'PiYG', scale_mapping: bool = True, scale_factor: float = 1.0, save_html: bool = False, parc: str = None, **kwargs)

Visualize positions of localized sources taking into consideration brain region of each vertex.

Note

It is necessary to perform add_vertices_info() before trying to plot brain regions.

Parameters:

• hemi (str (Default to 'both'.)) – Hemisphere which vertex is in

• cmap (str (Default to 'PiYG'.)) – matplotlib colormap to use for plotting

• scale_mapping (bool (Default to True)) – Whether to take into account the order of source locations using the foci scale for visualization (the largest foci corresponds to the first located source etc.).

• scale_factor (float (Default to 1.0)) – Scaling factor in the range [0,1] for the first located source.

• save_html (bool (Default to False)) – Whether to save 3D output plot to html file.

• parc (str (Default to None)) – Name of parcellation to be performed. Needed only if ‘brain_region’ key is not present in Localized[‘vertices’] yet.

plot_localized_brain_regions(hemi: str, parc: str, subjects_dir: str = None, surf: str = 'inflated', cmap: str = 'Reds', none_color: str = 'gainsboro', return_df_info: bool = False, **kwargs)

plot_localized_sources(hemi: str = 'both', color_mapping: bool = True, color: str = 'crimson', cmap: str = 'Reds', scale_mapping: bool = True, scale_factor: float = 1.0, save_html: bool = False, **kwargs)

plot_sources_power(stc: SourceEstimate = None, norm: str = 'max', cmap: str = 'Reds', **kwargs)

save(output_path: str)

Save mvpure_py.Localized object to pickle file.

Parameters:

output_path (str) – Directory where mvpure_py.Localized data should be stored.

mvpure_py.localizer.mvpure_localizer.localize(subject: str, subjects_dir: str, localizer_to_use: str | list, n_sources_to_localize: int, R: ndarray, N: ndarray, forward: Forward = None, leadfield: ndarray = None, r: str | int = 'full') → dict

Localize brain activity.

Parameters:

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

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

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

• n_sources_to_localize (int) – Number of sources to localize

• R (array-like) – Data covariance matrix

• N (array-like) – Noise covariance matrix

• forward (mne.Forward) – The forward operator. Can be None if leadfield has valid value.

• leadfield (array-like) – Leadfield matrix with shape (n_channels, n_sources). Can be None if forward has valid value.

• r (str | int) –

  Optimization parameter.

  • If int, should be equal or less to n_sources_to_localize.

  • If equal to "full": r will be equal to n_sources_to_localize.

Returns:

• mvpure_py.Localized (Instance of mvpure_py.Localized containing information of localizer type, localized)

• sources and their leadfield.

mvpure_py.localizer.mvpure_localizer.read_localized(fname: str) → Localized

Read a mvpure_py.Localized object from pickle file.

Parameters:

fname (str) – Path to file where pickle file with mvpure_py.Localized object is stored

Returns:

mvpure_py.Localized

Return type:

read mvpure_py.Localized object

Module contents

References

[1] (1,2,3)

Jurkowska, J., Dreszer, J., Lewandowska, M., Tolpa, K., & Piotrowski, T. J. (2025). Multi-Source Neural Activity Indices and Spatial Filters for EEG/MEG Inverse Problem: An Extension to MNE-Python. bioRxiv, 2025-09.