Sc Cell Annotation

sc-cell-annotation

When to use

The user has a clustered AnnData (e.g. obs["leiden"]) and wants labelled cell types in obs["cell_type"]. Pick a method by data / reference availability:

• markers (default) — built-in or custom marker-gene scoring.
• manual — user-supplied cluster-to-label map.
• celltypist — pretrained Immune_All_Low.pkl style classifier.
• popv / knnpredict — reference AnnData mapping (PopV consensus or lightweight KNN).
• singler / scmap — R-backed reference annotation.
• scsa — Fisher-test DB scoring (species, tissue).

This skill labels — for ranking the genes that justify a label use sc-markers; for replicate-aware condition DE use sc-de.

Use from a step

annotation = load_skill("sc-cell-annotation")
adata = read_input("results/03_clustering/intermediate/adata_clustered.h5ad")
# celltypist Immune_All_Low: PBMC sample; the model covers circulating immune types.
adata = annotation.annotate(adata, method="celltypist", model="Immune_All_Low")
run = annotation.run_info(adata)
assert run["summary"]["actual_method"] == "celltypist", run["summary"]["fallback_reason"]
write_output(annotation.annotation_table(adata), "tables/cell_type_counts.csv")
write_output(annotation.annotation_figure(adata), "figures/umap_cell_type.png")
write_output(adata, "intermediate/adata_annotated.h5ad")

A complete step that runs on demo data: examples/example_step.py.

API

<!-- api:begin generated from _api.py; regenerate with run.py api <skill dir> --write -->

annotate(adata, *, method: str='markers', cluster_key: str | None=None, markers: dict[str, list[str]] | None=None, marker_file: str | None=None, model: str='Immune_All_Low', majority_voting: bool=False, reference: str='HPCA', manual_map: str | None=None, manual_map_file: str | None=None, species: str='Human', tissue: str='All', scsa_foldchange: float=1.5, scsa_pvalue: float=0.05)

Annotate cell types with the chosen method; the single entry point to the method functions.

:param method: One of markers (default), manual, celltypist, popv, knnpredict, singler, scmap, scsa. See the method functions for what each needs. :param cluster_key: The obs column with cluster labels. Default None: the matrix contract's primary cluster key, else the first of leiden, louvain, seurat_clusters, cluster, cell_type present. :param markers: markers only: cell type to marker genes. Default: the built-in human set. :param marker_file: markers only: a JSON or CSV marker file, used instead of markers. :param model: celltypist only. Default "Immune_All_Low". :param majority_voting: celltypist only. Default False. :param reference: popv, knnpredict: a labelled .h5ad path; singler, scmap: a celldex atlas name. Default "HPCA". :param manual_map: manual only: inline mapping such as "0=T cell;1,2=Myeloid". :param manual_map_file: manual only: a mapping file (json/csv/tsv/txt). :param species: scsa only: "Human" or "Mouse". Default "Human". :param tissue: scsa only: CellMarker tissue filter. Default "All". :param scsa_foldchange: scsa only. Default 1.5. :param scsa_pvalue: scsa only. Default 0.05. :returns: The same AnnData. :raises ValueError: an unknown method, or what the chosen method raises.

annotate_markers(adata, *, cluster_key: str | None=None, markers: dict[str, list[str]] | None=None, marker_file: str | None=None)

Label each cluster with the cell type whose marker genes have the highest mean expression in it.

Every cell of a cluster gets the cluster's label; a cluster where no marker gene is expressed is Unknown. Gene names are matched exactly, or case-insensitively when nothing matches exactly (human markers on mouse data).

:param cluster_key: As in :func:annotate. :param markers: Cell type to marker genes. Default: the built-in human set (PBMC, brain and general stromal types). Give tissue-specific markers for other tissues. :param marker_file: A JSON ({"T cell": ["CD3D", ...]}) or CSV (T cell,CD3D;CD3E) marker file, used instead of markers. :returns: The same AnnData with obs['cell_type'] and obs['annotation_score'] (the winning mean expression). :raises ValueError: the cluster column is missing.

