/cell-type-annotation

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