---
name: cell-annotation-8a1dfc0bd267
description: Automated and marker-guided single-cell cell type annotation using CellTypist, marker review, reference transfer, and confidence-aware label curation.
tool_type: python
primary_tool: CellTypist
---

# Cell Annotation

## Version Compatibility

Reference examples assume:

- `scanpy` 1.10+
- `celltypist` 1.6+
- `pandas` 2.2+

Before using code patterns, verify installed versions match the environment:

- Python: `python -c "import scanpy, celltypist; print(scanpy.__version__, celltypist.__version__)"`
- If APIs differ, inspect the installed docs and adapt the pattern instead of retrying unchanged.

## Overview

Use this skill when the user wants cluster labels or per-cell labels for scRNA-seq. The default stance is:

1. inspect markers first
2. run reference-based annotation
3. keep uncertainty explicit
4. export both raw predicted labels and a curated final label column

## When To Use This Skill

- clusters already exist and need biological labels
- the dataset has a relevant reference atlas or known marker panels
- the user wants CellTypist or similar automated annotation

## Quick Route

- If clusters are unstable or clearly QC-driven, fix preprocessing before annotation.
- If the atlas mismatch is severe, prefer broad lineage labels over overconfident fine labels.
- If multiple methods disagree, mark labels as uncertain instead of forcing a consensus.

## Progressive Disclosure

- Read [technical_reference.md](technical_reference.md) for strategy selection, confidence interpretation, and disagreement handling.
- Read [commands_and_thresholds.md](commands_and_thresholds.md) for concrete CellTypist code, score thresholds, and output columns.

## Default Rules

- Never accept automated labels without checking marker expression.
- Keep per-cell predictions and cluster-level curated labels separate.
- Use `Unknown`, `Uncertain`, or `Ambiguous` when evidence is weak.
- Document the reference model or atlas used.

## Expected Inputs

- processed `h5ad` with clusters and embeddings
- marker gene lists or known lineage markers
- optional reference atlas or model

## Expected Outputs

- `results/annotated.h5ad`
- `results/cell_labels.tsv`
- `results/cluster_annotation_summary.tsv`
- `figures/umap_cell_types.pdf`
- `figures/marker_dotplot.pdf`

## Preferred Tools

- `scanpy`
- `celltypist`
- `pandas`
- `matplotlib`

## Starter Pattern

```python
import scanpy as sc
import celltypist

adata = sc.read_h5ad("results/processed.h5ad")
pred = celltypist.annotate(adata, model="Immune_All_Low.pkl", majority_voting=True)
adata = pred.to_adata()
adata.obs["cell_type_raw"] = adata.obs["majority_voting"]
adata.obs["cell_type_confidence"] = adata.obs["conf_score"]
adata.write("results/annotated.h5ad")
```

## Workflow

### 1. Inspect markers before automation

Check canonical lineage markers on UMAP, dotplots, or heatmaps. If clusters do not support a plausible biological separation, do not lock in labels yet.

### 2. Choose the annotation level

- broad lineage labels when the reference is imperfect
- fine-grained labels only when markers and reference agree
- cluster-level labels for noisy or sparse datasets

### 3. Run reference-based annotation

Use CellTypist or another compatible reference transfer method. Store:

- raw label
- confidence score
- model name

### 4. Curate with markers and cluster context

Review top markers per cluster and compare them against predicted labels. Rename or collapse labels if fine categories are not robust.

### 5. Export both raw and final labels

At minimum, keep:

- `cell_type_raw`
- `cell_type_confidence`
- `cell_type_final`

## Output Artifacts

- `results/annotated.h5ad`
- `results/cell_labels.tsv`
- `results/cluster_annotation_summary.tsv`
- `figures/umap_cell_types.pdf`
- `figures/marker_dotplot.pdf`

## Quality Review

- `CellTypist conf_score > 0.5` is usually comfortable for a provisional label.
- `0.2-0.5` should be manually reviewed against markers.
- `< 0.2` should usually remain `Unknown` or `Uncertain` unless markers are compelling.
- Every final label should have either marker support, reference support, or both.

## Anti-Patterns

- assigning fine-grained labels only because the model returned them
- overwriting raw labels so the original prediction is lost
- treating low-confidence single-cell labels as publication-ready without review
- hiding disagreements between marker evidence and reference transfer

## Related Skills

- scRNA Preprocessing And Clustering
- Cell Communication
- Trajectory And Lineage

## Optional Supplements

- `scanpy`
- `scvi-tools`


---
Source attribution: Runchuan-BU
Original project: https://github.com/Runchuan-BU/BioClaw
License: MIT
License information: https://opensource.org/license/mit
Original upstream instructions; downloaded from Mega AI Hub.

## Upstream license notice

MIT License

Copyright (c) 2026 Gabriel Moreira

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.



# Mega AI Hub resource metadata

Creator / publisher: Runchuan-BU
Original project: https://github.com/Runchuan-BU/BioClaw
Attribution basis: Upstream repository explicitly recorded in package mirror path

Fields of work: Data & Analytics, Education & Research
Roles: Business Intelligence Analyst, Data Scientist, Researcher
Specialties: API
Tools: Celltypist, Matplotlib, Pandas, Scanpy
Country applicability: Country not specified
Classification basis: Source catalog labels
Instruction SHA-256: 697fe4e26f1176fe0b0264dd1a00e909ab12a5ec5a7e2be20284a505867637ff