pAMICA: Adaptive Mixture ICA

Python (PyTorch) implementation of Adaptive Mixture Independent Component Analysis (AMICA) that reproduces the reference Fortran implementation within numerical tolerance, with CPU, NVIDIA GPU (CUDA), and Apple GPU (MLX) support. It targets EEG/EMG blind source separation and is a drop-in replacement for EEGLAB's AMICA: single-model output is written in exactly the reference's on-disk format and loads directly in EEGLAB.

Single-model results match the Fortran reference (Hungarian-matched component correlation 0.9996 on well-determined data, Newton disabled, with the reference agreeing with itself at 0.998); see the documentation for validation details and the backend-selection guide.

Overview

AMICA (Adaptive Mixture ICA) is an advanced blind source separation algorithm that uses adaptive mixtures of independent component analyzers. This implementation provides:

• Multiple source models
• Different PDF types
• Newton optimization
• Component sharing
• Outlier rejection
• Data preprocessing (mean removal, sphering)

Installation

Released versions are on PyPI: uv add pamica (or uv pip install pamica). The development version, with the changes listed as unreleased in the changelog, installs from source; the canonical environment is uv:

git clone https://github.com/sccn/pAMICA.git
cd pAMICA
uv sync                     # install dependencies into a managed venv
uv run pytest               # optional: run the tests

The optional Apple-GPU backend (MLX, Apple Silicon only) installs with the mlx extra: uv sync --extra mlx from source, or uv add "pamica[mlx]".

Usage

pamica exposes a scikit-learn-style estimator backed by the PyTorch natural-gradient EM implementation:

import numpy as np
from pamica import AMICA

# X is (n_channels, n_samples) of real EEG/EMG; float64 gives Fortran parity
model = AMICA(n_models=1, n_mix=3).fit(X)

sources = model.transform(X)       # (n_sources, n_samples)
maps = model.get_sensor_mixing_matrix()  # scalp maps, (n_channels, n_sources)
order = model.variance_order()     # EEGLAB IC order (IC1 = highest variance)

Backends and precision

The wrapper auto-selects a device and computes in float64 for Fortran parity; on a Mac, where the Metal Performance Shaders (MPS) device has no float64, a default fit runs on the CPU.

• CPU and CUDA (float64) are bit-reproducible; use them for parity runs.
• float32 (about 7 significant digits, not parity) is required on the Apple GPUs and modestly faster on CPU; it is not a general speedup, since CUDA is overhead-bound (float32 is about as fast as float64).
• On Apple Silicon the MLX backend is the fastest option and carries the full feature surface (all pdf families, Newton, rejection, EEGLAB export, and Mutual Information Reduction (MIR) diagnostics); select it with backend="mlx" on AMICA or the MNE wrapper AMICAICA (float32 only).

AMICA(device="cuda").fit(X)               # NVIDIA GPU, float64
AMICA(backend="mlx").fit(X)               # Apple GPU, float32 (install the mlx extra)

EEGLAB interoperability

pamica writes results in EEGLAB's AMICA output format, so a run drops into an EEGLAB workflow with no manual re-ordering or sign-flipping:

model.write_amica_output("amicaout")   # gm, W, S, mean, c, alpha, mu, sbeta, rho, ...

mod = loadmodout15('amicaout');   % components in EEGLAB variance order

pamica's defaults follow the compiled amica15 binary (lrate 0.1, Newton off), and EEGLAB's runamica15.m sets its own (lrate 0.05, Newton on). To rerun an EEGLAB decomposition, fit from the input.param that runamica15.m wrote beside its output: AMICA.from_params_file("amicaouttmp/input.param").fit(X). The defaults table lists every setting in the three sources.

Legacy NumPy CLI

The NumPy reference backend keeps a command-line interface, driven by a pamica JSON parameter file or a Fortran input.param:

python -m pamica.numpy_impl.cli params.json --outdir results

See the documentation for the full API, the parameter reference, and the backend-selection and validation guides.

Citation

If you use pamica, please cite it (see CITATION.cff) and the original AMICA method:

Palmer, J. A., Kreutz-Delgado, K., & Makeig, S. (2012). AMICA: An adaptive mixture of independent component analyzers with shared components. Technical report, Swartz Center for Computational Neuroscience, UC San Diego.

License

This project is licensed under the BSD 3-Clause License - see the LICENSE file for details.