scFoundry

scFoundry is a unified, reproducible framework for deploying, running and evaluating single-cell foundation models (scFMs). One command gives you zero-shot embeddings, label transfer on frozen embeddings, supervised fine-tuning, the benchmark metrics of our paper, or representation-geometry probes — for any supported model, in its original container, with its authors' recipe. No per-model environment setup, no code.

It is built on Nextflow: every model runs in a pinned container, every launch is recorded, and the same commands work on a workstation with Docker or on an HPC cluster with Apptainer/Singularity. This repository is the home of scFoundry and of the benchmark described in the accompanying paper.

📖 Documentation: https://svvord.github.io/scFoundry-docs/ — installation, tutorials, the reference for every task and method, and the benchmark results with an interactive explorer.

[2026.08] scFoundry 0.2: pip-installable scfoundry command with workspaces; embed covers the scFMs, PCA, scVI and the batch-integration methods; new transfer task (prototype / kNN / logistic regression / MLP on frozen embeddings); finetune restricted to methods that update parameters; new benchmark and geometry tasks (the manuscript's metrics and representation-geometry probes); revised CellFM, Geneformer, scFoundation, SCimilarity and scPRINT implementations. [2026.03.04] Fine-tuning implementation released. [2026.01.13] Few-shot learning implementation released; scPRINT deployment fixes.

Requirements

Installation

pip install scfoundry                                       # release (PyPI)
pip install git+https://github.com/Svvord/scFoundry.git     # latest from GitHub

Install into the environment that provides nextflow. Full instructions, including the developer install: Installation.

Quick start

scfoundry init my_project && cd my_project    # workspace: nextflow.config, data/, cache/, results/, runs/
scfoundry download --method scgpt             # official checkpoint -> data/model_weights/
scfoundry embed --method scgpt --data cells.h5ad
# -> results/embeddings/scgpt/cells.h5ad   (embedding in adata.X, original obs kept)

Input is an AnnData .h5ad with raw counts over the full transcriptome; see Input data format. Four demo files under data/demo/ satisfy the contract; the Quickstart embeds, scores and annotates them end to end.

Tasks

scfoundry list methods prints the method × task matrix; scfoundry <task> --help the options of a task.

Supported methods

Zero-shot scFMs: Cell2Sentence, CELLama, CellFM, CellPLM, Geneformer, GenePT, LangCell, scBERT, scCello, scFoundation, scGPT, SCimilarity, scPRINT, UCE, and Novae for spatial data. References: PCA, scVI (CELLxGENE Census). Integration: scGPT (integrated), scVI (de novo), Harmony, Seurat CCA, Seurat RPCA.

Containers, pinned versions, default checkpoints and per-method parameters: Supported methods.

Benchmark results

Every method over 26 Tabula Sapiens v2 tissues (548,977 cells), with default settings throughout: Benchmark results and the interactive explorer. The tables are what scfoundry benchmark and scfoundry geometry compute, so your own numbers are directly comparable — see Reproducing the paper.

Citation

If scFoundry or the benchmark is useful for your research, please cite:

Siyu Hou, Penghui Yang, Wenjing Ma, Jinxi Xiang, Jade Xiaoqing Wang, Hui Wan, Ying Ma and Xiang Zhou (2026). Accessible and reproducible deployment reveals the practical boundaries of single-cell foundation models. bioRxiv, https://doi.org/10.64898/2026.01.06.698060 (the revised version with this title replaces the current preprint at this DOI within one to two weeks)

@article{hou2026accessible,
  title = {Accessible and reproducible deployment reveals the practical boundaries of single-cell foundation models},
  author = {Hou, Siyu and Yang, Penghui and Ma, Wenjing and Xiang, Jinxi and Wang, Jade Xiaoqing and Wan, Hui and Ma, Ying and Zhou, Xiang},
  year = {2026},
  publisher = {Cold Spring Harbor Laboratory},
  journal = {bioRxiv},
  doi = {10.64898/2026.01.06.698060},
  url = {https://doi.org/10.64898/2026.01.06.698060}
}

Please also cite the upstream paper of every model whose results you report — links on the citation page.