Contributing#

Contributing to jamica#

Thank you for your interest in contributing to jamica!

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>/jamica.git
cd jamica

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

Using pip:

pip install -e ".[dev]"

Using uv:

uv pip install -e ".[dev]"

[dev] pulls [test], which brings JAX and the plotting stack, so pytest runs the suite against the shipped backend.

The MNE-Python integration tests skip themselves when MNE is absent, so a plain [dev] install reports a clean run while leaving roughly twenty of them unexecuted. Since that integration is a headline feature, install those extras before trusting a green suite on changes that could touch it:

pip install -e ".[dev,mne,icalabel]"
pytest --run-slow

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#

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

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

AI assistance#

You are welcome to use AI coding assistants. Two requests: understand what you are submitting well enough to defend it in review, and note the assistance with a Co-authored-by: trailer on the commit so the record stays accurate.

AI_USAGE.md describes how assistance has been used in this project and what it does not change about how the package is verified.

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 jamica against other ICA implementations are especially valuable, including:

  • Fortran AMICA 1.7

  • Picard

  • FastICA

  • Infomax

Benchmarking on new EEG or MEG datasets is also encouraged.

Changes to the solver, preprocessing, or an external solver contract must also pass the numerical regression gate:

python scripts/regression_vs_ref.py --backend=cpu

The command checks full-batch, default blocked, and classic E-step fits against the validated pre-optimization baseline in an isolated temporary checkout. It fails on a changed iteration count, non-finite output, relative unmixing error above 1e-4, relative likelihood error above 1e-10, or worst matched component correlation below 0.999999. Use --backend=numpy to repeat the same gate without JAX.

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.