---

name: "cell-type-annotation" description: "scRNA-seq cell type annotation - read before any annotation skills. Chooses and runs the route: name clusters manually from canonical markers (scanpy, runnable code here), transfer labels with CellTypist or a popV/scANVI on a reference, or do both and validate one against other. Covers package availability, tissue- and state-matched references, marker panels, confidence and marker validation of transferred labels, doublets, unresolved clusters. Tool-specific code lives in celltypist/popv-cell-annotation and scvi-tools-single-cell." license: "CC-BY-4.0"

Single-Cell RNA-seq Cell Type Annotation

Routes at a Glance

Choose the route; the tool skills hold the code for each automated route.

| Route | Fits when | Needs | In default sandbox | Code | |-------|-----------|-------|--------------------|------| | A. Manual markers | Well-characterized tissue, small dataset, or no reference matches tissue and state | scanpy | Installed | This skill, Workflow step 4 | | B. CellTypist transfer | A pre-trained model matches tissue and state | celltypist | Installed | celltypist-cell-annotation | | C. Ensemble transfer | You have labelled reference data | popv or scvi-tools | Not installed - install first | popv-cell-annotation, scvi-tools-single-cell | | D. Both, compared, step-wise | Labels feed a biological claim; rare populations | A plus B or C | A + B installed | Workflow steps 4 and 7 |

Spatial data is not covered here: Xenium/MERFISH/CosMx cells go to spatial-transcriptomics-cell-type-annotation, Visium spots to spatial-transcriptomics-deconvolution-cell2location.

Ask the route as D2 in the Pre-flight Interview and say which routes run as-is: route C needs popv or scvi-tools installed first.

Overview

Cell type annotation is the process of assigning biological identities to computationally defined clusters in single-cell RNA-seq data. It is one of the most consequential analytical decisions in a scRNA-seq project: annotation errors propagate into downstream analyses of differential expression, trajectory inference, and cell-cell communication. This skill chooses among routes A-D above and holds the code for route A.

It synthesizes community know-how on CellTypist (Dominguez Conde et al., Science 2022), popV (Luecken et al., Nature Methods 2024), and classical marker-based approaches, following standards established by the Human Cell Atlas project.

Routes A to C run from effort-intensive but transparent (manual) to efficient and scalable (automated). They are not mutually exclusive: route D runs automated transfer to generate hypotheses and validates them with manual marker inspection. For high-stakes biological claims — rare cell types, novel disease states, clinical applications — use route D and resolve discordant labels explicitly before publication.

Key Concepts

Clusters Are Not Cell Types

Leiden/Louvain clusters group transcriptionally similar cells. One type can split across clusters (over-clustering) or two can merge (under-clustering); annotate at the resolution the question needs.

Marker Evidence

The strongest evidence is a canonical marker that also ranks high in this dataset's rank_genes_groups. Data-only markers are hypotheses; single-study markers are supporting evidence. Require at least two co-expressed markers per type.

Reference Match and Confidence

A reference or model is valid only for the tissue and state it was built from; a mismatched one still labels every cell, confidently. Low-confidence cells flag novel types, doublets, or transitional states - review them, do not accept the label.

Label Vocabulary

Use Cell Ontology (CL) names and state the granularity (lineage, type, or state) so labels compare across datasets.

Pre-flight Interview

Settle these with the user before writing any analysis code. The Decision Framework below explains the reasoning; this block is the machine-readable form of it.

decisions:
  - id: D1
    param: tissueContext
    kind: required
    source: user
    ask: "Which tissue, and in what state (healthy, fetal, diseased, cultured, perturbed)?"
    default: null

  - id: D2
    param: annotationStrategy
    kind: required
    source: user
    ask: "Markers (A), a CellTypist model (B), an ensemble on your labelled reference (C), or markers and transfer compared (D)?"
    default: null

  - id: D3
    param: referenceAtlas
    kind: optional
    source: literature
    ask: "Which model or reference matches this tissue and state?"
    default: "best match for the stated tissue and state, named inside the B/C/D route options"
    skip_if: "markers-only annotation"

  - id: D4
    param: markerPanel
    kind: optional
    source: literature
    ask: "Which canonical markers define the expected populations?"
    default: "agent-drafted panel for the tissue and state, listed in the plan"
    skip_if: "label transfer only"

  - id: D5
    param: markerValidation
    kind: optional
    source: user
    ask: "Check assigned labels against canonical markers before accepting them?"
    default: "checked"
    skip_if: "markers-only annotation"

  - id: D6
    param: labelGranularity
    kind: required
    source: user
    ask: "Name broad lineages, or subtypes and activation states within them?"
    default: null

  - id: D7
    param: unresolvedClusters
    kind: optional
    source: user
    ask: "What should happen to clusters that match no expected type - labelled by their top markers, left unassigned, or investigated as possible doublets or artefacts?"
    default: "left unassigned and reported"

  - id: D8
    param: doubletHandling
    kind: optional_conditional
    source: data
    ask: "Clusters co-express two lineages and no doublet flag exists - remove doublets before annotating?"
    default: "run Scrublet per sample when adata.obs has no doublet flag"
    skip_if: "adata.obs already carries a doublet flag from upstream QC"

