Bio Single Cell Cell Annotation

Version Compatibility

Reference examples tested with: scanpy 1.10+, Seurat 5.0+, celltypist 1.6+

Before using code patterns, verify installed versions match. If versions differ:

• Python: pip show <package> then help(module.function) to check signatures
• R: packageVersion('<pkg>') then ?function_name to verify parameters

If code throws ImportError, AttributeError, or TypeError, introspect the installed package and adapt the example to match the actual API rather than retrying.

Automated Reference-Based Cell Annotation

"Annotate my cells from a reference" -> Transfer labels from an annotated reference or pretrained model onto query cells, with a calibrated confidence/rejection step.

• Python: celltypist.annotate() (pretrained LR) or scvi-tools scANVI label transfer
• R: SingleR() (correlation to a reference) or RunAzimuth() (anchor-based mapping)

Governing principle

An annotation is a HYPOTHESIS, not a measurement. Reference-based annotators are closed-world: every query cell is forced toward the nearest label the reference contains, so a genuinely novel state gets the nearest wrong label - often with high apparent confidence. Reproducible is not the same as correct; an automated label inherits the reference's annotation errors, granularity, and tissue/donor/disease scope, and propagates them at scale wearing the authority of "automated." Markers are context-dependent. A marker gene is a conditional statement: "marker X = type Y" means "in this tissue, platform, and processing, X enriches in Y relative to these other cells." A marker in blood may be expressed broadly in tumor; "canonical confirmation" using the same markers that defined the type is circular (recovering the prior, not new evidence). Treat reference labels and marker catalogs (PanglaoDB, CellMarker) as priors to be triangulated, never ground truth. Before naming a new cell type, triage the four-way confusion in decreasing frequency: (1) doublets - two cell types summed, co-expressing mutually exclusive lineage markers; (2) low-quality/dying - high mito %, low gene count, ambient-dominated; (3) batch/technical - the cluster maps to one sample/lane/chemistry; (4) ambient-RNA contamination (SoupX/CellBender). Only after excluding all four is "novel cell type" admissible. The field is littered with "novel populations" that were doublets or stress artifacts.

This skill covers automated reference transfer. Manual marker discovery and hand-labeling live in single-cell/markers-annotation; the two are complementary - automate a first pass, confirm with markers, reserve expert curation for the final label and ambiguous populations.

Choosing an annotation method

No method escapes the closed-world limit except by an explicit reject/unassigned bin. When methods compete, verify current best practice and reference availability against installed docs before committing.

Normalization requirements (silent-failure risk)

CellTypist (Python)

Goal: Transfer labels from a pretrained model with cluster-level smoothing and a probability for rejection.

Approach: Normalize the query to CP10K log1p (the model's expected input), run annotate with majority_voting to reassign each over-clustered subgroup to its dominant label, then keep a per-cell confidence for filtering.

import scanpy as sc
import celltypist
from celltypist import models

adata = sc.read_h5ad('clustered.h5ad')
adata.X = adata.layers['counts'].copy()
sc.pp.normalize_total(adata, target_sum=1e4)
sc.pp.log1p(adata)

models.download_models(model='Immune_All_Low.pkl')
predictions = celltypist.annotate(adata, model='Immune_All_Low.pkl', majority_voting=True)
adata = predictions.to_adata()

adata.obs['cell_type'] = adata.obs['majority_voting']
adata.obs['uncertain'] = adata.obs['conf_score'] < 0.5

SingleR (R)

Goal: Assign each cell by correlation to a reference and prune low-confidence calls.

Approach: Score each cell's Spearman correlation to reference profiles (per-label score is the 0.8 quantile), assign the max, fine-tune, then prune cells whose delta (assigned-label score minus median) falls >3 MADs below the delta distribution.

library(SingleR)
library(celldex)
library(SingleCellExperiment)

sce <- as.SingleCellExperiment(seurat_obj)
ref <- celldex::HumanPrimaryCellAtlasData()

pred <- SingleR(test = sce, ref = ref, labels = ref$label.main, de.method = 'classic', fine.tune = TRUE)
seurat_obj$SingleR <- pred$labels
seurat_obj$SingleR_pruned <- pred$pruned.labels

plotScoreHeatmap(pred)
plotDeltaDistribution(pred)

Use de.method='classic' for bulk references and de.method='wilcox' for single-cell references. Cells pruned to NA are the rejection set; inspect the delta distribution rather than trusting a hard score cutoff.