Scanpy : Analyse de données en cellule unique
Vue d'ensemble
Scanpy est une boîte à outils Python évolutive pour l'analyse de données de séquençage d'ARN en cellule unique, construite sur AnnData. Utilisez ce skill pour des workflows complets de cellule unique comprenant le contrôle qualité, la normalisation, la réduction de dimensionnalité, le clustering, l'identification de gènes marqueurs, la visualisation et l'analyse de trajectoires. Version stable actuelle : scanpy 1.12.x (janvier 2026).
Installation
Nécessite Python 3.12+ (scanpy 1.12 a abandonné Python ≤3.11) et anndata ≥0.10.
uv pip install "scanpy[leiden]"
L'extension [leiden] installe python-igraph et leidenalg, nécessaires pour le clustering de Leiden. Pour des environnements reproductibles, épinglez une version : uv pip install "scanpy[leiden]==1.12.1".
Pour les grands jeux de données ou les données hors cœur, de nombreuses fonctions prennent en charge les tableaux Dask (expérimental) :
uv pip install "scanpy[leiden]" dask
Consultez le tutoriel Utiliser Dask avec Scanpy. Pour des opérations de type Scanpy accélérées par GPU, utilisez rapids-singlecell en tant que package séparé.
Si l'entrée est un objet R de cellule unique (.rds, .RData, Seurat ou SingleCellExperiment), convertissez-le d'abord en .h5ad avec des outils R, puis chargez-le avec Scanpy. Consultez references/r_interop.md pour les instructions d'installation et de conversion sous macOS, Linux et Windows.
Pour les détails sur la structure et les entrées/sorties d'AnnData, utilisez le skill anndata. Pour les modèles probabilistes et la correction de lot, utilisez scvi-tools.
Quand utiliser ce skill
Ce skill doit être utilisé lorsque :
- Vous analysez des données de séquençage d'ARN en cellule unique (formats .h5ad, 10X, CSV)
- Vous travaillez avec des jeux de données de cellule unique compatibles R (
.rds,.RData, Seurat, SingleCellExperiment) qui nécessitent une conversion en.h5ad - Vous effectuez un contrôle qualité sur des jeux de données scRNA-seq
- Vous créez des visualisations UMAP, t-SNE ou PCA
- Vous identifiez des clusters cellulaires et trouvez des gènes marqueurs
- Vous annotez des types cellulaires en fonction de l'expression génique
- Vous réalisez une inférence de trajectoire ou une analyse de pseudotemps
- Vous générez des graphiques de cellule unique de qualité publication
Boîte à outils de scripts (préférez ces scripts à l'écriture de code from scratch)
Ce skill contient des scripts CLI prêts à l'emploi dans scripts/ pour chaque étape courante. Exécutez ces scripts plutôt que d'écrire du code scanpy à la main — ils gèrent le chargement des fichiers par extension, la configuration des figures, des valeurs par défaut judicieuses, la préservation des comptages bruts et la journalisation de la progression. Chacun lit et écrit du .h5ad, donc ils s'enchaînent, et chacun a son propre --help. N'écrivez du code scanpy que lorsqu'une tâche n'est pas couverte par un script ou nécessite une personnalisation inhabituelle.
Tous les scripts utilisent un assistant partagé scripts/_common.py (chargement, sauvegarde, configuration des figures) — conservez-le avec les autres. Exécutez depuis le répertoire du skill ou passez des chemins complets ; les figures sont par défaut dans ./figures/.
| Script | Objectif | Appel typique |
|---|---|---|
run_pipeline.py | Workflow complet en une commande : charger → QC → normaliser → HVG → PCA → (batch) → UMAP → Leiden → marqueurs | python scripts/run_pipeline.py raw.h5ad -o processed.h5ad |
inspect_data.py | Résumer un jeu de données inconnu (forme, obs/var, couches, ce qui est déjà calculé, brut vs normalisé) | python scripts/inspect_data.py data.h5ad |
convert.py | Charger n'importe quel format (répertoire 10x/.h5, csv, loom, mtx) et écrire du .h5ad | python scripts/convert.py 10x_dir/ -o data.h5ad |
qc_analysis.py | Métriques QC, graphiques avant/après, filtrage, option Scrublet pour les doublets | python scripts/qc_analysis.py raw.h5ad -o qc.h5ad --scrublet |
preprocess.py | Normaliser, log1p, HVG, option scale/regress (conserve la couche counts + raw) | python scripts/preprocess.py qc.h5ad -o norm.h5ad |
reduce_dimensions.py | PCA + graphique de variance, voisins, UMAP, option t-SNE | python scripts/reduce_dimensions.py norm.h5ad -o red.h5ad |
batch_correct.py | Intégration : harmony / bbknn / combat | python scripts/batch_correct.py red.h5ad -o int.h5ad --method harmony --batch-key sample |
cluster.py | Leiden (ou louvain) à une ou plusieurs résolutions | python scripts/cluster.py red.h5ad -o clu.h5ad --resolution 0.3 0.6 1.0 |
find_markers.py | rank_genes_groups + CSV par groupe + graphiques de marqueurs | python scripts/find_markers.py clu.h5ad --groupby leiden -o clu.h5ad |
annotate.py | Mapper les clusters → types cellulaires depuis JSON/CSV ; option dotplot de référence des marqueurs | python scripts/annotate.py clu.h5ad -o ann.h5ad --mapping map.json |
score_genes.py | Noter les signatures géniques (JSON) et/ou la phase du cycle cellulaire | python scripts/score_genes.py ann.h5ad -o scored.h5ad --gene-sets sigs.json |
pseudobulk.py | Agréger les comptages par échantillon × type cellulaire → matrice pour pydeseq2 | python scripts/pseudobulk.py ann.h5ad --by sample cell_type --out-prefix pb |
subset.py | Sous-ensembler par valeurs obs ou liste de gènes (optionnellement effacer les embeddings obsolètes) | python scripts/subset.py ann.h5ad -o tcells.h5ad --obs cell_type --keep "T cells" |
plot.py | Générer des graphiques umap/tsne/pca/violin/dotplot/heatmap/etc. à partir d'un objet traité | python scripts/plot.py ann.h5ad --kind dotplot --genes CD3D CD14 --groupby cell_type |
Exécution de bout en bout en une commande
# Comptages → objet clusterisé avec marqueurs annotés + figures + CSV de marqueurs
python scripts/run_pipeline.py raw.h5ad -o processed.h5ad \
--resolution 0.5 --n-top-genes 2000 --scrublet
# Avec intégration multi-échantillons :
python scripts/run_pipeline.py raw.h5ad -o processed.h5ad --batch-key sample --batch-method harmony
# Paramètres reproductibles via JSON (les clés reflètent les noms des flags avec des underscores) :
python scripts/run_pipeline.py raw.h5ad -o processed.h5ad --config params.json
Chaîne étape par étape (lorsque vous devez inspecter/itérer entre les étapes)
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
# inspecter résultats/marqueurs/*.csv, décider des étiquettes, écrire un JSON de mapping, puis :
python scripts/annotate.py clu.h5ad -o ann.h5ad --mapping celltypes.json
Les sections ci-dessous documentent les appels scanpy sous-jacents que chaque script effectue — lisez-les lorsque vous personnalisez au-delà des flags du script.
Démarrage rapide
Importation et configuration de base
import scanpy as sc
import pandas as pd
import numpy as np
# Configurer les paramètres
sc.settings.verbosity = 3
sc.settings.set_figure_params(dpi=80, facecolor='white')
sc.settings.figdir = './figures/'
sc.settings.autosave = True # Préféré à save= par graphique (déprécié dans scanpy 1.12)
Chargement des données
# Depuis 10X Genomics
adata = sc.read_10x_mtx('chemin/vers/donnees/')
adata = sc.read_10x_h5('chemin/vers/donnees.h5')
# Depuis h5ad (format AnnData)
adata = sc.read_h5ad('chemin/vers/donnees.h5ad')
# Depuis CSV
adata = sc.read_csv('chemin/vers/donnees.csv')
Pour les fichiers R natifs, n'essayez pas d'analyser les fichiers .rds de Seurat directement en Python. Convertissez d'abord :
# Voir references/r_interop.md pour installer R et les packages de conversion.
Rscript convert_rds_to_h5ad.R input.rds output.h5ad
adata = sc.read_h5ad('output.h5ad')
Comprendre la structure d'AnnData
L'objet AnnData est la structure de données centrale dans scanpy :
adata.X # Matrice d'expression (cellules × gènes)
adata.obs # Métadonnées des cellules (DataFrame)
adata.var # Métadonnées des gènes (DataFrame)
adata.uns # Annotations non structurées (dict)
adata.obsm # Données multi-dimensionnelles des cellules (PCA, UMAP)
adata.raw # Sauvegarde des données brutes
# Accéder aux noms des cellules et des gènes
adata.obs_names # Barcodes des cellules
adata.var_names # Noms des gènes
Workflow d'analyse standard
Les sept étapes, avec le code et les paramètres importants à chaque étape, se trouvent dans references/analysis_workflow.md :
- Contrôle qualité — filtrer les cellules et les gènes ; inspecter la fraction mitochondriale et les comptages avant de choisir les seuils plutôt que de copier les valeurs par défaut.
- Normalisation et prétraitement — normaliser, transformer en log, sélectionner les gènes hautement variables,
et conserver
.rawpour les graphiques ultérieurs. - Réduction de dimensionnalité — PCA, puis le graphe de voisinage, puis UMAP.
- Clustering — Leiden à une résolution choisie pour la question, pas la valeur par défaut.
- Identification des gènes marqueurs — gènes classés par cluster.
- Annotation des types cellulaires — mapper les clusters aux types à partir des marqueurs.
- Sauvegarde des résultats — écrire l'
AnnDataannotée.
Les tâches de suivi courantes — graphiques de publication, inférence de trajectoire, expression différentielle pseudobulk entre conditions, notation de jeux de gènes et correction de lot — se trouvent dans le même fichier. Voir aussi references/standard_workflow.md et references/plotting_guide.md.
Paramètres clés à ajuster
Contrôle qualité
min_genes: Nombre minimum de gènes par cellule (typiquement 200-500)min_cells: Nombre minimum de cellules par gène (typiquement 3-10)pct_counts_mt: Seuil mitochondrial (typiquement 5-20%)
Normalisation
target_sum: Nombre de comptages cible par cellule (par défaut 1e4)
Sélection de caractéristiques
n_top_genes: Nombre de HVGs (typiquement 2000-3000)min_mean,max_mean,min_disp: Paramètres de sélection des HVG
Réduction de dimensionnalité
n_pcs: Nombre de composantes principales (vérifier le graphique du ratio de variance)n_neighbors: Nombre de voisins (typiquement 10-30)
Clustering
resolution: Granularité du clustering (0.4-1.2, plus élevé = plus de clusters)
Pièges courants et bonnes pratiques
- Toujours sauvegarder les comptages bruts :
adata.raw = adataavant de filtrer les gènes - Vérifier attentivement les graphiques QC : Ajuster les seuils en fonction de la qualité du jeu de données
- Utiliser le clustering de Leiden :
sc.tl.louvainest déprécié dans scanpy 1.12 - Essayer plusieurs résolutions de clustering : Trouver la granularité optimale
- Valider les annotations de types cellulaires : Utiliser plusieurs gènes marqueurs
- Utiliser
use_raw=Truepour les graphiques d'expression génique : Affiche les comptages normalisés depuis.raw - Vérifier le ratio de variance de la PCA : Déterminer le nombre optimal de PCs
- Sauvegarder les résultats intermédiaires : Les longs workflows peuvent échouer en cours de route
- Pseudobulk pour l'expression différentielle : Ne pas traiter les p-valeurs de
rank_genes_groupscomme une analyse rigoureuse de l'expression différentielle entre conditions - Sauvegarder les graphiques via les paramètres : Utiliser
sc.settings.autosaveau lieu dusave=déprécié sur les fonctions de tracé - Convertir les objets R avant Scanpy : Utiliser les packages R pour convertir les fichiers Seurat ou SingleCellExperiment
.rdsen.h5ad, en conservant les comptages, les métadonnées et les identifiants de gènes
Ressources fournies
scripts/ (Boîte à outils CLI)
Un ensemble de scripts composables en entrée/.h5ad en sortie couvrant tout le workflow plus un pipeline complet en une commande. Voir la section Boîte à outils de scripts ci-dessus pour le tableau complet et des exemples d'enchaînement. Chaque script a --help. Fichiers :
_common.py— assistants partagés de chargement/sauvegarde/figures importés par les autres (pas un CLI)run_pipeline.py— pipeline complet en une commande (flags ou--configJSON)inspect_data.py,convert.py— explorer et charger/convertir n'importe quel format d'entréeqc_analysis.py,preprocess.py,reduce_dimensions.py,batch_correct.py,cluster.py— étapes du pipelinefind_markers.py,annotate.py,score_genes.py,pseudobulk.py— marqueurs, annotation, notation, préparation DEsubset.py,plot.py— sous-ensembler par métadonnées/gènes ; générer n'importe quel graphique standard
Utilisez ces scripts par défaut avant d'écrire du code scanpy à la main.
references/standard_workflow.md
Workflow complet étape par étape avec des explications détaillées et des exemples de code pour :
- Chargement et configuration des données
- Contrôle qualité avec visualisation
- Normalisation et mise à l'échelle
- Sélection de caractéristiques
- Réduction de dimensionnalité (PCA, UMAP, t-SNE)
- Clustering (Leiden)
- Détection de doublets (scrublet) et agrégation pseudobulk
- Identification de gènes marqueurs
- Annotation de types cellulaires
- Inférence de trajectoire
- Expression différentielle
Lisez cette référence lorsque vous effectuez une analyse complète à partir de zéro.
references/api_reference.md
Guide de référence rapide pour les fonctions scanpy organisées par module :
- Lecture/écriture de données (
sc.read_*,adata.write_*) - Prétraitement (
sc.pp.*) - Outils (
sc.tl.*) - Tracé (
sc.pl.*) - Structure et manipulation d'AnnData
- Paramètres et utilitaires
Utilisez ceci pour une recherche rapide des signatures de fonctions et des paramètres courants.
references/plotting_guide.md
Guide complet de visualisation comprenant :
- Graphiques de contrôle qualité
- Visualisations de réduction de dimensionnalité
- Visualisations de clustering
- Graphiques de gènes marqueurs (heatmaps, dot plots, violin plots)
- Graphiques de trajectoire et de pseudotemps
- Personnalisation de qualité publication
- Figures multi-panneaux
- Palettes de couleurs et style
Consultez ceci lors de la création de figures prêtes à publier.
references/r_interop.md
Manuel d'utilisation pour l'agent pour installer R sur macOS, Linux et Windows, installer les packages de conversion CRAN/Bioconductor, inspecter les entrées .rds/.RData, convertir les objets Seurat ou SingleCellExperiment en .h5ad, et valider le résultat dans Scanpy.
assets/analysis_template.py
Modèle d'analyse complet fournissant un workflow complet du chargement des données à l'annotation des types cellulaires. Copiez et personnalisez ce modèle pour de nouvelles analyses :
cp assets/analysis_template.py mon_analyse.py
# Modifier les paramètres et exécuter
python mon_analyse.py
Le modèle inclut toutes les étapes standard avec des paramètres configurables et des commentaires utiles.
Modèles JSON assets/
Modèles à modifier et à passer pour ne pas avoir à créer la configuration/les mappings à partir de zéro :
assets/pipeline_config.json— jeu de paramètres pourrun_pipeline.py --configassets/celltype_mapping.json— carte cluster → type cellulaire pourannotate.py --mappingassets/gene_signatures.json— signatures de jeux de gènes pourscore_genes.py --gene-sets
Ressources supplémentaires
- Documentation officielle de scanpy : https://scanpy.scverse.org/en/stable/
- Tutoriels Scanpy : https://scanpy-tutorials.readthedocs.io/en/latest/
- Documentation d'AnnData : https://anndata.readthedocs.io/en/latest/
- Projet scverse : https://scverse.org/
Références
- Wolf FA, Angerer P, Theis FJ. SCANPY: large-scale single-cell gene expression data analysis. Genome Biology 2018, 19:15. doi: 10.1186/s13059-017-1382-0
- Documentation Scanpy : https://scanpy.scverse.org/en/stable/
- Dépôt GitHub : https://github.com/scverse/scanpy