JAX-accelerated Adaptive Mixture Independent Component Analysis for Python.

jamica is a JAX implementation of AMICA (Adaptive Mixture Independent Component Analysis), an algorithm for blind source separation. It is aimed mainly at EEG.

AMICA is one of the strongest methods in the ICA family for EEG decomposition. The original implementation is a Fortran program from UCSD, usually run through MATLAB or EEGLAB. jamica rewrites it in Python on top of JAX, so the same code JIT-compiles and runs on either CPU or GPU, and it works directly with MNE-Python.

Why jamica?

JAX + AMICA = jamica. The name also describes the problem AMICA solves.

Record a jam session with a few microphones. Each one picks up a different blend of the same players. Getting the individual instruments back out of those recordings is blind source separation, which is what ICA does for EEG: electrodes pick up mixtures of cortical, muscular and ocular activity, and the job is to pull them apart again.

A jam is rarely one fixed mixture, though. Players drop in and out. Someone takes a solo. The statistics of what the microphones hear keep shifting. AMICA handles this by fitting several mixture models instead of one, and by learning the shape of each source distribution rather than assuming it. That makes it a good match for data a single stationary ICA model does not describe well.

jamica runs that algorithm on JAX, on CPU or GPU, inside the usual Python scientific stack.

Status: jamica reproduces the Fortran AMICA 1.7 reference on the tested single-model configurations. See Validation.

Highlights

• The AMICA algorithm in Python, JIT-compiled through JAX
• Runs on CPU or GPU without changing your code
• Numerical agreement with the Fortran AMICA 1.7 reference on the tested configurations
• 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

pip install "jamica[jax]"

or, from conda-forge:

conda install -c conda-forge jamica jax

Renamed from amica. Releases up to 0.1.0 were published as amica. That name installed a top-level amica module, which collided with amica-python — an independent implementation of the same algorithm by another author — so the two could not coexist in one environment. Since 0.2.0 this project installs as jamica, and the two can be installed side by side.

For NVIDIA GPUs, take the CUDA build of JAX instead:

pip install "jamica[gpu]"        # JAX with CUDA 12 (Linux only)

The other extras are separate, so you only install what you need:

pip install "jamica[mne]"        # MNE-Python integration, fit_ica()
pip install "jamica[icalabel]"   # ICLabel component classification
pip install "jamica[viz]"        # plotting and density diagnostics
pip install "jamica[all]"        # everything above

From source

For development, or to run the test suite:

git clone https://github.com/snesmaeili/jamica.git
cd jamica
pip install -e ".[dev]"

With uv:

git clone https://github.com/snesmaeili/jamica.git
cd jamica
uv venv && source .venv/bin/activate
uv pip install -e ".[dev]"

Quick Start

from jamica 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:

from jamica import fit_ica

ica = fit_ica(raw)

ica.plot_components()
ica.apply(raw)

For integrations that already whiten and PCA-reduce their data, jamica.amica is the stable single-model solver boundary:

from jamica import amica

_, W, sources, n_iter = amica(
    X_ica,
    whiten=False,
    return_n_iter=True,
    random_state=42,
)

Here X_ica is shaped (n_components, n_samples), sources == W @ X_ica, and JAMICA performs no additional centering, whitening, or PCA. Multi-model adaptive ICA and its model probabilities remain available through the native JAMICA API rather than this conventional-ICA boundary.

See the MNE single-model solver contract for the exact matrix, preprocessing, random-state, and error guarantees.

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/jamica/

Validation

jamica reproduces the Fortran AMICA 1.7 reference on single-model fits: final log-likelihoods, unmixing matrices and adaptive-density parameters agree closely across K=1 and K=3 density terms, under both Newton and natural-gradient updates, and on a 100-iteration audit on real EEG.

Protocols, the patched reference build, comparisons against other AMICA implementations and against Picard, extended Infomax and FastICA, and every figure and table in the manuscript are in jamica-benchmark. Exact scope is in the documentation.

Contributing

Contributions are welcome!

Please read CONTRIBUTING.md before opening a pull request.

Parts of jamica were written with AI assistance; AI_USAGE.md says where, and what it does not change about how the package is verified.

Citation

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

Citation metadata is available in CITATION.cff.

License

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