Cell Annotation & Type Identification

Overview

Cell annotation assigns biological identities (cell types, states) to individual cells based on their transcriptomic profiles. This page provides a comprehensive guide to available tools, helping you choose the right method for your analysis.

Validate the verdict

• Score the confidence, not just the label. Inspect per-cell and per-cluster confidence distributions; keep low-confidence cells as unknown instead of forcing a verdict.
• Re-check canonical markers. Confirm that assigned types re-express their expected marker genes in your own data.
• Cross-examine with reference databases: CellMarker 2.0 PanglaoDB Azimuth · HuBMAP atlases Human Cell Atlas

Quick Reference

🛠️ Hands-On Practice

The walkthrough below takes a QC'd AnnData object and gives every cell a name, end to end: normalize to the exact scale CellTypist expects, run a pretrained immune model with majority voting over Leiden clusters, keep the per-cell probability as a confidence score, cross-examine the labels against a hand-picked marker panel, and leave low-evidence cells honestly marked Unknown. Everything is computational and retrospective — the only evidence used is the count matrix you already have.

Environment & packages

CellTypist is a light logistic-regression classifier and installs cleanly alongside Scanpy. leidenalg supplies the over-clustering used for majority voting; decoupler is optional but convenient for signature-based marker scoring. Keep an R environment on hand only if you want the SingleR cross-check.

# conda / mamba recommended
conda create -n scannot python=3.10 -y
conda activate scannot

pip install scanpy celltypist leidenalg
pip install decoupler            # optional: signature / marker scoring

# optional R cross-check with SingleR
# R: BiocManager::install(c("SingleR", "celldex", "SingleCellExperiment"))

Hardware. CellTypist inference is CPU-only and fast: a 50k-cell dataset annotates in under a minute on a laptop, and 500k cells fit comfortably on a 32–64 GB compute node. Only the foundation-model route (scGPT, UCE, scFoundation fine-tuning) needs a GPU; reference mapping with Azimuth or scArches sits in between.

Data structures & formats

• AnnData (input) — must carry log1p-normalized expression in adata.X; stash the raw integers in adata.layers["counts"] before normalizing so differential expression and doublet tools can still reach them
• CellTypist model (.pkl) — a pickled logistic-regression classifier plus its label set; downloaded once into ~/.celltypist/data/models/. Immune_All_Low.pkl covers fine-grained immune subtypes, Immune_All_High.pkl the coarse ones
• AnnotationResult — returned by celltypist.annotate(), with .predicted_labels (a DataFrame holding predicted_labels, over_clustering, majority_voting), .probability_matrix (cells × labels), and .decision_matrix (raw decision scores)
• Per-cell obs columns — after result.to_adata(): adata.obs["predicted_labels"], adata.obs["majority_voting"], adata.obs["conf_score"]
• Marker dictionary — a plain dict of {"cell type": [genes]} fed to sc.pl.dotplot(); the orthogonal evidence you judge the classifier against
• h5ad — write the annotated object with adata.write_h5ad(); for the R/SingleR route export counts + obs to a SingleCellExperiment or via zellkonverter::readH5AD()

Minimal code walkthrough

Load a QC-filtered object, normalize to exactly 10,000 counts per cell and log1p-transform, build a Leiden over-clustering, run CellTypist with majority_voting=True, record per-cell confidence, demote low-confidence cells to Unknown, and cross-check the result with a marker dot plot.

import scanpy as sc
import numpy as np
import celltypist
from celltypist import models

# 1. Load the QC'd object (post filtering / doublet removal, raw counts in X)
adata = sc.read_h5ad("adata_qc.h5ad")
adata.layers["counts"] = adata.X.copy()      # keep integers for later DE

# 2. NORMALIZATION CONTRACT — the classic CellTypist mistake.
#    CellTypist models were trained on expression normalized to exactly
#    10,000 counts per cell and then log1p-transformed. target_sum=1e4 is
#    NOT optional: use 1e6 (CPM), SCTransform residuals, or scaled/z-scored
#    values and the probabilities are silently wrong, not an error.
sc.pp.normalize_total(adata, target_sum=1e4)
sc.pp.log1p(adata)
adata.raw = adata                            # log-normalized snapshot

