Standard single-cell RNA-seq analysis pipeline. Use for QC, normalization, dimensionality reduction (PCA/UMAP/t-SNE), clustering, differential expression, visualization, and converting R-friendly single-cell formats such as Seurat or SingleCellExperiment RDS files into h5ad for Scanpy. Best for exploratory scRNA-seq analysis with established workflows. For deep learning models use scvi-tools; for data format questions use anndata.
SKILL.md
Scanpy: Single-Cell Analysis
Overview
Scanpy is a scalable Python toolkit for analyzing single-cell RNA-seq data, built on AnnData. Apply this skill for complete single-cell workflows including quality control, normalization, dimensionality reduction, clustering, marker gene identification, visualization, and trajectory analysis. Current stable release: scanpy 1.12.x (January 2026).
The [leiden] extra installs python-igraph and leidenalg, required for Leiden clustering. For reproducible environments, pin a version: uv pip install "scanpy[leiden]==1.12.1".
For large or out-of-core datasets, many functions support Dask arrays (experimental):
If the input is an R-native single-cell object (.rds, .RData, Seurat, or SingleCellExperiment), first convert it to .h5ad with R tooling, then load it with Scanpy. Read references/r_interop.md for agent-run installation and conversion instructions across macOS, Linux, and Windows.
For AnnData structure and I/O details, use the anndata skill. For probabilistic models and batch correction, use .
scvi-tools
When to Use This Skill
This skill should be used when:
Analyzing single-cell RNA-seq data (.h5ad, 10X, CSV formats)
Working with R-friendly single-cell datasets (.rds, .RData, Seurat, SingleCellExperiment) that need conversion to .h5ad
Performing quality control on scRNA-seq datasets
Creating UMAP, t-SNE, or PCA visualizations
Identifying cell clusters and finding marker genes
Annotating cell types based on gene expression
Conducting trajectory inference or pseudotime analysis
Generating publication-quality single-cell plots
Script Toolkit (prefer these over writing code from scratch)
This skill bundles ready-to-run CLI scripts in scripts/ for every common step. Run these instead of hand-writing scanpy code — they handle file loading by extension, figure setup, sensible defaults, raw-count preservation, and progress logging. Each reads and writes .h5ad, so they chain together, and each has its own --help. Only drop down to writing scanpy code when a task isn't covered by a script or needs unusual customization.
All scripts use a shared scripts/_common.py helper (loading, saving, figure config) — keep it alongside the others. Run from the skill directory or pass full paths; figures default to ./figures/.
Script
Purpose
Typical call
run_pipeline.py
Full workflow in one command: load → QC → normalize → HVG → PCA → (batch) → UMAP → Leiden → markers
Quality control — filter cells and genes; inspect mitochondrial fraction and counts
before choosing thresholds rather than copying defaults.
Normalization and preprocessing — normalize, log-transform, select highly variable
genes, and keep .raw for later plotting.
Dimensionality reduction — PCA, then the neighbour graph, then UMAP.
Clustering — Leiden at a resolution chosen for the question, not the default.
Marker gene identification — ranked genes per cluster.
Cell type annotation — mapping clusters to types from markers.
Save results — writing the annotated AnnData.
Common follow-on tasks — publication plots, trajectory inference, pseudobulk differential
expression between conditions, gene set scoring, and batch correction — are in the same
file. See also references/standard_workflow.md and
references/plotting_guide.md.
Key Parameters to Adjust
Quality Control
min_genes: Minimum genes per cell (typically 200-500)
min_cells: Minimum cells per gene (typically 3-10)
Validate cell type annotations: Use multiple marker genes
Use use_raw=True for gene expression plots: Shows normalized counts from .raw
Check PCA variance ratio: Determine optimal number of PCs
Save intermediate results: Long workflows can fail partway through
Pseudobulk for DE: Do not treat rank_genes_groups p-values as rigorous DE between conditions
Save plots via settings: Use sc.settings.autosave instead of deprecated save= on plot functions
Convert R objects before Scanpy: Use R packages to convert Seurat or SingleCellExperiment .rds files to .h5ad, preserving counts, metadata, and gene identifiers
Bundled Resources
scripts/ (CLI toolkit)
A composable set of .h5ad-in/.h5ad-out scripts covering the whole workflow plus a one-command end-to-end pipeline. See the Script Toolkit section above for the full table and chaining examples. Each script has --help. Files:
_common.py — shared loading/saving/figure helpers imported by the others (not a CLI)
run_pipeline.py — full pipeline in one command (flags or --config JSON)
inspect_data.py, convert.py — explore and load/convert any input format
Consult this when creating publication-ready figures.
references/r_interop.md
Agent runbook for installing R on macOS, Linux, and Windows, installing CRAN/Bioconductor conversion packages, inspecting .rds/.RData inputs, converting Seurat or SingleCellExperiment objects to .h5ad, and validating the result in Scanpy.
assets/analysis_template.py
Complete analysis template providing a full workflow from data loading through cell type annotation. Copy and customize this template for new analyses:
cp assets/analysis_template.py my_analysis.py
# Edit parameters and run
python my_analysis.py
The template includes all standard steps with configurable parameters and helpful comments.
assets/ JSON templates
Edit-and-pass templates so you don't author config/mappings from scratch:
assets/pipeline_config.json — parameter set for run_pipeline.py --config
assets/celltype_mapping.json — cluster → cell-type map for annotate.py --mapping
assets/gene_signatures.json — gene-set signatures for score_genes.py --gene-sets
