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>.