# 3. Over-clustering for majority voting. CellTypist can compute its own,
#    but reusing your analysis Leiden keeps labels consistent with the UMAP
#    you will actually show. Slightly over-cluster (higher resolution).
sc.pp.highly_variable_genes(adata, n_top_genes=2000, batch_key=None)
sc.pp.pca(adata, n_comps=50, mask_var="highly_variable")
sc.pp.neighbors(adata, n_neighbors=15)
sc.tl.leiden(adata, resolution=1.5, key_added="leiden", flavor="igraph",
             n_iterations=2, directed=False)
sc.tl.umap(adata)

# 4. Download and load a pretrained model. Immune_All_Low = fine-grained
#    immune subtypes; Immune_All_High = coarse lineages. Pick the resolution
#    your tissue actually supports.
models.download_models(model=["Immune_All_Low.pkl"])
model = models.Model.load(model="Immune_All_Low.pkl")
print(model.cell_types[:10], "...", len(model.cell_types), "labels")

# 5. Annotate. majority_voting=True refines per-cell calls by taking the
#    dominant label within each over-clustering group -- it removes salt-and-
#    pepper noise but can erase genuinely rare populations (see pitfalls).
predictions = celltypist.annotate(
    adata,
    model=model,
    majority_voting=True,
    over_clustering="leiden",
)

# 6. Per-cell confidence = max class probability. Keep it visible; it is the
#    only honest signal that a cell was a coin flip between two labels.
prob = predictions.probability_matrix
adata.obs["predicted_labels"]  = predictions.predicted_labels["predicted_labels"].values
adata.obs["majority_voting"]   = predictions.predicted_labels["majority_voting"].values
adata.obs["conf_score"]        = prob.max(axis=1).values
adata.obs["runner_up"]         = prob.apply(
    lambda r: r.sort_values(ascending=False).index[1], axis=1
).values

# 7. Do NOT force a name on weak evidence. Demote low-probability cells to
#    "Unknown" rather than letting the argmax invent an identity.
LOW_CONF = 0.5
adata.obs["cell_type"] = adata.obs["majority_voting"].astype(str)
adata.obs.loc[adata.obs["conf_score"] < LOW_CONF, "cell_type"] = "Unknown"
n_unknown = (adata.obs["cell_type"] == "Unknown").sum()
print(f"Unknown (conf < {LOW_CONF}): {n_unknown} / {adata.n_obs} cells")
print(adata.obs["cell_type"].value_counts().head(20))

# 8. ORTHOGONAL CROSS-EXAMINATION. A classifier label is a hypothesis; a
#    canonical marker panel is the independent witness. Every called type
#    should light up its own markers and stay dark elsewhere.
markers = {
    "T cell":        ["CD3D", "CD3E", "TRAC"],
    "CD8 T":         ["CD8A", "CD8B", "GZMK"],
    "CD4 T":         ["IL7R", "CCR7", "CD40LG"],
    "NK":            ["NKG7", "GNLY", "KLRD1"],
    "B cell":        ["MS4A1", "CD79A", "CD79B"],
    "Plasma":        ["JCHAIN", "MZB1", "XBP1"],
    "Monocyte":      ["LYZ", "CD14", "FCN1"],
    "cDC":           ["FCER1A", "CD1C", "CLEC9A"],
    "Platelet":      ["PPBP", "PF4", "ITGA2B"],
}
markers = {k: [g for g in v if g in adata.var_names] for k, v in markers.items()}
sc.pl.dotplot(adata, markers, groupby="cell_type",
              standard_scale="var", dendrogram=True)
sc.pl.umap(adata, color=["cell_type", "conf_score"], legend_loc="on data")

# 9. Quantify agreement between the two lines of evidence: score each cell
#    for each marker panel and check the argmax against the classifier.
for ct, genes in markers.items():
    sc.tl.score_genes(adata, genes, score_name=f"score_{ct}")
scores = adata.obs[[f"score_{ct}" for ct in markers]]
adata.obs["marker_call"] = (
    scores.idxmax(axis=1).str.replace("score_", "", regex=False)
)
print(sc.metrics.confusion_matrix("cell_type", "marker_call", adata.obs))

