Skip to main content
ClaudeWave
EN, English
Skill382 repo starsupdated 7d ago

single-cell-annotation

This Claude Code skill provides best practices for annotating cell types in single-cell RNA-seq data across three methodologies: marker-based identification using canonical or data-derived gene panels, reference-based label transfer using established atlases like the Human Cell Atlas, and automated classification approaches. Use this skill when analyzing single-cell transcriptomics data that requires assigning cell type identities to clusters or individual cells, particularly when distinguishing stable cell types from transient cell states.

Install in Claude Code
Copy
git clone --depth 1 https://github.com/jaechang-hits/SciAgent-Skills /tmp/single-cell-annotation && cp -r /tmp/single-cell-annotation/legacy/single-cell-annotation ~/.claude/skills/single-cell-annotation
Then start a new Claude Code session; the skill loads automatically.

SKILL.md

# Single Cell RNA-seq Cell Type Annotation

---

## Metadata

**Short Description**: Best practices for annotating cell types in single-cell RNA-seq data using marker-based, automated, and reference-based approaches.

**Authors**: Distilled from "Single-cell best practices" by Luecken, M.D. et al.

**Affiliations**: Helmholtz Munich, Wellcome Sanger Institute, Harvard Medical School, and contributors

**Version**: 1.0

**Last Updated**: January 2025

**License**: CC BY 4.0

**Commercial Use**: ✅ Allowed

**Source**: https://www.sc-best-practices.org/cellular_structure/annotation.html

**Citation**: Luecken, M.D., Theis, F.J. et al. (2023). Current best practices in single-cell RNA-seq analysis: a tutorial. Molecular Systems Biology.

---

## Overview

Cell type annotation is the process of assigning cell type labels to clusters or individual cells in single-cell RNA-seq data. This guide covers three main approaches and their practical implementation.

## Key Concepts

### Cell Type vs. Cell State
A **cell type** is a stable identity defined by a developmental trajectory and core marker gene program (e.g., CD4+ T cell, hepatocyte). A **cell state** is a transient condition (activated, cycling, stressed) overlaid on a cell type. Annotation should target cell types first; states are attributes that may further subdivide a type but should not be conflated with type identity.

### Marker Genes and Marker Panels
Marker genes are genes whose expression is enriched in a specific cell type relative to other cells in the same tissue context. Reliable annotation uses **panels of multiple markers** (typically 3-5 per type) rather than a single gene, because expression is noisy in droplet-based scRNA-seq and many markers are shared across related types. Markers come in two flavors: **canonical** (literature-derived, e.g., CD3D for T cells) and **data-derived** (from differential expression on the dataset).

### Reference Atlases and Label Transfer
A reference atlas is a previously annotated dataset (e.g., Human Cell Atlas, Tabula Sapiens) used to project labels onto a new "query" dataset. Label transfer methods (scArches, scANVI, Azimuth, SingleR) align query cells into the reference latent space and assign the nearest neighbor's label. Quality of transfer depends on tissue match, technology match (e.g., 10x v3 vs. Smart-seq2), and species match.

## Decision Framework

Use this tree to choose an annotation approach:

```
                Do you have a well-characterized tissue
                with a high-quality reference atlas?
                            │
              ┌─────────────┴─────────────┐
              │                           │
             YES                          NO
              │                           │
              ▼                           ▼
   Is this a standard tissue       Are you studying
   (PBMC, lung, gut) with a       novel cell types or
   pre-trained classifier?         exploratory data?
              │                           │
        ┌─────┴─────┐               ┌─────┴─────┐
        │           │               │           │
       YES          NO             YES          NO
        │           │               │           │
        ▼           ▼               ▼           ▼
   Automated    Reference-     Manual marker  Manual +
   (CellTypist) based          based          automated
                (scArches,     (Scanpy,       cross-check
                 Azimuth,      Seurat)
                 SingleR)
```

### Decision Table

| Scenario | Approach | Primary Tool | Validation |
|----------|----------|--------------|------------|
| Standard human PBMC, large dataset (>100k cells) | Automated | CellTypist | Spot-check with manual markers |
| Well-characterized tissue (lung, kidney, brain) | Reference-based label transfer | scArches / Azimuth | Marker consistency on top clusters |
| Novel/rare tissue, no good reference | Manual marker-based | Scanpy / Seurat | Hierarchical, broad-to-fine |
| Cross-species (e.g., zebrafish) | Manual markers + ortholog mapping | Scanpy + custom panel | Compare to closest reference species |
| Developmental / continuous trajectory | Reference-based with state-aware model | scANVI / scArches | Trajectory coherence + markers |
| Disease tissue with known perturbation | Manual + automated cross-check | CellTypist + Scanpy | Confirm disease-specific states separately |

## Three Annotation Approaches

