/celltypist-cell-annotation

name: "celltypist-cell-annotation"
description: "Automated scRNA-seq cell type annotation via pre-trained logistic regression. 45+ models: immune, gut, lung, brain, fetal, cancer microenvironments. Input normalized AnnData; outputs per-cell labels, majority-vote cluster labels, confidence scores. Use for fast, reference-backed annotation without manual marker inspection; read cell-type-annotation first."
license: "MIT"

CellTypist Cell Type Annotation

Overview

CellTypist is an automated cell type classifier for single-cell RNA-seq data built on logistic regression models trained on curated reference atlases. Given a normalized AnnData object, it predicts cell type labels at the single-cell level and optionally applies majority voting within user-defined clusters to produce consensus, biologically coherent annotations. The tool ships with 45+ ready-to-use models spanning pan-immune, organ-specific, and developmental contexts, and supports training custom models from labeled data.

When to Use

• Annotating PBMC, whole-blood, lymph node, or other immune cell datasets using a single standardized reference model
• Generating a first-pass cell type annotation before manual curation with canonical marker genes
• Annotating cluster-level cell types in published or in-house datasets using majority voting to smooth noisy per-cell predictions
• Comparing annotation results across multiple tissue-specific models to determine the most biologically relevant reference
• Training a custom CellTypist model from a labeled reference dataset for a tissue or species not covered by pre-built models
• Quantifying annotation confidence to flag low-certainty cells (confidence score < 0.5) for manual review or exclusion
• Use **omics-plotting** SKILL for generic result-table figures; UMAP/dotplot annotation views use scanpy `sc.pl.*`
• Use **scVI/scANVI** (scvi-tools-single-cell) instead when you need probabilistic label transfer with batch correction and uncertainty quantification via a variational autoencoder
• Use **popV** (popv-cell-annotation) instead when you want ensemble consensus from 10+ methods including deep learning and KNN-based approaches

Prerequisites

• **Python packages** (pre-installed in the runtime): `celltypist>=1.6`, `scanpy>=1.9`, `anndata`
• **Data requirements**: AnnData with normalized, log1p-transformed counts in `adata.X` (10,000 UMIs per cell target sum). Raw counts must be normalized before calling CellTypist
• **Environment**: Python 3.8+; 8 GB RAM sufficient for most datasets; internet access required to download the selected model(s) on first use
• **Model download**: download the model for the data (Step 3). Loading a model by name, so download the chosen one first

Pre-flight Interview

Settle these with the user before writing any analysis code.

decisions:
  - id: D1
    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: D2
    param: tissueContext
    kind: required
    source: user
    ask: "Which tissue, and in what state (healthy, fetal, diseased, cultured, perturbed)?"
    default: null

  - id: D3
    param: model
    kind: optional
    source: literature
    ask: "Which model or reference matches this tissue and state?"
    default: "best match for the stated tissue and state"
    skip_if: "markers-only annotation"

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

  - id: D5
    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: D6
    param: labelGranularity
    kind: required
    source: user
    ask: "Name broad lineages, or subtypes and activation states within them?"
    default: null

  - id: D7
    param: majorityVoting
    kind: required
    source: user
    ask: "Label each cell, or take a consensus per cluster?"
    default: "per-cell; voting once clusters are trusted"

  - id: D8
    param: clusteringKey
    kind: derived
    source: upstream
    depends_on: [D7]
    ask: "Which clustering is the consensus taken over?"
    default: "upstream clustering"
    skip_if: "no majority voting"

  - id: D9
    param: assignmentThreshold
    kind: required
    source: user
    ask: "Label every cell, or leave uncertain cells unassigned?"
    default: "best match for every cell"

  - id: D10
    param: minClusterProportion
    kind: optional
    source: user
    depends_on: [D7]
    ask: "What fraction of a cluster must agree to apply the consensus?"
    default: "no minimum"
    skip_if: "no majority voting"

D1-D6 match `cell-type-annotation` word for word; ask each once. If D1 is markers only, use that skill instead. Check D3 against D2: a mismatched model still labels every cell confidently, and only the D4 marker check catches it.

Quick Start

Minimal pipeline — annotate a preprocessed AnnData with the pan-immune model:

import celltypist
import scanpy as sc
from celltypist import models

# Load a preprocessed AnnData (normalized + log1p, Leiden clusters already in adata.obs)
adata = sc.read_h5ad("preprocessed_pbmc.h5ad")

# Download only the model to be used (otherwise an empty cache pulls every model)
models.download_models(model="Immune_All_Low.pkl")

# Run annotation with majority voting across Leiden clusters
predictions = celltypist.annotate(
    adata,
    model="Immune_All_Low.pkl",
    majority_voting=True,
)
adata = predictions.to_adata()

print(adata.obs[["predicted_labels", "majority_voting", "conf_score"]].head(10))
# predicted_labels  majority_voting  conf_score
# CD4