# 10. Save. Store the full probability matrix so downstream reviewers can
#     re-threshold without re-running the classifier.
adata.obsm["celltypist_prob"] = prob.reindex(adata.obs_names).values
adata.uns["celltypist_labels"] = list(prob.columns)
adata.write_h5ad("adata_annotated.h5ad")
print("Saved adata_annotated.h5ad")

Fallback routes. If no CellTypist model fits your tissue, two alternatives use the same annotated object. SingleR (R) correlates each cell against a bulk or single-cell reference and reports a per-cell delta score, so it flags weak assignments explicitly:

# R -- SingleR cross-check on the same log-normalized matrix
library(SingleR); library(celldex); library(zellkonverter)

sce <- readH5AD("adata_annotated.h5ad")            # X = log-normalized
assayNames(sce) <- "logcounts"
ref <- celldex::HumanPrimaryCellAtlasData()        # or MonacoImmuneData()

pred <- SingleR(test = sce, ref = ref, labels = ref$label.fine,
                de.method = "wilcox")
table(pred$pruned.labels, useNA = "ifany")         # NA = pruned, low confidence
plotDeltaDistribution(pred)                        # per-cell assignment margin

Or take the reference-mapping route — Azimuth (Seurat) or scArches/scANVI — which projects your query into a curated atlas embedding and transfers labels with a mapping score. That route handles batch effects between query and reference far better than a plain classifier, at the cost of needing a well-matched atlas.

Common pitfalls & tips

• The 10,000-count normalization is a hard requirement. CellTypist expects sc.pp.normalize_total(adata, target_sum=1e4) followed by sc.pp.log1p(). Feeding CPM (1e6), raw counts, scaled/z-scored values, or SCTransform residuals produces confidently wrong labels with no warning — the model still returns probabilities, they are just meaningless. Check np.expm1(adata.X[:5]).sum(1) ≈ 10,000 before you trust anything.
• Majority voting over-merges rare types. Smoothing to the dominant label inside each over-cluster cleans up noise, but a 30-cell pDC or MAIT population sitting inside a larger cluster is erased outright. Always keep the raw predicted_labels column beside majority_voting, and over-cluster (Leiden resolution 1.5–2.0) so rare types get their own group before voting.
• A missing cell type gets mislabeled, not flagged. Classifiers are closed-world: if your tumor sample contains malignant epithelium and the reference only knows immune cells, those cells are assigned to the nearest immune label with a plausible-looking probability. Absence of a class is never reported as absence — inspect the confidence distribution and the markers of every cluster, especially large ones with a suspiciously uniform label.
• Tissue-mismatched references are a silent failure. Immune_All_Low on brain tissue will call microglia something in its immune vocabulary; a gut atlas will not describe kidney. Match the reference to the tissue and the assay (10x vs Smart-seq2 differ in gene detection), and prefer the coarse model when the fine one has no vocabulary for your sample.
• Batch effects break reference mapping, not just integration. Query-vs-reference differences in chemistry, donor, or dissociation protocol shift the embedding and drag labels with them. Use a method that models the batch (scArches/scANVI, Azimuth's anchor transfer, Symphony) rather than nearest-neighbor transfer on unintegrated PCA, and never integrate query and reference so aggressively that the biological signal you are trying to read is also removed.
• Always validate with orthogonal markers. Treat the classifier output as a hypothesis and the canonical marker dot plot as the independent witness. A "CD8 T cell" cluster with no CD3D and abundant LYZ is a misannotation regardless of how high the probability is. Disagreement between the two is the signal worth investigating, not a nuisance.
• Mark low-confidence cells "Unknown" rather than force-assigning. The argmax always returns something. Thresholding on max probability (≈0.5, calibrated by looking at the score histogram) and labeling the rest Unknown is honest and downstream-safe; a forced label propagates into every DE test, composition comparison, and figure that follows.
• Annotate on log-normalized data, test on counts. Keep the raw integers in adata.layers["counts"]. Annotation needs the normalized matrix, but differential expression, pseudobulk, and doublet re-checks need counts — losing them means re-running the pipeline from the start.