popV Multi-Method Cell Type Transfer

popV Multi-Method Cell Type Transfer

Overview

popV (Population Voting for single-cell annotation) annotates a query scRNA-seq dataset by running 10+ independent classification algorithms against a labeled reference atlas and aggregating results via majority voting. Each method produces its own label; the final popv_prediction is the consensus across all methods, and the popv_agreement score quantifies how many methods agree. This ensemble strategy is robust to individual method failures on unusual datasets and provides a principled uncertainty estimate: low agreement highlights novel cell states or annotation gaps.

When to Use

• Annotating a query dataset by transferring labels from a well-curated reference atlas when you want a consensus rather than a single model's judgment
• Identifying novel or ambiguous cell states as cells where methods disagree (low popv_agreement score)
• Benchmarking annotation reliability by comparing per-method labels to detect systematic disagreements
• Annotating large atlas datasets (>100k cells) where batch effects between reference and query are substantial
• Producing annotation for downstream analyses that require high-confidence labels (clinical data, regulatory submissions)
• Use omics-plotting SKILL for confidence bar charts and method-agreement heatmaps from exported tables (UMAPs stay in scanpy sc.pl.*)
• Use CellTypist (celltypist-cell-annotation) instead when speed matters and a pre-trained model matches your tissue; popV is slower because it trains multiple models on your reference
• Use scANVI (scvi-tools-single-cell) instead when you need a single probabilistic deep generative model with formal uncertainty quantification and do not require the ensemble

Prerequisites

• Python packages: popv>=0.6, scanpy>=1.9, anndata, scvi-tools>=1.0, harmonypy, bbknn, celltypist
• Data requirements: Two AnnData objects — a labeled reference (adata_ref) with cell type labels in obs, and an unlabeled query (adata_query). Both must be from the same species and have overlapping gene sets. Raw counts in adata.X (popV applies its own normalization internally)
• Environment: Python 3.9+; GPU recommended for scVI/SCANVI methods (falls back to CPU); 32 GB RAM recommended for >200k reference cells

pip install popv scvi-tools harmonypy bbknn celltypist

Pre-flight Interview

Settle these with the user before writing any analysis code.

decisions:
  - id: D1
    param: annotationStrategy
    kind: required
    source: user
    ask: "Name cell types from canonical markers by hand over the clusters, transfer them from an annotated reference by ensemble consensus, or do both and compare the two?"
    default: "ensemble transfer, then confirm against markers"