Imported from quadbio/scembed (
AGENTS.md). Install upstream withnpx skills add quadbio/scembed. Copyright stays with the author.
AGENTS.md — scembed
scembed is a Python package for benchmarking single-cell data integration
methods with scIB metrics. It wraps common integration tools (Harmony,
LIGER, Scanorama, scVI, scANVI, scPoli, ResolVI, scVIVA), drives benchmarks
through scIB metrics, and aggregates W&B sweep results produced via
slurm_sweep.
Trust Order
When sources disagree:
- PR description and changed code
- This file (
AGENTS.md) REVIEW_GUIDE.md- Tests under
tests/ - Public docs in
docs/
This file owns invariants and the where-to-find table. Review-specific
workflow lives in REVIEW_GUIDE.md.
Where To Find What
| Topic | Source of truth |
|---|---|
| Method registry / dispatch | src/scembed/factory.py (get_method_instance) |
| Method base class & embedding-key convention | src/scembed/methods/base.py (BaseIntegrationMethod) |
| CPU-only methods (HVG, LIGER, Scanorama, precomputed) | src/scembed/methods/cpu_methods.py |
| GPU/torch methods (Harmony, scVI, scANVI, scPoli, ResolVI, scVIVA) | src/scembed/methods/gpu_methods.py |
| scIB benchmarking | src/scembed/evaluation.py (IntegrationEvaluator) |
| W&B sweep aggregation | src/scembed/aggregation.py (scIBAggregator) |
| Optional-dependency gating | src/scembed/check.py (check_deps, CHECKERS) |
| Public API surface | src/scembed/__init__.py |
| Contributor guide | docs/contributing.md |
| Usage examples | docs/notebooks/basic_usage.ipynb |
| PR review workflow & risk areas | REVIEW_GUIDE.md |
| Test fixtures | tests/conftest.py |
| Sweep driver | https://github.com/quadbio/slurm_sweep |
Review Guidelines
For GitHub PR reviews, use REVIEW_GUIDE.md as the canonical review workflow
and source of review-specific risk areas, testing checks, and
documentation-impact checks. This file only owns the project invariants and
the source-of-truth map above.
Critical Invariants
- Every integration method subclasses
BaseIntegrationMethodand writes its result intoadata.obsm["X_<name>"], wherename = ClassName.replace("Method", "").lower(). Examples:HarmonyMethod→X_harmony,scVIMethod→X_scvi. - New methods register their dependency keys in
CHECKERS(src/scembed/check.py) and callcheck_deps(...)before importing the optional package. This is what gives users a clear error when an extra is missing. - Optional install extras and the methods they enable:
[cpu]—pyliger,scanorama. Used byLIGERMethod,ScanoramaMethod. (HVGMethodandPrecomputedEmbeddingMethodneed no extra.)[gpu]—harmony-pytorch,scvi-tools,scarches,torch. Used byHarmonyMethod,scVIMethod,scANVIMethod,scVIVAMethod,ResolVIMethod,scPoliMethod.scPoliMethoddepends onscarches, notscvi-tools.[fast-metrics]—faiss-cpu,rapids-singlecell.
- W&B SDK version differences are isolated in helper methods inside
aggregation.py. Don't sprinkle SDK-version checks elsewhere. - Public API is whatever
src/scembed/__init__.pyexports (IntegrationEvaluator,scIBAggregator,get_method_instance,logger,methods). Keep that surface minimal — submodule symbols stay private unless explicitly re-exported. - Tests mirror the module layout:
src/scembed/X/→tests/X/. Method tests live intests/methods/; everything else is flat undertests/.
Development Commands
Python 3.11 and 3.14 are the matrix endpoints (see
[tool.hatch.envs.hatch-test.matrix]).
uv sync # install with default groups
uvx hatch test # run tests on highest matrix Python
uvx hatch test --all # full matrix (3.11, 3.14)
uvx hatch run docs:build # build Sphinx docs
uvx pre-commit run --all-files # lint + format (biome, pyproject-fmt, ruff)