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).

Installation

Requires Python 3.12+ (scanpy 1.12 dropped Python ≤3.11) and anndata ≥0.10.

uv pip install "scanpy[leiden]"

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):

uv pip install "scanpy[leiden]" dask

See the Using dask with Scanpy tutorial. For GPU-accelerated scanpy-like operations, use rapids-singlecell as a separate package.

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	python scripts/run_pipeline.py raw.h5ad -o processed.h5ad
inspect_data.py	Summarize an unknown dataset (shape, obs/var, layers, what's already computed, raw vs normalized)	python scripts/inspect_data.py data.h5ad
convert.py	Load any format (10x dir/.h5, csv, loom, mtx) and write .h5ad	python scripts/convert.py 10x_dir/ -o data.h5ad
qc_analysis.py	QC metrics, before/after plots, filtering, optional Scrublet doublets	python scripts/qc_analysis.py raw.h5ad -o qc.h5ad --scrublet
preprocess.py	Normalize, log1p, HVG, optional scale/regress (keeps counts layer + raw)	python scripts/preprocess.py qc.h5ad -o norm.h5ad
reduce_dimensions.py	PCA + variance plot, neighbors, UMAP, optional t-SNE	python scripts/reduce_dimensions.py norm.h5ad -o red.h5ad
batch_correct.py	Integration: harmony / bbknn / combat	python scripts/batch_correct.py red.h5ad -o int.h5ad --method harmony --batch-key sample
cluster.py	Leiden (or louvain) at one or many resolutions	python scripts/cluster.py red.h5ad -o clu.h5ad --resolution 0.3 0.6 1.0
find_markers.py	rank_genes_groups + per-group CSVs + marker plots	python scripts/find_markers.py clu.h5ad --groupby leiden -o clu.h5ad
annotate.py	Map clusters → cell types from JSON/CSV; optional marker reference dotplot	python scripts/annotate.py clu.h5ad -o ann.h5ad --mapping map.json
score_genes.py	Score gene signatures (JSON) and/or cell-cycle phase	python scripts/score_genes.py ann.h5ad -o scored.h5ad --gene-sets sigs.json
pseudobulk.py	Aggregate counts by sample × cell type → matrix for pydeseq2	python scripts/pseudobulk.py ann.h5ad --by sample cell_type --out-prefix pb
subset.py	Subset by obs values or gene list (optionally clear stale embeddings)	python scripts/subset.py ann.h5ad -o tcells.h5ad --obs cell_type --keep "T cells"
plot.py	Generate umap/tsne/pca/violin/dotplot/heatmap/etc. from a processed object	python scripts/plot.py ann.h5ad --kind dotplot --genes CD3D CD14 --groupby cell_type

One-shot end-to-end run

# Counts → clustered, marker-annotated object + figures + marker CSVs
python scripts/run_pipeline.py raw.h5ad -o processed.h5ad \
    --resolution 0.5 --n-top-genes 2000 --scrublet
# With multi-sample integration:
python scripts/run_pipeline.py raw.h5ad -o processed.h5ad --batch-key sample --batch-method harmony
# Reproducible parameters via JSON (keys mirror flag names with underscores):
python scripts/run_pipeline.py raw.h5ad -o processed.h5ad --config params.json

Step-by-step chain (when you need to inspect/iterate between stages)

python scripts/qc_analysis.py        raw.h5ad  -o qc.h5ad   --scrublet
python scripts/preprocess.py         qc.h5ad   -o norm.h5ad --n-top-genes 2000
python scripts/reduce_dimensions.py  norm.h5ad -o red.h5ad  --n-pcs 40
python scripts/cluster.py            red.h5ad  -o clu.h5ad  --resolution 0.3 0.5 0.8
python scripts/find_markers.py       clu.h5ad  -o clu.h5ad  --groupby leiden --use-raw
# inspect results/markers/*.csv, decide labels, write a mapping JSON, then:
python scripts/annotate.py           clu.h5ad  -o ann.h5ad  --mapping celltypes.json

The sections below document the underlying scanpy calls each script performs — read them when customizing beyond the script flags.

Quick Start

Basic Import and Setup

import scanpy as sc
import pandas as pd
import numpy as np

# Configure settings
sc.settings.verbosity = 3
sc.settings.set_figure_params(dpi=80, facecolor='white')
sc.settings.figdir = './figures/'
sc.settings.autosave = True  # Preferred over per-plot save= (deprecated in scanpy 1.12)

Loading Data

# From 10X Genomics
adata = sc.read_10x_mtx('path/to/data/')
adata = sc.read_10x_h5('path/to/data.h5')

# From h5ad (AnnData format)
adata = sc.read_h5ad('path/to/data.h5ad')

# From CSV
adata = sc.read_csv('path/to/data.csv')

For R-native files, do not try to parse Seurat .rds directly in Python. Convert first:

# See references/r_interop.md for installing R and conversion packages.
Rscript convert_rds_to_h5ad.R input.rds output.h5ad

adata = sc.read_h5ad('output.h5ad')

Understanding AnnData Structure

The AnnData object is the core data structure in scanpy:

adata.X          # Expression matrix (cells × genes)
adata.obs        # Cell metadata (DataFrame)
adata.var        # Gene metadata (DataFrame)
adata.uns        # Unstructured annotations (dict)
adata.obsm       # Multi-dimensional cell data (PCA, UMAP)
adata.raw        # Raw data backup

# Access cell and gene names
adata.obs_names  # Cell barcodes
adata.var_names  # Gene names

Standard Analysis Workflow

1. Quality Control

Identify and filter low-quality cells and genes:

# Identify mitochondrial genes
adata.var['mt'] = adata.var_names.str.startswith('