/sc-cell-annotation

name: sc-cell-annotation
description: Load when assigning cell-type labels to a clustered scRNA AnnData via marker dictionaries,
  CellTypist, PopV, KNNPredict, SingleR, scmap, SCSA, or a manual cluster-to-label map. Skip when ranking
  marker genes per cluster (use sc-markers); condition-vs-control DE (use sc-de).
tags:
- singlecell
- scrna
- cell-annotation
- celltypist
- popv
- singler
- scmap
- scsa
- knnpredict
- markers

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 communiti