mvpure-py 2.3.2__tar.gz

mvpure_py-2.3.2/.github/workflows/pypi_release.yml

@@ -0,0 +1,66 @@
+
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build package
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: python -m pip install --upgrade build
+
+      - name: Build distributions
+        run: python -m build
+
+      - name: Check distributions
+        run: |
+          python -m pip install --upgrade twine
+          python -m twine check dist/*
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v5
+        with:
+          name: python-package-distributions
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+
+    environment:
+      name: pypi
+      url: https://pypi.org/project/mvpure-py/
+
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v6
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish distributions
+        uses: pypa/gh-action-pypi-publish@release/v1

mvpure_py-2.3.2/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.coverage
+build/
+dist/
+.venv/
+entorno/
+/docs/

mvpure_py-2.3.2/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Julia Jurkowska
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

mvpure_py-2.3.2/PKG-INFO

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: mvpure-py
+Version: 2.3.2
+Summary: EEG/MEG multi-source spatial filters and source localization tools
+Author: Julia Jurkowska
+License-Expression: BSD-3-Clause
+Project-URL: Homepage, https://github.com/julia-jurkowska/mvpure-tools
+Project-URL: Repository, https://github.com/julia-jurkowska/mvpure-tools
+Project-URL: Documentation, https://julia-jurkowska.github.io/mvpure-tools/
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: joblib==1.5.1
+Requires-Dist: matplotlib==3.11.2
+Requires-Dist: mne==1.13.2
+Requires-Dist: numpy==2.5.4
+Requires-Dist: pandas==3.1.0
+Requires-Dist: scikit-learn==1.9.1
+Requires-Dist: scipy==1.18.1
+Requires-Dist: termcolor==3.3.0
+Requires-Dist: tqdm==4.67.1
+Requires-Dist: nibabel==5.4.2
+Requires-Dist: PyQt5==5.15.11
+Provides-Extra: test
+Requires-Dist: pytest==9.1.1; extra == "test"
+Dynamic: license-file
+
+# MVPURE-PY package
+<div style="text-align: center;">
+<img width="256" height="256" alt="mvpure_py logo" src="https://github.com/user-attachments/assets/ee880cfc-bb19-486b-be65-8c59f61c9e87" />
+</div>
+
+EEG/MEG Multi-Source Localizers with **mvpure-py**  
+Extends **MNE-Python** with multi-source neural activity indices and spatial filters.  
+Based on *“Multi-Source Neural Activity Indices for EEG/MEG Localization: A Two-Stage Spatial Filtering Framework and Extension to MNE-Python”*.
+
+**Repository:** [GitHub](https://github.com/julia-jurkowska/mvpure-tools) \
+**Tutorial & online docs:** [mvpure_py documentation](https://julia-jurkowska.github.io/mvpure-tools)
+
+---
+
+## Table of Contents
+
+1. [Overview](#overview)
+2. [Features](#features)
+3. [Dependencies](#dependencies)
+4. [Installation](#installation)
+    - From source
+5. [Tutorial & Examples](#tutorial--examples)
+6. [Citation](#citation)
+---
+## Overview
+
+The **mvpure-tools** package implements multi-source neural activity indices for EEG / MEG source localization, extending MNE-Python’s API. It enables improved reconstruction when sources may be correlated, overcoming limitations of single-source beamforming methods (e.g. LCMV) in certain settings.
+
+Key contributions include:
+
+- Algebraic, compact forms for multi-source neural activity indices
+- Seamless integration into MNE-Python workflows (covariance, forward/inverse handling, visualization)
+- A step-by-step tutorial using real EEG data (oddball paradigm, synthetic data)
+
+---
+
+## Features
+
+- Neural activity indices (MAI_MVP) in the multi-source setting
+- Iterative localization algorithms compatible with large candidate source sets
+- Built on top of MNE-Python, so you can combine it with standard EEG / MEG toolchains
+- Tutorial and example scripts included  
+
+---
+## Dependencies
+
+Before installing, make sure you have:
+
+- Python
+- **MNE-Python**
+- NumPy, SciPy
+- (Other dependencies listed in `requirements.txt`)  
+
+---
+
+## Installation
+### From Source (recommended)
+To install from GitHub:
+
+1. Clone the repository
+```bash
+git clone https://github.com/julia-jurkowska/mvpure-tools.git
+cd mvpure-tools
+```
+2. (Optional) create a virtual environment
+
+```bash
+python3 -m venv venv
+source venv/bin/activate
+```
+
+3. Install dependencies
+```bash
+pip install -r requirements.txt
+```
+
+4. Install the package
+```bash
+pip install .
+```
+or for development mode:
+```bash
+pip install -e .
+```
+
+5. Verify installation:
+
+```python
+import mvpure_py
+from mvpure_py import localizer
+```
+---
+## Tutorial & Examples
+See tutorials on documentation site: [documentation](https://julia-jurkowska.github.io/mvpure-tools).
+
+The tutorials walk you through:
+
+1. Preprocessing (filtering, artifact rejection, ICA, epoching)
+2. Estimation of number of sources and rank
+3. Localization of sources using neural activity indices
+4. Reconstruction of time courses
+5. Visualization of estimated sources
+---
+
+## Citation
+
+If you use **mvpure_py** in your work, please cite:
+
+> Jurkowska, J., Dreszer, J., Lewandowska, M., Tolpa, K., Piotrowski, T.,
+> *Multi-source neural activity indices for EEG/MEG localization: A two-stage spatial filtering framework and extension to MNE-Python*, NeuroImage, Volume 339, 2026, 122126, <https://doi.org/10.1016/j.neuroimage.2026.122126>.
+

mvpure_py-2.3.2/README.md

@@ -0,0 +1,111 @@
+# MVPURE-PY package
+<div style="text-align: center;">
+<img width="256" height="256" alt="mvpure_py logo" src="https://github.com/user-attachments/assets/ee880cfc-bb19-486b-be65-8c59f61c9e87" />
+</div>
+
+EEG/MEG Multi-Source Localizers with **mvpure-py**  
+Extends **MNE-Python** with multi-source neural activity indices and spatial filters.  
+Based on *“Multi-Source Neural Activity Indices for EEG/MEG Localization: A Two-Stage Spatial Filtering Framework and Extension to MNE-Python”*.
+
+**Repository:** [GitHub](https://github.com/julia-jurkowska/mvpure-tools) \
+**Tutorial & online docs:** [mvpure_py documentation](https://julia-jurkowska.github.io/mvpure-tools)
+
+---
+
+## Table of Contents
+
+1. [Overview](#overview)
+2. [Features](#features)
+3. [Dependencies](#dependencies)
+4. [Installation](#installation)
+    - From source
+5. [Tutorial & Examples](#tutorial--examples)
+6. [Citation](#citation)
+---
+## Overview
+
+The **mvpure-tools** package implements multi-source neural activity indices for EEG / MEG source localization, extending MNE-Python’s API. It enables improved reconstruction when sources may be correlated, overcoming limitations of single-source beamforming methods (e.g. LCMV) in certain settings.
+
+Key contributions include:
+
+- Algebraic, compact forms for multi-source neural activity indices
+- Seamless integration into MNE-Python workflows (covariance, forward/inverse handling, visualization)
+- A step-by-step tutorial using real EEG data (oddball paradigm, synthetic data)
+
+---
+
+## Features
+
+- Neural activity indices (MAI_MVP) in the multi-source setting
+- Iterative localization algorithms compatible with large candidate source sets
+- Built on top of MNE-Python, so you can combine it with standard EEG / MEG toolchains
+- Tutorial and example scripts included  
+
+---
+## Dependencies
+
+Before installing, make sure you have:
+
+- Python
+- **MNE-Python**
+- NumPy, SciPy
+- (Other dependencies listed in `requirements.txt`)  
+
+---
+
+## Installation
+### From Source (recommended)
+To install from GitHub:
+
+1. Clone the repository
+```bash
+git clone https://github.com/julia-jurkowska/mvpure-tools.git
+cd mvpure-tools
+```
+2. (Optional) create a virtual environment
+
+```bash
+python3 -m venv venv
+source venv/bin/activate
+```
+
+3. Install dependencies
+```bash
+pip install -r requirements.txt
+```
+
+4. Install the package
+```bash
+pip install .
+```
+or for development mode:
+```bash
+pip install -e .
+```
+
+5. Verify installation:
+
+```python
+import mvpure_py
+from mvpure_py import localizer
+```
+---
+## Tutorial & Examples
+See tutorials on documentation site: [documentation](https://julia-jurkowska.github.io/mvpure-tools).
+
+The tutorials walk you through:
+
+1. Preprocessing (filtering, artifact rejection, ICA, epoching)
+2. Estimation of number of sources and rank
+3. Localization of sources using neural activity indices
+4. Reconstruction of time courses
+5. Visualization of estimated sources
+---
+
+## Citation
+
+If you use **mvpure_py** in your work, please cite:
+
+> Jurkowska, J., Dreszer, J., Lewandowska, M., Tolpa, K., Piotrowski, T.,
+> *Multi-source neural activity indices for EEG/MEG localization: A two-stage spatial filtering framework and extension to MNE-Python*, NeuroImage, Volume 339, 2026, 122126, <https://doi.org/10.1016/j.neuroimage.2026.122126>.
+

mvpure_py-2.3.2/mvpure_py/__init__.py

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

mvpure_py-2.3.2/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-2.3.2/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-2.3.2/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)}).")