A Unified Framework for Domain Adaptation in EEG-based Brain-Computer Interfaces.

Python implementation of DA4BCI — a comprehensive toolkit of domain adaptation methods, distance metrics, and evaluation tools for EEG-based BCI applications. The package provides a unified interface to align EEG distributions across sessions or subjects, mitigating distributional shift and improving model robustness.

Looking for the R version? See DA4BCI.

Requires Python >= 3.9.

pip install git+https://github.com/Yiming-S/DA4BCI-Python.git

git clone https://github.com/Yiming-S/DA4BCI-Python.git
cd DA4BCI-Python
pip install -e ".[dev]"

The -e flag installs in editable mode so changes take effect without reinstalling. The [dev] extra includes testing dependencies (pytest).

• numpy >= 1.21
• scipy >= 1.7
• scikit-learn >= 1.0
• matplotlib >= 3.4
• POT >= 0.8 (Python Optimal Transport)

import numpy as np
from da4bci import domain_adaptation, distance_summary

# Simulate EEG-like source and target features
rng = np.random.default_rng(1)
source = rng.standard_normal((100, 20))
target = rng.standard_normal((100, 20)) + 0.5

# Apply domain adaptation (unified interface)
result = domain_adaptation(source, target, method="coral", control={"lam": 1e-5})
adapted_source = result["weighted_source_data"]
adapted_target = result["target_data"]

# Quantify distribution alignment
ds = distance_summary(adapted_source, adapted_target,
                      include=["MMD", "Energy", "Wasserstein", "Mahalanobis"])

# Or call methods directly
from da4bci import domain_adaptation_coral
result = domain_adaptation_coral(source, target, lam=1e-5)

All methods are dispatched through the unified domain_adaptation() function or can be imported individually.

DA4BCI includes a set of distance metrics for quantitatively assessing the effect of adaptation:

• Euclidean Distance Matrix — efficient pairwise distances between datasets.
• Wasserstein Distance — minimal transport cost between distributions.
• Maximum Mean Discrepancy (MMD) — kernel-based discrepancy, sensitive to subtle shifts.
• Energy Distance — empirical-distribution discrepancy from pairwise distances.
• Mahalanobis Distance — whitening-aware distance with optional shrinkage covariance.

from da4bci import compute_mmd, compute_energy, compute_wasserstein, compute_mahalanobis
from da4bci import evaluate_shift, distance_summary

# Compare before/after adaptation
result = evaluate_shift(source, target, adapted_source, adapted_target)

# Full distance summary
ds = distance_summary(source, target,
                      include=["MMD", "Energy", "Wasserstein", "Mahalanobis"])

For a practical method-selection guide organized by shift type, data representation, supervision level, and risk, see the Algorithm Selection Guide in the R repository (the guidance applies identically to this Python implementation).

Quick rules of thumb:

• Start with SA and CORAL as fast linear baselines.
• If covariance structure dominates, move to PT and ART; keep RD as a lightweight baseline.
• If mismatch looks nonlinear or cluster-wise, try OT.
• If you have reliable source labels and need class-aware refinement, try M3D.

da4bci/
├── methods/          # 10 DA algorithms + unified interface
│   ├── tca.py, sa.py, coral.py, gfk.py, mida.py
│   ├── riemannian.py, art.py, pt.py, ot.py, m3d.py
│   └── __init__.py   # domain_adaptation() dispatcher
├── metrics/
│   ├── kernels.py    # rbf_kernel, sigma_med
│   ├── distance.py   # MMD, Energy, Wasserstein, Mahalanobis
│   └── evaluation.py # evaluate_shift, proxy_a_distance, distance_summary
├── geometry/
│   └── spd.py        # SPD matrix operations (matrix_power, riemannian_mean, log/exp map)
├── preprocessing/
│   ├── alignment.py  # Euclidean alignment for EEG trials
│   ├── weights.py    # KMM reweighting
│   └── label_shift.py
├── detection/
│   └── page_hinkley.py
└── plotting.py       # PCA / t-SNE before/after visualization

Replicating the R package's ParallelTEST experiment: 10 DA methods × 10 distribution-shift scenarios = 100 experiments.

Each experiment generates source and target data (1500 samples × 50 features) from different distribution pairs, applies domain adaptation, and measures distribution alignment via MMD, Energy distance, and Mahalanobis distance.

10 Distribution-Shift Scenarios

Average runtime across all 10 distributions (1500 × 50 data, single run):

Benchmarked on the same data (500 × 50), median of 5 runs:

Python is faster across all methods, with speedups from 1.1× to 20.6×. The advantage grows with data size.

Energy distance reduction % (positive = domain gap reduced, higher is better):

-- indicates the method increased the gap on that distribution (negative reduction).

Mahalanobis distance reduction %:

1. TCA has the most robust Energy reduction across all 10 distributions (73–97%), making it the safest general-purpose choice.
2. ART and PT achieve perfect Mahalanobis alignment (100%) and strong Energy reduction on most distributions, but degrade on heavy-tailed Cauchy data.
3. MIDA excels on structured shifts (mean shift, count data: 97–100% Energy reduction) but struggles with Uniform distributions.
4. CORAL and PT are the fastest (< 1 ms), suitable for real-time BCI applications where latency matters.
5. Cauchy distributions are the hardest scenario — only TCA and MIDA maintain positive Energy reduction.
6. GFK preserves the original distribution by design (near-zero change in all metrics), as it only performs subspace rotation without explicit alignment.

cd benchmark/dist_benchmark
python run_benchmark.py          # full: 10 methods × 10 distributions
python run_benchmark.py --quick  # smoke test: 3 methods × 3 distributions

Results are saved to benchmark/dist_benchmark/results/, including JSON data and before/after PCA scatter plots for all 100 experiments.

pytest tests/ -v    # 148 tests

MIT

• Yiming Shen — yiming.shen001@umb.edu
• David Degras — david.degras@umb.edu