### 1. Manual Marker-Based Annotation
Identify cell types by examining expression of known marker genes in each cluster.

**Tools**: Scanpy, Seurat
**Best for**: Small datasets, novel cell types, high confidence needs

### 2. Automated Annotation
Use pre-trained classifiers to automatically assign cell type labels.

**Tools**: CellTypist, scAnnotate
**Best for**: Standard tissues, quick preliminary annotation, large datasets

### 3. Reference-Based Label Transfer
Transfer labels from annotated reference datasets to your query data.

**Tools**: scArches, scANVI, Azimuth, SingleR
**Best for**: Well-characterized tissues, integration with public data

## Recommended Workflow

### Step 1: Quality Control First
- **Remove low-quality cells before annotation**
- Filter doublets (expected doublet rate: 0.8% per 1000 cells)
- Check for ambient RNA contamination
- Verify cluster quality and resolution

### Step 2: Initial Marker-Based Assessment

```python
# Scanpy example
import scanpy as sc

# Calculate marker genes for clusters
sc.tl.rank_genes_groups(adata, 'leiden', method='wilcoxon')

# Visualize top markers
sc.pl.rank_genes_groups(adata, n_genes=25, sharey=False)

# Plot known markers
markers = {
    'T cells': ['CD3D', 'CD3E', 'CD4', 'CD8A'],
    'B cells': ['CD19', 'MS4A1', 'CD79A'],
    'Monocytes': ['CD14', 'FCGR3A', 'LYZ'],
    'NK cells': ['NCAM1', 'NKG7', 'GNLY']
}

sc.pl.dotplot(adata, markers, groupby='leiden')
```

### Step 3: Use Automated Tools for Validation

```python
# CellTypist example (fast, accurate for immune cell
anndata-data-structureSkill

Annotated matrices for single-cell genomics. Stores X with obs/var metadata, layers, embeddings (obsm/varm), graphs (obsp/varp), uns. Use for .h5ad/.zarr I/O, concatenation, scverse integration. For analysis use scanpy; for probabilistic models use scvi-tools.

arboreto-grn-inferenceSkill

GRN inference from expression via GRNBoost2 (gradient boosting) or GENIE3 (Random Forest). Load matrix, filter by TFs, infer TF-target-importance links, save network. Dask-parallelized to single-cell scale. Core SCENIC component.

archs4-databaseSkill

Query ARCHS4 REST API for uniformly processed RNA-seq expression, tissue patterns, co-expression across 1M+ human/mouse samples. Retrieve z-scores, co-expressed genes, samples by metadata, HDF5 matrices. For variant population genetics use gnomad-database; for pathway enrichment use gget-genomic-databases (Enrichr).

bakta-genome-annotationSkill

Annotate bacterial and archaeal genomes and plasmids with Bakta's Prodigal/HMM/diamond pipeline. Identifies CDS, ncRNA, tRNA, rRNA, tmRNA, sORFs, CRISPR arrays, oriC/oriV/oriT, and gaps against a curated UniRef-derived database. Produces NCBI-compatible GFF3, GenBank, EMBL, JSON, FASTA, TSV, and a circular genome plot. Use Prokka for legacy pipelines or non-bacterial kingdoms; PGAP for NCBI GenBank submission.

bcftools-variant-manipulationSkill

CLI for VCF/BCF: filter, merge, annotate, query, normalize, compute stats. Core post-variant-calling: quality filtering, multi-sample merging, rsID annotation, genotype extraction. Samtools companion in HTSlib. Use GATK for complex indel realignment during calling; use VCFtools for population genetics stats.

bedtools-genomic-intervalsSkill

Genomic interval ops on BED/BAM/GFF/VCF. Find overlaps, merge intervals, compute coverage, extract FASTA, find nearest features. Core for ChIP-seq peak annotation, region filtering, genome arithmetic. Use tabix for indexed single-region queries; use deeptools for normalized bigWig coverage.

biopython-molecular-biologySkill

Molecular biology toolkit: sequence manipulation, FASTA/GenBank/PDB I/O, NCBI Entrez, BLAST automation, pairwise/MSA alignment, Bio.PDB, phylogenetic trees. Use for batch processing, custom pipelines, format conversion, PubMed/GenBank queries. For quick gene lookups use gget; for multi-service REST APIs use bioservices.

biopython-sequence-analysisSkill

Biopython sequence analysis: parse FASTA/FASTQ/GenBank/GFF (SeqIO), NCBI Entrez (esearch/efetch/elink), remote/local BLAST, pairwise/MSA alignment (PairwiseAligner, MUSCLE/ClustalW), phylogenetic trees (Phylo). Use for gene family studies, phylogenomics, comparative genomics, NCBI pipelines. For PCR/restriction/cloning use biopython-molecular-biology; for SAM/BAM use pysam.