scanpy

Scanpy: Einzelzell-Analyse

Überblick

Scanpy ist ein skalierbares Python-Toolkit für die Analyse von Einzelzell-RNA-seq-Daten, das auf AnnData aufbaut. Wende dieses Skill für vollständige Einzelzell-Workflows an, einschließlich Qualitätskontrolle, Normalisierung, Dimensionsreduktion, Clusterbildung, Markergen-Identifikation, Visualisierung und Trajektorienanalyse. Aktuelle stabile Version: scanpy 1.12.x (Januar 2026).

Installation

Erfordert Python 3.12+ (scanpy 1.12 hat Python ≤3.11 fallen gelassen) und anndata ≥0.10.

uv pip install "scanpy[leiden]"

Das [leiden]-Extra installiert python-igraph und leidenalg, die für das Leiden-Clustering benötigt werden. Für reproduzierbare Umgebungen eine Version festlegen: uv pip install "scanpy[leiden]==1.12.1".

Für große oder Out-of-Core-Datasets unterstützen viele Funktionen Dask-Arrays (experimentell):

uv pip install "scanpy[leiden]" dask

Siehe das Tutorial Using dask with Scanpy. Für GPU-beschleunigte Scanpy-ähnliche Operationen verwende rapids-singlecell als separates Paket.

Wenn die Eingabe ein R-natives Einzelzellobjekt (.rds, .RData, Seurat oder SingleCellExperiment) ist, konvertiere es zuerst mit R-Tools in .h5ad und lade es dann mit Scanpy. Lese references/r_interop.md für agentengeführte Installations- und Konvertierungsanleitungen unter macOS, Linux und Windows.

Für AnnData-Struktur- und I/O-Details verwende das anndata-Skill. Für probabilistische Modelle und Batch-Korrektur verwende scvi-tools.

Wann dieses Skill verwenden

Dieses Skill sollte verwendet werden, wenn:

• Einzelzell-RNA-seq-Daten (.h5ad, 10X, CSV-Formate) analysiert werden
• Mit R-freundlichen Einzelzelldatasets (.rds, .RData, Seurat, SingleCellExperiment) gearbeitet wird, die in .h5ad konvertiert werden müssen
• Eine Qualitätskontrolle von scRNA-seq-Datasets durchgeführt wird
• UMAP-, t-SNE- oder PCA-Visualisierungen erstellt werden
• Zellcluster identifiziert und Markergene gefunden werden
• Zelltypen basierend auf Genexpression annotiert werden
• Trajektorien- oder Pseudotime-Analysen durchgeführt werden
• Veröffentlichungsreife Einzelzellgrafiken erzeugt werden

Skript-Toolkit (diese statt Code von Grund auf neu schreiben bevorzugen)

Dieses Skill bündelt einsatzbereite CLI-Skripte in scripts/ für jeden gängigen Schritt. Führe diese anstelle von handgeschriebenem Scanpy-Code aus – sie kümmern sich um das Laden von Dateien (basierend auf der Endung), Figuren-Setup, sinnvolle Standardwerte, Erhalt der Rohdatenzählungen und Fortschrittsprotokollierung. Jedes liest und schreibt .h5ad, sodass sie sich verketten lassen, und jedes hat eine eigene --help. Nur dann selbst Scanpy-Code schreiben, wenn eine Aufgabe von keinem Skript abgedeckt wird oder eine ungewöhnliche Anpassung erforderlich ist.

Alle Skripte verwenden eine gemeinsame Hilfsdatei scripts/_common.py (Laden, Speichern, Figure-Konfiguration) – halte sie zusammen mit den anderen. Führe sie aus dem Skill-Verzeichnis aus oder gib vollständige Pfade an; Figuren standardmäßig in ./figures/.

