mvpure-py 2.3.2__py3-none-any.whl

mvpure_py/__init__.py

@@ -0,0 +1,3 @@
+from ._version import __version__
+
+__all__ = ["__version__"]

mvpure_py/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '2.3.2'
+__version_tuple__ = version_tuple = (2, 3, 2)
+
+__commit_id__ = commit_id = 'g8b490f09b'

mvpure_py/localizer/__init__.py

@@ -0,0 +1,21 @@
+"""
+References
+----------
+.. [1] 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.
+"""
+from .mvpure_localizer import (
+    localize,
+    Localized,
+    read_localized
+)
+from .localizer_utils import (
+    get_activity_index,
+)
+
+from ._utils import (
+    _check_localize_params,
+    _prepare_localize_params,
+    _check_vertices_and_indices,
+    _check_n_sources_param
+)

mvpure_py/localizer/_utils.py

@@ -0,0 +1,178 @@
+from ..utils import _check_hemi_param
+
+import mne
+import numpy as np
+from termcolor import colored
+import logging
+logging.basicConfig(
+    level=logging.WARNING,
+    format='[%(levelname)s] %(message)s'
+)
+
+
+def _check_localize_params(
+        forward: mne.Forward,
+        leadfield: np.array) -> None:
+    """
+    Checking user input for mvpure_py.localizer.localize() function.
+    """
+    if forward is None and leadfield is None:
+        raise ValueError("One of the parameters 'forward' and 'leadfield' should not be None")
+
+    if forward is not None and leadfield is not None:
+        if np.array_equal(forward['sol']['data'], leadfield):
+            raise ValueError("Both parameters 'forward' and 'leadfield' were specified. "
+                             "They should be equal, but they are not.")
+
+
+def _prepare_localize_params(
+        forward: mne.Forward,
+        leadfield: np.array) -> np.array:
+    """
+    Adjusting input parameters in mvpure_py.localizer.localize() function.
+    Handling forward/leadfield options.
+    """
+    if forward is not None:
+        leadfield = forward["sol"]["data"]
+
+    return leadfield
+
+
+def _check_n_sources_param(n_sources: int) -> None:
+    """
+    Checks type of 'n_sources_to_localize' from mvpure_py.localizer.localize() function.
+    Should be an integer.
+    """
+    if not isinstance(n_sources, (int, np.integer)):
+        raise TypeError(f"Parameter 'n_sources_to_localize' should be an integer. Got type: {type(n_sources)} instead.")
+
+
+def _check_rank(
+        r: int | str | float | list,
+        n_sources_to_localize: int):
+    """
+    Checking correctness of rank optimization ('r') parameter.
+    """
+    if not isinstance(r, (int, np.integer, str, float, np.floating, list)):
+        raise ValueError(f"Optimization parameter 'r' (set to: {r}) should be of type: int, float, string or list. "
+                         f"Got {type(r)} instead.")
+
+    # if 'r' is a list, it should contain integers / floats
+    # and all elements should be equal or less to n_sources_to_localize,
+    if isinstance(r, list):
+        if not all(
+                isinstance(x, (int, np.integer, float, np.floating)) and
+                n_sources_to_localize >= x >= 1
+                for x in r
+        ):
+            raise ValueError("If `r` is a list, all elements should be int or float"
+                             " and equal or less than number of sources to localize.")
+
+    # 'r' should be less or equal to number of sources to localize
+    if isinstance(r, (int, np.integer)) and r > n_sources_to_localize:
+        raise ValueError(f"Optimization parameter 'r' (set to {r}) should be equal or less than"
+                         f" number of sources to localize ('n_sources_to_localize' set to {n_sources_to_localize}).")
+
+    # only option for 'r' as string is 'full'
+    if isinstance(r, str) and r not in ["full"]:
+        raise ValueError(f"If parameter 'r' is a string it should be set to 'full'. "
+                         f"Got {r} instead.")
+
+    # if 'r' == 0, use full rank
+    if isinstance(r, (int, np.integer)) and r == 0:
+        return "full"
+
+    # if 'r' is smaller than zero, take n_sources_to_localize - abs(r)
+    if isinstance(r, (int, np.integer)) and r < 0 and (n_sources_to_localize - abs(r)) > 0:
+        adjusted_value = n_sources_to_localize - abs(r)
+        logging.warning(
+            f"Got rank lower than zero. Taking n_sources_to_localize - {abs(r)} = {adjusted_value} instead."
+        )
+        return adjusted_value
+
+    # if 'r' is smaller than zero and n_sources_to_localize - abs(r) == 0, use full rank
+    if isinstance(r, (int, np.integer)) and r < 0 and (n_sources_to_localize - abs(r)) == 0:
+        return "full"
+
+    # if 'r' is smaller than zero and n_sources_to_localize - abs(r) == 0, raise error
+    if isinstance(r, (int, np.integer)) and r < 0 and (n_sources_to_localize - abs(r)) < 0:
+        raise ValueError(f"Optimization parameter 'r' (set to {r}) should be equal or higher than 0.")
+
+    # if using float and float can not be converted to integer - raise error
+    if isinstance(r, (float, np.floating)) and int(r) != r:
+        raise TypeError(f"Parameter 'r' should be type an integer (if numeric). Got float instead.")
+
+
+def _prepare_localizer_to_use(localizer_to_use: str | list[str]):
+    """
+    Checking and adjusting 'localizer_to_use' parameter from mvpure_py.localizer.localize() function.
+    """
+    # list of all localizers options
+    all_localizers = ['mai', 'mai_mvp']
+    # if localizer_to_use is a string
+    if isinstance(localizer_to_use, str):
+        # if localizer_to_use == 'all' use all localizers
+        if localizer_to_use == 'all':
+            param_localizer_to_use = all_localizers
+        # can be single name of localizers
+        elif localizer_to_use in all_localizers:
+            param_localizer_to_use = [localizer_to_use]
+        # otherwise raise ValueError
+        else:
+            raise ValueError(f"If 'localizer_to_use' is a string it should be either 'all' or "
+                             f"name of one of the localizers to use. Possible options are: {all_localizers}. "
+                             f"Got '{localizer_to_use}' instead.")
+    elif isinstance(localizer_to_use, list):
+        param_localizer_to_use = [loc for loc in localizer_to_use if loc in all_localizers]
+        if len(param_localizer_to_use) < len(localizer_to_use):
+            print(colored(
+                f"WARNING: One or more of localizers' names are not valid."
+                f" Possible options are: {all_localizers}, got {localizer_to_use}.",
+                "yellow"
+            ))
+        if len(param_localizer_to_use) == 0:
+            raise ValueError(f"None of the localizers' name are valid."
+                             f" Possible options are: {all_localizers}, got {localizer_to_use}")
+    else:
+        raise ValueError(f"'localizer_to_use' should be either list of valid localizers' names "
+                         f"or string with single localizer name")
+    return param_localizer_to_use
+
+
+def _define_hemi_based_on_vertices(localized) -> str:
+    """
+    Define hemi (`both`, `rh`, `lh`) based on vertices stored in `localized` object.
+    """
+    if hasattr(localized['stc'], 'lh_vertno') and hasattr(localized['stc'], 'rh_vertno'):
+        hemi = "both"
+    elif hasattr(localized['stc'], 'lh_vertno'):
+        hemi = "lh"
+    elif hasattr(localized['stc'], 'rh_vertno'):
+        hemi = "rh"
+
+    return hemi
+
+
+def _check_norm_param(norm):
+    if norm not in ["max", "sum"]:
+        raise ValueError(f"'norm' can be equal to one of the following: "
+                         f" 'max' (max normalization), 'sum' (L1 normalization. "
+                         f"Got {norm} instead.")
+
+
+def _check_vertices_and_indices(lh_vertices: list, lh_indices: list, rh_vertices: list, rh_indices: list):
+    if (lh_indices is not None and lh_vertices is None) or (lh_indices is None and lh_vertices is not None):
+        raise ValueError(f"Both 'lh_vertices' and 'lh_indices' should be specified. "
+                         f"Got lh_vertices={lh_vertices} and lh_indices={lh_indices}.")
+
+    if (rh_indices is not None and rh_vertices is None) or (rh_indices is None and rh_vertices is not None):
+        raise ValueError(f"Both 'rh_vertices' and 'rh_indices' should be specified. "
+                         f"Got rh_vertices={rh_vertices} and rh_indices={rh_indices}.")
+
+    if lh_vertices is not None and lh_indices is not None and len(lh_vertices) != len(lh_indices):
+        raise ValueError(f"Can not add vertices to Localized object because length of vertices list ({len(lh_vertices)})"
+                         f"does not match length of indices list ({len(lh_indices)}).")
+
+    if rh_vertices is not None and rh_indices is not None and len(rh_vertices) != len(rh_indices):
+        raise ValueError(f"Can not add vertices to Localized object because length of vertices list ({len(rh_vertices)})"
+                         f"does not match length of indices list ({len(rh_indices)}).")

