Skip to content

Installation & Setup

Requirements

Requirement Version
Python >=3.10, <4
Package manager uv (recommended) or pip
OS Linux / macOS (developed and tested on Linux)

Dependencies are exactly pinned in pyproject.toml (numpy==1.26.4, scipy, scanpy, anndata==0.10.8, leidenalg==0.10.2, and others). This is deliberate: the numerical results in these docs are tied to specific versions, and floating-point behaviour across major NumPy or scikit-learn releases is not guaranteed to be identical.

Why pinned versions matter here

The upstream reference implementation leaves all its dependencies unpinned, which makes exact reproduction of its published numbers difficult. Fed-MaxFuse pins everything so a run today matches a run from the thesis.

Install with uv

git clone https://github.com/kbaran1998/fed-maxfuse.git
cd fed-maxfuse/fed-maxfuse

uv sync                 # install runtime dependencies
uv sync --group dev     # add dev tooling (pytest, ruff, pylint, mypy)

Install with pip

python -m venv .venv
source .venv/bin/activate
pip install -e .

Use a virtual environment

The dependency set is large and exactly pinned. Installing into a system Python will almost certainly conflict with something.

Verify the installation

The package exposes a single console entry point, cli:

cli --help

You should see six command groups:

generate     Generate and batch experiment configurations
data         Download benchmark datasets
run          Train and evaluate
preprocess   Prepare datasets for MaxFuse
export       Export notebook images and scripts
analysis     Inspect matchings and embeddings

Run the test suite to confirm the numerical stack works:

uv run pytest              # 345 tests across 20 files
uv run pytest -n auto      # parallel, via pytest-xdist

Download the data

Two benchmark datasets are supported, both published by the MaxFuse authors:

cli data download --type maxfuse    # CITE-seq/PBMC + CODEX/scRNA-seq tonsils
cli data download --type pbmc       # PBMC only
cli data download --type all        # everything
Dataset ID Modalities Cells Linkage
cite_seq_and_pbmc CITE-seq RNA ↔ PBMC protein 10,000 / 10,000 Stronger (177 shared features)
tonsils scRNA-seq ↔ CODEX 12,977 / 178,919 Weak (32 shared features)

Preprocess

MaxFuse needs four matrices: active and shared, per modality. The preprocessing step builds them:

cli preprocess data cite_seq_and_pbmc --out ./data/preprocessed
cli preprocess info cite_seq_and_pbmc          # inspect resulting shapes
cli preprocess labels cite_seq_and_pbmc        # prepare ground-truth labels
cli preprocess distances cite_seq_and_pbmc -v  # precompute distances for evaluation

See Local Preprocessing for what these steps do.

Optional: containers

Experiments in the thesis ran on the Delft AI Cluster (DAIC) under SLURM. Because root access is restricted there, images were built locally with Docker, pushed to the GitHub Container Registry, pulled on the cluster, and executed with Apptainer (formerly Singularity).

docker build -t fed-maxfuse .
apptainer exec docker://ghcr.io/<owner>/fed-maxfuse cli run train federated config.json

Hardware expectations

The dominant cost is the dense cross-modal distance matrix computed per batch pair, plus the linear sum assignment over it.

Dataset Approximate peak memory
cite_seq_and_pbmc (10k × 10k) A few GB
tonsils (12,977 × 178,919) Substantially more — plan for a workstation or cluster node

Evaluation is the memory-hungry half

Unsupervised metrics (MRRE, Steadiness & Cohesiveness) use full distance and rank matrices, scaling as \(O(n^2)\). Datasets above 100,000 cells at 32-bit precision needed at least 37 GB in the thesis experiments. Run training and evaluation as separate jobs; they have very different memory profiles.

Next steps