Skript	Zweck	Typischer Aufruf
run_pipeline.py	Vollständiger Workflow in einem Befehl: Laden → QC → Normalisieren → HVG → PCA → (Batch) → UMAP → Leiden → Marker	python scripts/run_pipeline.py raw.h5ad -o processed.h5ad
inspect_data.py	Ein unbekanntes Dataset zusammenfassen (Form, obs/var, Ebenen, was bereits berechnet, roh vs. normalisiert)	python scripts/inspect_data.py data.h5ad
convert.py	Beliebige Formate laden (10x-Verzeichnis/.h5, csv, loom, mtx) und .h5ad schreiben	python scripts/convert.py 10x_dir/ -o data.h5ad
qc_analysis.py	QC-Metriken, Vorher/Nachher-Diagramme, Filtern, optional Scrublet-Doubletten	python scripts/qc_analysis.py raw.h5ad -o qc.h5ad --scrublet
preprocess.py	Normalisieren, log1p, HVG, optional skalieren/regressieren (behält counts-Ebene + raw)	python scripts/preprocess.py qc.h5ad -o norm.h5ad
reduce_dimensions.py	PCA + Varianzdiagramm, Nachbarn, 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 (oder Louvain) mit einer oder mehreren Auflösungen	python scripts/cluster.py red.h5ad -o clu.h5ad --resolution 0.3 0.6 1.0
find_markers.py	rank_genes_groups + CSVs pro Gruppe + Marker-Diagramme	python scripts/find_markers.py clu.h5ad --groupby leiden -o clu.h5ad
annotate.py	Cluster → Zelltypen aus JSON/CSV zuordnen; optionaler Referenz-Dotplot der Marker	python scripts/annotate.py clu.h5ad -o ann.h5ad --mapping map.json
score_genes.py	Gen-Signaturen (JSON) und/oder Zellzyklusphase bewerten	python scripts/score_genes.py ann.h5ad -o scored.h5ad --gene-sets sigs.json
pseudobulk.py	Zählungen nach Probe × Zelltyp aggregieren → Matrix für pydeseq2	python scripts/pseudobulk.py ann.h5ad --by sample cell_type --out-prefix pb
subset.py	Nach obs-Werten oder Genliste teilmengen (optional veraltete Einbettungen löschen)	python scripts/subset.py ann.h5ad -o tcells.h5ad --obs cell_type --keep "T cells"
plot.py	UMAP/t-SNE/PCA/Violin/Dotplot/Heatmap etc. aus einem verarbeiteten Objekt erzeugen	python scripts/plot.py ann.h5ad --kind dotplot --genes CD3D CD14 --groupby cell_type

End-to-End-Durchlauf in einem Schritt

# Zählungen → geclustertes, markerannotiertes Objekt + Figuren + Marker-CSVs
python scripts/run_pipeline.py raw.h5ad -o processed.h5ad \
    --resolution 0.5 --n-top-genes 2000 --scrublet
# Mit Multi-Proben-Integration:
python scripts/run_pipeline.py raw.h5ad -o processed.h5ad --batch-key sample --batch-method harmony
# Reproduzierbare Parameter über JSON (Schlüssel spiegeln Flag-Namen mit Unterstrichen wider):
python scripts/run_pipeline.py raw.h5ad -o processed.h5ad --config params.json

Schritt-für-Schritt-Kette (wenn du zwischen den Schritten inspizieren/iterieren musst)

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
# Ergebnisse/Marker/*.csv inspizieren, Labels festlegen, ein Mapping-JSON schreiben, dann:
python scripts/annotate.py           clu.h5ad  -o ann.h5ad  --mapping celltypes.json

Die folgenden Abschnitte dokumentieren die zugrunde liegenden Scanpy-Aufrufe, die jedes Skript ausführt – lies sie, wenn du über die Skript-Flags hinaus anpassen möchtest.

Schnellstart

Grundlegender Import und Setup

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

# Einstellungen konfigurieren
sc.settings.verbosity = 3
sc.settings.set_figure_params(dpi=80, facecolor='white')
sc.settings.figdir = './figures/'
sc.settings.autosave = True  # Bevorzugt gegenüber der pro Plot speichern= (in scanpy 1.12 veraltet)

Daten laden

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

# Aus h5ad (AnnData-Format)
adata = sc.read_h5ad('path/to/data.h5ad')

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

Für R-native Dateien: Versuche nicht, Seurat .rds direkt in Python zu parsen. Konvertiere zuerst:

# Siehe references/r_interop.md für die Installation von R und Konvertierungspaketen.
Rscript convert_rds_to_h5ad.R input.rds output.h5ad

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

AnnData-Struktur verstehen

Das AnnData-Objekt ist die zentrale Datenstruktur in Scanpy:

adata.X          # Expressionsmatrix (Zellen × Gene)
adata.obs        # Zellmetadaten (DataFrame)
adata.var        # Genmetadaten (DataFrame)
adata.uns        # Unstrukturierte Annotationen (dict)
adata.obsm       # Mehrdimensionale Zelldaten (PCA, UMAP)
adata.raw        # Sicherung der Rohdaten

# Zugriff auf Zell- und Gennamen
adata.obs_names  # Zell-Barcodes
adata.var_names  # Gennamen

Standard-Analyse-Workflow

Die sieben Schritte mit Code und den Parametern, die in jedem Schritt wichtig sind, findest du in references/analysis_workflow.md:

1. Qualitätskontrolle — filtere Zellen und Gene; überprüfe den mitochondrialen Anteil und die Zählungen, bevor du Schwellenwerte auswählst, anstatt Standardwerte zu kopieren.
2. Normalisierung und Vorverarbeitung — normalisieren, log-transformieren, hochvariable Gene auswählen und .raw für spätere Diagramme behalten.
3. Dimensionsreduktion — PCA, dann den Nachbarschaftsgraphen, dann UMAP.
4. Clusterbildung — Leiden mit einer für die Fragestellung gewählten Auflösung, nicht dem Standardwert.
5. Markergen-Identifikation — Rangfolge der Gene pro Cluster.
6. Zelltyp-Annotation — Zuordnung von Clustern zu Typen anhand der Marker.
7. Ergebnisse speichern — das annotierte AnnData schreiben.

Häufige Folgeaufgaben – Veröffentlichungsdiagramme, Trajektorienanalyse, differentielle Pseudobulk-Expression zwischen Bedingungen, Gen-Set-Scoring und Batch-Korrektur – befinden sich in derselben Datei. Siehe auch references/standard_workflow.md und references/plotting_guide.md.

Wichtige anzupassende Parameter

Qualitätskontrolle

• min_genes: Minimale Gene pro Zelle (typischerweise 200-500)
• min_cells: Minimale Zellen pro Gen (typischerweise 3-10)
• pct_counts_mt: Mitochondrialer Schwellenwert (typischerweise 5-20%)

Normalisierung

• target_sum: Ziel-Zählungen pro Zelle (Standard 1e4)

Merkmalsauswahl

• n_top_genes: Anzahl der HVGs (typischerweise 2000-3000)
• min_mean, max_mean, min_disp: HVG-Auswahlparameter

Dimensionsreduktion

• n_pcs: Anzahl der Hauptkomponenten (Varianzverhältnisdiagramm prüfen)
• n_neighbors: Anzahl der Nachbarn (typischerweise 10-30)

Clusterbildung

• resolution: Granularität der Clusterbildung (0.4-1.2, höher = mehr Cluster)

Häufige Fehler und bewährte Verfahren

1. Rohdaten-Zählungen immer speichern: adata.raw = adata vor dem Filtern von Genen
2. QC-Diagramme sorgfältig prüfen: Schwellenwerte basierend auf der Dataset-Qualität anpassen
3. Leiden-Clustering verwenden: sc.tl.louvain ist in scanpy 1.12 veraltet
4. Mehrere Cluster-Auflösungen ausprobieren: Optimale Granularität finden
5. Zelltyp-Annotationen validieren: Mehrere Markergene verwenden
6. use_raw=True für Genexpressionsdiagramme verwenden: Zeigt normalisierte Zählungen aus .raw
7. PCA-Varianzverhältnis prüfen: Optimale Anzahl von PCs bestimmen
8. Zwischenergebnisse speichern: Lange Workflows können auf halbem Weg fehlschlagen
9. Pseudobulk für DE verwenden: Behandle rank_genes_groups-p-Werte nicht als strenge DE zwischen Bedingungen
10. Diagramme über die Einstellungen speichern: Verwende sc.settings.autosave anstelle der veralteten save= auf Plot-Funktionen
11. R-Objekte vor Scanpy konvertieren: Verwende R-Pakete, um Seurat- oder SingleCellExperiment-.rds-Dateien in .h5ad zu konvertieren, wobei Zählungen, Metadaten und Gen-Identifikatoren erhalten bleiben

Mitgelieferte Ressourcen

scripts/ (CLI-Toolkit)

