scblueprint

Rule-based cell-type annotation for single-cell RNA-seq with automatic resolution optimization

scblueprint is a Python library for reproducible, YAML-driven cell-type annotation of single-cell RNA-seq data. It scores gene signatures, optimizes Leiden clustering resolution, applies correction rules, and provides an explain mode that shows exactly why each cluster received its label.

Features

• YAML blueprints - define cell types with positive/negative markers, colors, and references in a single file
• Automatic resolution - coarse-to-fine Leiden sweep that maximizes biological label diversity
• Correction rules - 4 built-in types (expression threshold, ontogeny override, coexpression required, mutually exclusive) plus custom Python rules
• Explain mode - every cluster label comes with score breakdowns and rule override chains
• Labeling strategies - majority vote or DE-gene overlap for cluster-level assignment
• UMAP sweep - multiprocessing parameter sweep with grid output
• Presets - mouse_cardiac with 30 literature-sourced cardiac cell types
• Built on scanpy - integrates with any scanpy/AnnData workflow

Installation

pip install scblueprint

Quick Start

import scanpy as sc
import scblueprint as scb

adata = sc.read_h5ad("my_data.h5ad")

bp = scb.Blueprint.from_preset("mouse_cardiac")

opt = scb.LeidenOptimizer()
result = opt.find_optimal(adata, bp.signatures, "leiden",
                          negative_markers=bp.negative_markers)
print(f"Best resolution: {result.resolution}")

ann = scb.Annotator(bp)
res = ann.apply(adata, "leiden", "cell_type", de_key="global_de")
print(res.summary())

ev = res.explain("3")
print(f"{ev.final_label}: {ev.score_breakdown}")

For YAML schema, correction rules, strategies and UMAP sweep see docs/usage.md.

API

Examples

6 runnable scripts covering basic annotation, auto-resolution, explain mode, custom rules, UMAP sweep and subpopulation deep dive - see docs/examples.md for the full list.

cd examples && python generate_all.py

Citation

If you use scblueprint in a publication, please cite it:

APA:

dam2452. (2026). scblueprint: Rule-based cell-type annotation for single-cell RNA-seq (Version 0.1.0). https://github.com/dam2452/scblueprint

BibTeX:

@software{scblueprint2026,
  title   = {scblueprint: Rule-based cell-type annotation for single-cell RNA-seq},
  author  = {dam2452},
  year    = {2026},
  version = {0.1.0},
  url     = {https://github.com/dam2452/scblueprint}
}

Contributing

Contributions are welcome! Here's how you can help:

1. Bug reports - Open an issue with a minimal reproducible example
2. Feature requests - Open an issue describing the use case
3. Code contributions - Fork, create a feature branch, and open a pull request
4. New presets - Add a YAML file under scblueprint/presets/ with markers and a test

Development setup

git clone https://github.com/dam2452/scblueprint.git
cd scblueprint
pip install -e ".[dev]"
pytest tests/ -v

License

This project is licensed under MIT - see LICENSE for details.