Ask D1, D2 and D6 together in one round; none depends on another. Skip any the request already answers. D3 and D4 are proposed, not asked: write the matched model into the D2 options (e.g. "B. CellTypist Immune_All_Low") and list the marker panel in the plan. Both are only valid for the tissue and the state they were built from - an adult reference applied to fetal or tumour tissue still labels every cell, confidently and wrongly - so check them against D1 before proposing. D5 defaults to checked because transfer has no way to say "these cells are not in my reference"; markers are what make that visible.

celltypist-cell-annotation and scanpy-scrna-seq repeat the shared decisions word for word, so the question survives whichever skill is read; when several are read, ask each once.

Decision Framework

When planning a cell type annotation strategy, choose the route based on dataset characteristics and scientific context:

Is the tissue and cell type composition well-characterized?
├── YES, standard tissue with clear markers (blood, lung, gut, brain)
│   ├── Dataset < 5,000 cells OR small team experiment
│   │   └── A: Manual marker-based annotation
│   │       (dotplot + violin + UMAP visualization)
│   └── Dataset ≥ 5,000 cells OR high-throughput study
│       ├── Standard tissue with pre-trained atlas available
│       │   └── B: CellTypist automated annotation
│       │       (select tissue-matched model, use majority_voting)
│       └── Need cross-atlas integration or rare cell types
│           └── C: popV ensemble label transfer
│               (requires reference AnnData + tissue label)
└── NO, novel tissue, disease state, or poorly characterized system
    ├── Reference atlas exists for related tissue
    │   └── C: popV ensemble label transfer
    │       (multiple methods + consensus = more robust)
    └── No good reference exists
        └── D: Manual annotation (cautious, exploratory)
            with CellTypist as validation
            (report as "putative" cell types, note limitations)

| Scenario | Recommended Approach | Rationale | |----------|---------------------|-----------| | Small dataset (<5,000 cells), well-characterized tissue | A: Manual markers | Automated tools provide marginal advantage; manual review is faster and more transparent | | Large dataset (>50,000 cells), blood or immune tissue | B: CellTypist with Immune_All_High model | CellTypist has the most complete immune training data; scales without added complexity | | Large dataset, lung or airway tissue | B: CellTypist with Human_Lung_Atlas model | HLCA-trained model provides granular lung-specific annotation | | Novel disease condition or patient-derived samples | C: popV with tissue-matched reference | Ensemble consensus is more robust to distribution shift; produces a method-agreement score | | Integration with published atlas (e.g., HLCA, HBA) | C: popV | Designed for atlas-query integration; maintains label ontology compatibility | | Rare cell types (<1% of dataset) | D: popV + manual inspection | Rare populations benefit from multi-method ensemble; manual inspection catches misannotation | | Fetal or developmental tissue | D: markers + popV with fetal reference | Fetal cell types are distinct from adult; use a matched fetal reference (Tabula Sapiens fetal) | | Mixed or uncertain tissue composition | D: CellTypist, then marker validation | CellTypist provides a quick hypothesis; validate each predicted type with markers | | Benchmark or methods comparison study | D: A, B and C in parallel | Triangulating annotation from multiple strategies increases credibility |

Best Practices

1. Remove doublets before annotation: Scrublet or DoubletFinder should be applied as part of QC, before any clustering or annotation step. Doublets score high on gene count and UMI metrics. Annotating them produces hybrid "cell types" that confuse downstream analyses and inflate the apparent cell type diversity. Apply doublet detection, mark predicted doublets in adata.obs, and exclude them before proceeding to annotation.

2. Visualize canonical markers after any automated annotation: Automated tools, including CellTypist and popV, can be wrong. After obtaining automated labels, always inspect canonical marker expression using a dotplot (sc.pl.dotplot), violin plot (sc.pl.violin), or feature plot on UMAP (sc.pl.umap). If a population labeled "B cell" does not express MS4A1 and CD19, the label is suspect. This step takes 15–30 minutes and catches the most common annotation errors.

3. Use multiple independent methods and compare consensus: No single annotation method is universally superior. Comparing at least two methods (e.g., CellTypist and manual markers, or CellTypist and popV) builds confidence in labels where methods agree and flags cells requiring deeper inspection where they disagree. popV's built-in method-agreement score (number of methods that agree divided by total methods) directly quantifies this; a score below 0.5 suggests the cell may be a novel or ambiguous type.

4. Select reference atlases that match tissue, species, and developmental stage: The most common cause of poor label transfer is biological mismatch between query and reference. An adult lung query dataset should be annotated with an adult lung reference (HLCA), not a pan-tissue reference trained on different proportions of cell types. If the reference uses different developmental stage, health status, or sequencing technology, label transfer accuracy drops significantly. When no perfectly matched reference exists, use popV's ensemble, which is more tolerant of imperfect matches than single-method transfer.

5. Check annotation confidence scores and flag low-confidence cells: Both CellTypist (confidence score, 0–1) and popV (popv_score, fraction of methods agreeing) provide per-cell confidence metrics. Cells with CellTypist confidence below 0.5 or popV score below 0.5 should be flagged f