annotate_manual(adata, *, cluster_key: str | None=None, manual_map: str | None=None, manual_map_file: str | None=None)

Relabel clusters from a mapping the user gives.

:param cluster_key: As in :func:annotate. :param manual_map: Inline mapping such as "0=T cell;1,2=Myeloid". :param manual_map_file: A mapping file (json, csv, tsv or txt), used instead of manual_map. :returns: The same AnnData with obs['cell_type']. :raises ValueError: neither mapping is given.

annotate_celltypist(adata, *, model: str='Immune_All_Low', majority_voting: bool=False, cluster_key: str | None=None)

Per-cell labels from a pretrained CellTypist model.

CellTypist needs log1p-normalised expression to 10,000 counts; when the input fails that check, or the model cannot be loaded, the function falls back to :func:annotate_markers and records the reason (run_info(adata)["summary"]["fallback_reason"]).

:param model: A CellTypist model name or .pkl. Default "Immune_All_Low" (immune cells, fine labels); choose a tissue model for other data. Models download on first use. :param majority_voting: Smooth labels over over-clustered communities. Default False. :param cluster_key: Recorded for later steps; CellTypist labels cells individually. :returns: The same AnnData with obs['cell_type'], obs['annotation_score'] and obsm['cell_type_prob'].

annotate_popv(adata, *, reference: str='HPCA', cluster_key: str | None=None)

Labels transferred from a labelled reference AnnData by PopV-style consensus.

:param reference: Path to a labelled .h5ad (a cell_type column in obs). :param cluster_key: As in :func:annotate; used for the cluster consensus. :returns: The same AnnData with obs['cell_type'].

annotate_knnpredict(adata, *, reference: str='HPCA', cluster_key: str | None=None)

Labels transferred from a labelled reference AnnData by nearest neighbours (SCOP KNNPredict style).

:param reference: Path to a labelled .h5ad (a cell_type column in obs). :param cluster_key: As in :func:annotate. :returns: The same AnnData with obs['cell_type'] and obs['annotation_score'].

annotate_singler(adata, *, reference: str='HPCA', cluster_key: str | None=None)

Per-cell labels from SingleR against a celldex atlas, run in R.

:param reference: A celldex atlas: HPCA (default), BlueprintEncode, Monaco, ... :param cluster_key: Recorded for later steps; SingleR labels cells individually. :returns: The same AnnData with obs['cell_type'] and obs['annotation_score']. :raises RuntimeError: R, SingleR or celldex is missing, or SingleR returns nothing.

annotate_scmap(adata, *, reference: str='HPCA', cluster_key: str | None=None)

Per-cell labels projected with scmap onto a celldex atlas, run in R.

:param reference: A celldex atlas. Default HPCA. :param cluster_key: Recorded for later steps. :returns: The same AnnData with obs['cell_type']. :raises RuntimeError: R, scmap or celldex is missing, or scmap returns nothing.

annotate_scsa(adata, *, cluster_key: str | None=None, species: str='Human', tissue: str='All', foldchange: float=1.5, pvalue: float=0.05)

Cluster labels from CellMarker 2.0 genes scored against each cluster's markers (SCSA).

Runs a Wilcoxon test per cluster and scores each cell type's markers with a Fisher exact test. The CellMarker table downloads once to ~/.cache/omicsclaw/scsa; without network a small built-in set is used.

:param cluster_key: As in :func:annotate. :param species: "Human" (default) or "Mouse". :param tissue: CellMarker tissue filter such as "Blood". Default "All". :param foldchange: Minimum fold change of a cluster marker. Default 1.5. :param pvalue: Maximum adjusted p-value of a cluster marker. Default 0.05. :returns: The same AnnData with obs['cell_type'].