/popv-cell-annotation

name: "popv-cell-annotation"
description: "Consensus cell type annotation: runs 10+ algorithms (KNN-Harmony/BBKNN/Scanorama/scVI, CellTypist, ONCLASS, Random Forest, SCANVI, SVM, XGBoost) on a labeled reference and transfers labels via majority voting. Outputs per-method labels, consensus, agreement score. Use when single-method annotation is insufficient or you need ensemble uncertainty for novel states; to choose between manual markers, CellTypist and popV, read cell-type-annotation first."
license: "BSD-3-Clause"

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"

  - id: D2
    param: tissueContext
    kind: required
    source: user
    ask: "Which tissue is this, and in what state - healthy adult, fetal or developmental, diseased, or perturbed?"
    default: null

  - id: D3
    param: referenceAtlas
    kind: required
    source: literature
    depends_on: [D2]
    ask: "Which annotated reference matches that tissue AND that state?"
    default: null

  - id: D4
    param: referenceLabelColumn
    kind: required
    source: data
    depends_on: [D3]
    ask: "Which column of the reference holds the cell type labels, and at what granularity?"
    default: null

  - id: D5
    param: markerValidation
    kind: required
    source: user
    depends_on: [D1]
    ask: "Should the consensus labels be checked against canonical marker expression before they are accepted?"
    default: "checked - method agreement measures consistency, not correctness"

  - id: D6
    param: validationMarkerPanel
    kind: required
    source: literature
    depends_on: [D2, D5]
    ask: "Which canonical markers should the consensus types be confirmed against?"
    default: null
    skip_if: "marker validation declined"

  - id: D7
    param: consensusThreshold
    kind: required
    source: user
    ask: "How many of the annotation methods must agree before a label is trusted?"
    default: "80% agreement"

  - id: D8
    param: methodSubset
    kind: required
    source: user
    ask: "Run the full method panel, or drop the slow model-based ones?"
    default: "all methods"

  - id: D9
    param: variableGeneCount
    kind: optional
    source: user
    ask: "How many variable genes should the embedding and nearest-neighbour methods use?"
    default: 4000

  - id: D10
    param: trainingEpochs
    kind: optional_conditional
    source: data
    depends_on: [D8]
    ask: "Do the model-based methods need longer training for a large or complex query?"
    default: "50 unsupervised, 20 semi-supervised"
    skip_if: "model-based methods excluded"

  - id: D11
    param: gpuUse
    kind: never_ask
    source: data
    reason: "Falls back to CPU automatically; affects runtime only"
    default: true

D1 is asked even though the user has arrived at an ensemble annotator, because the alternative is not visible from here: manual marker naming and reference transfer fail in opposite directions. If the answer is manual only, this skill is not the tool — see `cell-type-annotation`.

D5 matters more here than it looks. The agreement score in D7 measures whether the methods concur, not whether they are right — several methods sharing one unsuitable reference agree with each other confidently. Mar