mvpure_py/localizer/localizer_utils.py

@@ -0,0 +1,345 @@
+""" Functions used during sources localization. """
+
+# Authors: Julia Jurkowska, Tomasz Piotrowski
+
+import os
+from typing import List, Optional, Tuple
+
+import numpy as np
+from joblib import Parallel, delayed
+from scipy.linalg import cho_factor, cho_solve, pinv
+from tqdm import tqdm
+
+# Number of threads used by BLAS/LAPACK - ADJUSTABLE
+os.environ["OMP_NUM_THREADS"] = "10"
+
+
+# ============================================================
+# -------- PSD low-rank pseudo-inverse (apply-only) ----------
+# ============================================================
+
+class PSDPinvApply:
+    """
+    Robust pseudo-inverse operator for PSD (possibly low-rank) matrix A:
+        A^+ ≈ U diag(1/lam) U^T  (truncated eigenpairs)
+
+    Use: op.apply(X) = A^+ @ X
+    """
+    __slots__ = ("U", "lam", "cutoff")
+
+    def __init__(self, U: np.ndarray, lam: np.ndarray, cutoff: float):
+        self.U = U
+        self.lam = lam
+        self.cutoff = cutoff
+
+    def apply(self, X: np.ndarray) -> np.ndarray:
+        if self.U.size == 0:
+            return np.zeros_like(X)
+        UtX = self.U.T @ X
+        return self.U @ (UtX / self.lam[:, None])
+
+
+def psd_pinv_operator(A: np.ndarray,
+                      rmax: Optional[int] = None,
+                      eps_rel: float = 1e-10) -> PSDPinvApply:
+    """
+    Build a robust pseudo-inverse *operator* for PSD A (low-rank supported).
+
+    Parameters
+    ----------
+    A : (m,m) PSD matrix (may be singular)
+    rmax : Optional[int]
+        Keep at most rmax eigenpairs (largest).
+    eps_rel : float
+        Keep eigenvalues > eps_rel * max_eig.
+
+    Returns
+    -------
+    PSDPinvApply
+        .apply(X) computes A^+ @ X
+    """
+    As = 0.5 * (A + A.T)  # enforce symmetry numerically
+    lam_all, U_all = np.linalg.eigh(As)  # ascending
+    lam_max = lam_all[-1] if lam_all.size else 0.0
+
+    if lam_max <= 0:
+        return PSDPinvApply(
+            U=np.zeros((A.shape[0], 0), dtype=A.dtype),
+            lam=np.zeros((0,), dtype=A.dtype),
+            cutoff=0.0
+        )
+
+    cutoff = eps_rel * float(lam_max)
+    keep = lam_all > cutoff
+
+    if rmax is not None and int(np.sum(keep)) > int(rmax):
+        idx = np.argsort(lam_all)[-int(rmax):]
+        keep2 = np.zeros_like(keep, dtype=bool)
+        keep2[idx] = True
+        keep = keep & keep2
+
+    lam = lam_all[keep].astype(A.dtype, copy=False)
+    U = U_all[:, keep].astype(A.dtype, copy=False)
+
+    return PSDPinvApply(U=U, lam=lam, cutoff=cutoff)
+
+
+# ============================================================
+# ---------------- Helper: build batch blocks ----------------
+# ============================================================
+
+def _build_blocks_batch(H_sel: np.ndarray,
+                        M_sel: Optional[np.ndarray],
+                        A_M_batch: np.ndarray,
+                        H_batch: np.ndarray) -> np.ndarray:
+    """
+    Construct block matrices for a batch of candidate sources.
+    """
+    k = 0 if M_sel is None else M_sel.shape[0]
+    B = A_M_batch.shape[1]
+    m = k + 1
+    dtype = A_M_batch.dtype
+
+    if k == 0:
+        s_batch = np.sum(A_M_batch * H_batch, axis=0)
+        return s_batch.reshape(B, 1, 1).astype(dtype, copy=False)
+
+    a_batch = H_sel[:, :k].T @ A_M_batch
+    s_batch = np.sum(A_M_batch * H_batch, axis=0)
+
+    blocks = np.empty((B, m, m), dtype=dtype)
+    blocks[:, :k, :k] = M_sel[None, :, :]
+    blocks[:, :k, k:k+1] = a_batch.T.reshape(B, k, 1)
+    blocks[:, k:k+1, :k] = a_batch.T.reshape(B, 1, k)
+    blocks[:, k, k] = s_batch
+
+    return blocks
+
+
+# ============================================================
+# ---------------- Activity index: simplified ----------------
+# ============================================================
+
+def _simple_mai_batch(blocks_G: np.ndarray,
+                      blocks_S: np.ndarray,
+                      current_iter: int) -> np.ndarray:
+    """
+    MAI = trace(G S⁻¹) - current_iter
+    """
+    B, m, _ = blocks_S.shape
+
+    if m == 1:
+        return blocks_G[:, 0, 0] / blocks_S[:, 0, 0] - current_iter
+
+    I = np.eye(m)
+
+    def _process_block(i):
+        try:
+            invS = cho_solve(cho_factor(blocks_S[i], lower=False, check_finite=False),
+                             I, check_finite=False)
+        except np.linalg.LinAlgError:
+            invS = pinv(blocks_S[i])
+
+        return np.trace(blocks_G[i] @ invS) - current_iter
+
+    results = Parallel(n_jobs=-1)(delayed(_process_block)(i) for i in range(B))
+    return np.array(results, dtype=float)
+
+# ============================================================
+# ---------------- Activity index: full versions --------------
+# ============================================================
+
+
+def _mai_mvp_batch(blocks_G: np.ndarray,
+                   blocks_S: np.ndarray,
+                   r: int,
+                   current_iter: int) -> np.ndarray:
+    """
+    MAI-MVP = sum of top-r eigenvalues of (G S⁻¹) - r
+    """
+    B, m, _ = blocks_S.shape
+
+    if current_iter <= r:
+        return _simple_mai_batch(blocks_G, blocks_S, current_iter)
+
+    I = np.eye(m)
+
+    def _process_block(i):
+        if m == 1:
+            return blocks_G[i, 0, 0] / blocks_S[i, 0, 0] - r
+
+        try:
+            invS = cho_solve(cho_factor(blocks_S[i], lower=False, check_finite=False),
+                             I, check_finite=False)
+        except np.linalg.LinAlgError:
+            invS = pinv(blocks_S[i])
+
+        M = blocks_G[i] @ invS
+        s, _ = np.linalg.eig(M)
+        s_sorted = np.sort(s)[::-1].real
+
+        return np.sum(s_sorted[:r]) - r
+
+    results = Parallel(n_jobs=-1)(delayed(_process_block)(i) for i in range(B))
+    return np.array(results, dtype=float)
+
+
+# ============================================================
+# ---------------- Dispatcher: choose function ---------------
+# ============================================================
+
+def _choose_activity_index_batch(localizer_to_use: str):
+    """
+    Return the appropriate activity index function depending on the localizer name.
+    """
+    if localizer_to_use == "mai":
+        return lambda Gs, Ss, Ts, current_iter, r: _simple_mai_batch(Gs, Ss, current_iter)
+    elif localizer_to_use == "mai_mvp":
+        return lambda Gs, Ss, Ts, current_iter, r: _mai_mvp_batch(Gs, Ss, r, current_iter)
+    else:
+        raise ValueError("Allowed: 'mai' and 'mai_mvp'")
+
+
+# ============================================================
+# ---------------- Main function -----------------------------
+# ============================================================
+
+def get_activity_index(localizer_to_use: str,
+                       H: np.ndarray,
+                       R: np.ndarray,
+                       N: np.ndarray,
+                       n_sources_to_localize: int,
+                       r: int,
+                       batch_size: int = 16384,
+                       show_progress: bool = True
+                       ) -> Tuple[List[int], np.ndarray, int, np.ndarray]:
+    """
+    Greedy source localization algorithm.
+    """
+
+    # --------------------------------------------------------
+    # Robust precompute for PSD low-rank R and N (NO Cholesky)
+    # --------------------------------------------------------
+    # A_R  = R^+ H
+    # A_N  = N^+ H
+    # A_TR = R^+ N R^+ H   (same object as: pinv(R) @ N @ pinv(R) @ H)
+    # --------------------------------------------------------
+
+    R_pinv = psd_pinv_operator(R, rmax=None, eps_rel=1e-10)
+    N_pinv = psd_pinv_operator(N, rmax=None, eps_rel=1e-10)
+
+    A_R = R_pinv.apply(H)
+    A_N = N_pinv.apply(H)
+    A_TR = R_pinv.apply(N @ A_R)
+
+    # Initialization
+    n_channels, n_sources = H.shape
+    H_sel = np.zeros((n_channels, n_sources_to_localize), dtype=H.dtype)
+    S_sel = G_sel = T_sel = None
+    index_max: List[int] = []
+    act_values: List[float] = []
+
+    func = _choose_activity_index_batch(localizer_to_use)
+    selected_mask = np.zeros(n_sources, dtype=bool)
+    all_indices = np.arange(n_sources, dtype=int)
+
+    need_G = ("mai" in localizer_to_use) or (localizer_to_use == "mpz_mvp")
+    need_T = ("mpz" in localizer_to_use)
+
+    # Greedy selection loop
+    for outer_iter in range(n_sources_to_localize):
+        best_val = -np.inf
+        best_idx = None
+
+        if show_progress:
+            pbar = tqdm(total=n_sources, desc=f"iter {outer_iter+1}/{n_sources_to_localize}")
+
+        # Process candidates in batches
+        for start in range(0, n_sources, batch_size):
+            end = min(n_sources, start + batch_size)
+            batch_idx = all_indices[start:end]
+            valid = ~selected_mask[batch_idx]
+            if not np.any(valid):
+                if show_progress:
+                    pbar.update(end - start)
+                continue
+            batch_idx = batch_idx[valid]
+
+            # Build block structures
+            A_R_batch = A_R[:, batch_idx]
+            H_batch = H[:, batch_idx]
+            blocks_S = _build_blocks_batch(H_sel[:, :len(index_max)], S_sel, A_R_batch, H_batch)
+
+            if need_G:
+                A_N_batch = A_N[:, batch_idx]
+                blocks_G = _build_blocks_batch(H_sel[:, :len(index_max)], G_sel, A_N_batch, H_batch)
+            else:
+                blocks_G = np.zeros_like(blocks_S)
+
+            if need_T:
+                A_TR_batch = A_TR[:, batch_idx]
+                blocks_T = _build_blocks_batch(H_sel[:, :len(index_max)], T_sel, A_TR_batch, H_batch)
+            else:
+                blocks_T = np.zeros_like(blocks_S)
+
+            # Compute activity index values for the batch
+            vals = func(blocks_G, blocks_S, blocks_T, current_iter=outer_iter + 1, r=r)
+            local_best_idx = int(np.argmax(vals))
+            local_best_val = float(vals[local_best_idx])
+
+            # Update global best
+            if local_best_val > best_val:
+                best_val = local_best_val
+                best_idx = int(batch_idx[local_best_idx])
+
+            if show_progress:
+                pbar.update(end - start)
+
+        if show_progress:
+            pbar.close()
+
+        if best_idx is None:
+            break
+
+        # Save chosen index and its value
+        index_max.append(best_idx)
+        act_values.append(float(best_val))
+        sel_pos = len(index_max) - 1
+        H_sel[:, sel_pos:sel_pos+1] = H[:, best_idx:best_idx+1]
+        selected_mask[best_idx] = True
+
+        # Incrementally update block matrices S_sel / G_sel / T_sel
+        aR_chosen = A_R[:, best_idx:best_idx+1]
+        S_sel = _build_blocks_batch(H_sel[:, :sel_pos+1], S_sel, aR_chosen,
+                                    H[:, best_idx:best_idx+1])[0]
+
+        if need_G:
+            aN_chosen = A_N[:, best_idx:best_idx+1]
+            G_sel = _build_blocks_batch(H_sel[:, :sel_pos+1], G_sel, aN_chosen,
+                                        H[:, best_idx:best_idx+1])[0]
+
+        if need_T:
+            aTR_chosen = A_TR[:, best_idx:best_idx+1]
+            T_sel = _build_blocks_batch(H_sel[:, :sel_pos+1], T_sel, aTR_chosen,
+                                        H[:, best_idx:best_idx+1])[0]
+
+    # Collect selected sources
+    # Sort and permute act_values to match sorted indices, so the returned tuple is internally self-consistent
+    if index_max:
+        sort_perm = np.argsort(index_max)
+        sorted_sources = [index_max[i] for i in sort_perm]
+        H_res = H[:, sorted_sources].copy()
+        act_values_sorted = np.array(act_values, dtype=float)[sort_perm]
+    else:
+        sorted_sources = []
+        H_res = np.zeros((n_channels, 0), dtype=H.dtype)
+        act_values_sorted = np.array([], dtype=float)
+
+    # Final summary
+    print("\n[Activity Index Result]")
+    print(f"  Selected indices (greedy discovery order): {index_max}")
+    print(f"  Selected indices (sorted, matches H_res columns): {sorted_sources}")
+    print(f"  Index max values (sorted to match H_res/sorted_sources): {act_values_sorted}")
+    print(f"  Rank parameter (r): {r}\n")
+
+    return sorted_sources, act_values_sorted, r, H_res