Contributing#

Contributing to amica#

Thank you for your interest in contributing to amica!

We welcome contributions of all kinds, including bug fixes, new features, documentation improvements, tests, benchmarks, and examples.

Getting Started#

1. Fork and Clone#

git clone https://github.com/<your-username>/amica.git
cd amica

2. Create a Virtual Environment#

Using venv:

python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate

or using uv:

uv venv
source .venv/bin/activate

3. Install amica#

Using pip:

pip install -e ".[dev]"

Using uv:

uv pip install -e ".[dev]"

4. Install Pre-commit Hooks#

pre-commit install

This enables automatic formatting, linting, and repository consistency checks before every commit.

Development Workflow#

Create a feature branch:

git checkout -b feature/my-new-feature

Make your changes and add or update tests where appropriate.

Run the full pre-commit suite:

pre-commit run --all-files

Run the test suite:

pytest

Backend Testing#

amica supports multiple computational backends.

NumPy#

pytest

JAX (CPU)#

pytest tests/ --backend=cpu

JAX (GPU)#

Requires CUDA and the GPU dependencies.

pytest tests/ --backend=gpu

To include slow tests:

pytest tests/ --backend=gpu --run-slow

GPU tests are recommended whenever modifying the optimization algorithm or JAX backend.

Documentation#

If your changes affect the documentation, ensure it builds successfully.

cd docs
make html

Nox#

For maintainers and advanced contributors, Nox provides reproducible development sessions.

nox -s tests
nox -s lint
nox -s docs

Code Style#

amica uses:

  • Ruff for linting and formatting

  • pre-commit for automated quality checks

  • NumPy-style docstrings for public APIs

Before opening a pull request, make sure:

  • all tests pass

  • pre-commit passes

  • documentation builds successfully (if affected)

Pull Requests#

Please:

  • write clear commit messages

  • include tests for new functionality

  • update documentation when appropriate

  • reference related issues (for example Fixes #42)

Pull requests should target the main branch.

Bug Reports#

When reporting a bug, please include:

  • a minimal reproducible example

  • expected behavior

  • actual behavior

  • Python version

  • operating system

  • backend (NumPy/JAX CPU/JAX GPU)

Feature Requests#

Feature requests are welcome.

Please describe:

  • the motivation

  • the proposed API or behavior

  • relevant papers or references, if applicable

Benchmarks and Validation#

Contributions that compare amica against other ICA implementations are especially valuable, including:

  • MATLAB AMICA

  • Picard

  • FastICA

  • Infomax

Benchmarking on new EEG or MEG datasets is also encouraged.

Code of Conduct#

By participating in this project, you agree to abide by our Code of Conduct.

Questions#

If you have questions, feel free to open a GitHub issue or discussion.