Metadata-Version: 2.4
Name: amica
Version: 0.0.1
Summary: Native Python implementation of AMICA for MNE-Python and scientific EEG workflows.
Author-email: Sina Esmaeili <sina.esmaeili@umontreal.ca>
License: BSD-3-Clause
Project-URL: Homepage, https://github.com/snesmaeili/amica
Project-URL: Documentation, https://snesmaeili.github.io/amica/
Project-URL: Repository, https://github.com/snesmaeili/amica.git
Project-URL: Issues, https://github.com/snesmaeili/amica/issues
Project-URL: Changelog, https://github.com/snesmaeili/amica/blob/main/CHANGELOG.md
Keywords: amica,ica,eeg,mne,neuroscience,blind-source-separation
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.21
Requires-Dist: scipy>=1.7
Provides-Extra: jax
Requires-Dist: jax>=0.4; extra == "jax"
Provides-Extra: gpu
Requires-Dist: jax[cuda12]>=0.4; extra == "gpu"
Provides-Extra: mne
Requires-Dist: mne>=1.0; extra == "mne"
Provides-Extra: icalabel
Requires-Dist: mne-icalabel>=0.4; extra == "icalabel"
Requires-Dist: onnxruntime; extra == "icalabel"
Provides-Extra: viz
Requires-Dist: matplotlib>=3.5; extra == "viz"
Provides-Extra: test
Requires-Dist: pytest>=8.0; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Requires-Dist: pytest-xdist; extra == "test"
Requires-Dist: pytest-timeout; extra == "test"
Requires-Dist: pandas>=2.0; extra == "test"
Requires-Dist: scikit-learn>=1.0; extra == "test"
Requires-Dist: python-picard; extra == "test"
Provides-Extra: docs
Requires-Dist: sphinx>=7.0; extra == "docs"
Requires-Dist: numpydoc; extra == "docs"
Requires-Dist: sphinx-gallery; extra == "docs"
Requires-Dist: pydata-sphinx-theme; extra == "docs"
Requires-Dist: myst-parser; extra == "docs"
Requires-Dist: sphinx-copybutton; extra == "docs"
Requires-Dist: sphinx-design; extra == "docs"
Requires-Dist: towncrier; extra == "docs"
Requires-Dist: linkify-it-py; extra == "docs"
Provides-Extra: dev
Requires-Dist: amica[docs,test]; extra == "dev"
Requires-Dist: pre-commit>=3.0; extra == "dev"
Requires-Dist: ruff>=0.9; extra == "dev"
Requires-Dist: towncrier>=23.0; extra == "dev"
Requires-Dist: nox; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Provides-Extra: release
Requires-Dist: build; extra == "release"
Requires-Dist: twine; extra == "release"
Requires-Dist: towncrier>=23.0; extra == "release"
Provides-Extra: all
Requires-Dist: amica[docs,icalabel,jax,mne,test,viz]; extra == "all"
Dynamic: license-file

# amica

[![CI](https://img.shields.io/github/actions/workflow/status/snesmaeili/amica/ci.yml?branch=main&label=CI)](https://github.com/snesmaeili/amica/actions/workflows/ci.yml)
[![Docs](https://img.shields.io/github/actions/workflow/status/snesmaeili/amica/docs.yml?branch=main&label=docs)](https://snesmaeili.github.io/amica/)
[![Codecov](https://img.shields.io/codecov/c/github/snesmaeili/amica)](https://codecov.io/gh/snesmaeili/amica)
[![PyPI - Version](https://img.shields.io/pypi/v/amica.svg)](https://pypi.org/project/amica/)
[![Python Versions](https://img.shields.io/pypi/pyversions/amica.svg)](https://pypi.org/project/amica/)
[![License](https://img.shields.io/badge/license-BSD--3--Clause-blue.svg)](LICENSE)

> **amica** is a native Python implementation of **AMICA (Adaptive Mixture Independent Component Analysis)**, one of the highest-performing ICA algorithms for EEG source separation.

Originally distributed as a closed-source Fortran executable from UCSD, this implementation of amica provides an open, extensible implementation with optional **JAX acceleration**, seamless **MNE-Python integration**, and a modern Python API for reproducible neuroimaging workflows.

> **Status:** amica is under active development and validation. The implementation already achieves numerical agreement with the original MATLAB AMICA across a broad range of configurations, while documentation and benchmarking continue to expand.

______________________________________________________________________

# Highlights

- Native Python implementation of the AMICA algorithm
- Numerical agreement with the original MATLAB AMICA implementation
- Optional **JAX** backend for CPU and GPU acceleration
- Native integration with **MNE-Python**
- Support for **multi-model AMICA**
- Modern scientific Python API
- Extensive testing and continuous integration
- Fully open source (BSD-3-Clause)

______________________________________________________________________

# Installation

## Using pip

```bash
git clone https://github.com/snesmaeili/amica.git
cd amica
pip install -e .
```

Install optional dependencies:

```bash
pip install -e ".[jax]"
pip install -e ".[mne]"
pip install -e ".[dev]"
pip install -e ".[all]"
```

## Using uv

```bash
git clone https://github.com/snesmaeili/amica.git
cd amica

uv venv
source .venv/bin/activate

uv pip install -e .
```

or

```bash
uv pip install -e ".[all]"
```

______________________________________________________________________

# Quick Start

```python
from amica import Amica, AmicaConfig

config = AmicaConfig(
    max_iter=2000,
    num_mix_comps=3,
)

model = Amica(config, random_state=42)

result = model.fit(data)

sources = model.transform(data)
```

For MNE-Python:

```python
from amica import fit_ica

ica = fit_ica(raw)

ica.plot_components()
ica.apply(raw)
```

______________________________________________________________________

# Examples

Example scripts are available in the `examples/` directory, including:

- MNE-Python integration
- Native AMICA API
- JAX acceleration
- Multi-model AMICA
- HPC / SLURM execution

______________________________________________________________________

# Documentation

Full documentation, API reference, validation experiments, and tutorials are available at

**https://snesmaeili.github.io/amica/**

______________________________________________________________________

# Validation

amica has been validated against the original MATLAB AMICA implementation and achieves numerical agreement across a wide range of configurations.

The documentation contains:

- validation experiments
- numerical parity analyses
- performance benchmarks
- reproducibility instructions

______________________________________________________________________

# Contributing

Contributions are welcome!

Please read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request.

______________________________________________________________________

# Citation

If amica contributes to your research, please cite the original AMICA publications.

Citation metadata is available in
[CITATION.cff](CITATION.cff).

______________________________________________________________________

# License

amica is distributed under the terms of the BSD 3-Clause License.