Ein zusammensetzbarer Satz von .h5ad-in/.h5ad-out-Skripten, die den gesamten Workflow plus eine Ein-Befehl-End-to-End-Pipeline abdecken. Siehe den Abschnitt Skript-Toolkit oben für die vollständige Tabelle und Verkettungsbeispiele. Jedes Skript hat --help. Dateien:

• _common.py — gemeinsame Lade-/Speicher-/Figure-Hilfsfunktionen, die von den anderen importiert werden (kein CLI)
• run_pipeline.py — vollständige Pipeline in einem Befehl (Flags oder --config JSON)
• inspect_data.py, convert.py — jedes Eingabeformat erkunden und laden/konvertieren
• qc_analysis.py, preprocess.py, reduce_dimensions.py, batch_correct.py, cluster.py — Pipeline-Schritte
• find_markers.py, annotate.py, score_genes.py, pseudobulk.py — Marker, Annotation, Bewertung, DE-Vorbereitung
• subset.py, plot.py — nach Metadaten/Genen teilmengen; jedes Standarddiagramm erzeugen

Verwende standardmäßig diese Skripte, bevor du Scanpy-Code von Grund auf neu schreibst.

references/standard_workflow.md

Vollständiger Schritt-für-Schritt-Workflow mit detaillierten Erklärungen und Codebeispielen für:

• Daten laden und Setup
• Qualitätskontrolle mit Visualisierung
• Normalisierung und Skalierung
• Merkmalsauswahl
• Dimensionsreduktion (PCA, UMAP, t-SNE)
• Clusterbildung (Leiden)
• Doubletten-Erkennung (Scrublet) und Pseudobulk-Aggregation
• Markergen-Identifikation
• Zelltyp-Annotation
• Trajektorienanalyse
• Differentielle Expression

Lies diese Referenz, wenn du eine vollständige Analyse von Grund auf durchführst.

references/api_reference.md

Kurzreferenz für Scanpy-Funktionen, organisiert nach Modulen:

• Daten lesen/schreiben (sc.read_*, adata.write_*)
• Vorverarbeitung (sc.pp.*)
• Tools (sc.tl.*)
• Diagramme (sc.pl.*)
• AnnData-Struktur und -Manipulation
• Einstellungen und Dienstprogramme

Verwende dies zum schnellen Nachschlagen von Funktionssignaturen und gängigen Parametern.

references/plotting_guide.md

Umfassender Visualisierungsleitfaden, einschließlich:

• Qualitätskontroll-Diagramme
• Dimensionsreduktions-Visualisierungen
• Cluster-Visualisierungen
• Markergen-Diagramme (Heatmaps, Dotplots, Violin-Diagramme)
• Trajektorien- und Pseudotime-Diagramme
• Anpassung für Veröffentlichungsqualität
• Mehrtafel-Figuren
• Farbpaletten und Styling

Konsultiere diesen, wenn du veröffentlichungsreife Grafiken erstellst.

references/r_interop.md

Agenten-Runbook für die Installation von R auf macOS, Linux und Windows, die Installation von CRAN/Bioconductor-Konvertierungspaketen, die Inspektion von .rds/.RData-Eingaben, die Konvertierung von Seurat- oder SingleCellExperiment-Objekten in .h5ad und die Validierung des Ergebnisses in Scanpy.

assets/analysis_template.py

Vollständige Analysevorlage, die einen vollständigen Workflow vom Laden der Daten bis zur Zelltyp-Annotation bietet. Kopiere und passe diese Vorlage für neue Analysen an:

cp assets/analysis_template.py my_analysis.py
# Parameter bearbeiten und ausführen
python my_analysis.py

Die Vorlage enthält alle Standardschritte mit konfigurierbaren Parametern und hilfreichen Kommentaren.

assets/ JSON-Vorlagen

Editierbare und direkt verwendbare Vorlagen, sodass du Konfigurationen/Mappings nicht von Grund auf neu erstellen musst:

• assets/pipeline_config.json — Parametersatz für run_pipeline.py --config
• assets/celltype_mapping.json — Cluster → Zelltyp-Zuordnung für annotate.py --mapping
• assets/gene_signatures.json — Gen-Set-Signaturen für score_genes.py --gene-sets

Zusätzliche Ressourcen

• Offizielle Scanpy-Dokumentation: https://scanpy.scverse.org/en/stable/
• Scanpy-Tutorials: https://

…[für die Übersetzung abgeschnitten]