Contrôle de qualité de l'ARNseq monocellulaire

Workflow QC automatisé pour données d'ARNseq monocellulaire suivant les meilleures pratiques scverse.

Quand utiliser cette skill

Utilisez quand les utilisateurs :

Demandent un contrôle de qualité ou QC sur des données d'ARNseq monocellulaire
Veulent filtrer les cellules de faible qualité ou évaluer la qualité des données
Ont besoin de visualisations ou métriques QC
Demandent à suivre les meilleures pratiques scverse/scanpy
Demandent un filtrage basé sur MAD ou une détection d'outliers

Formats d'entrée supportés :

Fichiers .h5ad (format AnnData de workflows scanpy/Python)
Fichiers .h5 (sortie Cell Ranger 10X Genomics)

Recommandation par défaut : Utilisez Approach 1 (pipeline complet) sauf si l'utilisateur a des besoins custom spécifiques ou demande explicitement une logique de filtrage non-standard.

Approach 1 : Pipeline QC complet (Recommandé pour les workflows standard)

Pour un QC standard suivant les meilleures pratiques scverse, utilisez le script pratique scripts/qc_analysis.py :

python3 scripts/qc_analysis.py input.h5ad
# ou pour les fichiers .h5 10X Genomics :
python3 scripts/qc_analysis.py raw_feature_bc_matrix.h5

Le script détecte automatiquement le format de fichier et le charge correctement.

Quand utiliser cette approche :

Workflow QC standard avec seuils ajustables (toutes les cellules filtrées de la même façon)
Traitement batch de plusieurs datasets
Analyse exploratoire rapide
L'utilisateur veut la solution « qui marche »

Prérequis : anndata, scanpy, scipy, matplotlib, seaborn, numpy

Paramètres :

Personnalisez les seuils de filtrage et les patterns de gènes en utilisant les paramètres en ligne de commande :

--output-dir - Répertoire de sortie
--mad-counts, --mad-genes, --mad-mt - Seuils MAD pour counts/gènes/MT%
--mt-threshold - Seuil dur de pourcentage mitochondrial
--min-cells - Seuil de filtrage des gènes
--mt-pattern, --ribo-pattern, --hb-pattern - Patterns de noms de gènes pour différentes espèces

Utilisez --help pour voir les valeurs par défaut actuelles.

Sorties :

Tous les fichiers sont sauvegardés dans le répertoire <input_basename>_qc_results/ par défaut (ou dans le répertoire spécifié par --output-dir) :

qc_metrics_before_filtering.png - Visualisations avant filtrage
qc_filtering_thresholds.png - Overlays de seuils basés sur MAD
qc_metrics_after_filtering.png - Métriques de qualité post-filtrage
<input_basename>_filtered.h5ad - Dataset propre et filtré prêt pour l'analyse en aval
<input_basename>_with_qc.h5ad - Données originales avec annotations QC conservées

Si vous copiez des sorties pour l'accès utilisateur, copiez les fichiers individuels (pas tout le répertoire) pour que les utilisateurs puissent les prévisualiser directement.

Étapes du workflow

Le script effectue les étapes suivantes :

Calculer les métriques QC - Profondeur de comptage, détection de gènes, contenu mitochondrial/ribosomal/hémoglobine
Appliquer le filtrage basé sur MAD - Détection d'outliers permissive utilisant des seuils MAD pour counts/gènes/MT%
Filtrer les gènes - Supprimer les gènes détectés dans peu de cellules
Générer les visualisations - Plots avant/après complets avec overlays de seuils

Approach 2 : Blocs de construction modulaires (Pour les workflows custom)

Pour les workflows d'analyse custom ou les besoins non-standard, utilisez les fonctions utilitaires modulaires de scripts/qc_core.py et scripts/qc_plotting.py :

# Exécutez depuis le répertoire scripts/, ou ajoutez scripts/ à sys.path si nécessaire
import anndata as ad
from qc_core import calculate_qc_metrics, detect_outliers_mad, filter_cells
from qc_plotting import plot_qc_distributions  # Seulement si visualisation nécessaire

adata = ad.read_h5ad('input.h5ad')
calculate_qc_metrics(adata, inplace=True)
# ... logique d'analyse custom ici

Quand utiliser cette approche :

Workflow différent nécessaire (sauter des étapes, changer l'ordre, appliquer des seuils différents à des sous-ensembles)
Logique conditionnelle (p. ex., filtrer les neurones différemment que les autres cellules)
Exécution partielle (seulement métriques/visualisation, pas de filtrage)
Intégration avec d'autres étapes d'analyse dans un pipeline plus large
Critères de filtrage custom au-delà de ce que les paramètres en ligne de commande supportent

Fonctions utilitaires disponibles :

De qc_core.py (opérations QC principales) :

calculate_qc_metrics(adata, mt_pattern, ribo_pattern, hb_pattern, inplace=True) - Calculer les métriques QC et annoter adata
detect_outliers_mad(adata, metric, n_mads, verbose=True) - Détection d'outliers basée sur MAD, retourne un masque booléen
apply_hard_threshold(adata, metric, threshold, operator='>', verbose=True) - Appliquer des seuils durs, retourne un masque booléen
filter_cells(adata, mask, inplace=False) - Appliquer un masque booléen pour filtrer les cellules
filter_genes(adata, min_cells=20, min_counts=None, inplace=True) - Filtrer les gènes par détection
print_qc_summary(adata, label='') - Imprimer les statistiques résumées

De qc_plotting.py (visualisation) :

plot_qc_distributions(adata, output_path, title) - Générer des plots QC complets
plot_filtering_thresholds(adata, outlier_masks, thresholds, output_path) - Visualiser les seuils de filtrage
plot_qc_after_filtering(adata, output_path) - Générer des plots post-filtrage

Exemples de workflows custom :

Exemple 1 : Calculer seulement les métriques et visualiser, ne pas filtrer encore

adata = ad.read_h5ad('input.h5ad')
calculate_qc_metrics(adata, inplace=True)
plot_qc_distributions(adata, 'qc_before.png', title='Initial QC')
print_qc_summary(adata, label='Before filtering')

Exemple 2 : Appliquer seulement le filtrage MT%, garder les autres métriques permissives

adata = ad.read_h5ad('input.h5ad')
calculate_qc_metrics(adata, inplace=True)

# Filtrer seulement les cellules avec MT% élevé
high_mt = apply_hard_threshold(adata, 'pct_counts_mt', 10, operator='>')
adata_filtered = filter_cells(adata, ~high_mt)
adata_filtered.write('filtered.h5ad')

Exemple 3 : Seuils différents pour différents sous-ensembles

adata = ad.read_h5ad('input.h5ad')
calculate_qc_metrics(adata, inplace=True)

# Appliquer QC spécifique au type (suppose que les métadonnées cell_type existent)
neurons = adata.obs['cell_type'] == 'neuron'
other_cells = ~neurons

# Les neurones tolèrent un MT% plus élevé, les autres cellules utilisent un seuil plus strict
neuron_qc = apply_hard_threshold(adata[neurons], 'pct_counts_mt', 15, operator='>')
other_qc = apply_hard_threshold(adata[other_cells], 'pct_counts_mt', 8, operator='>')

Bonnes pratiques

Être permissif avec le filtrage - Les seuils par défaut conservent intentionnellement la plupart des cellules pour éviter de perdre les populations rares
Inspecter les visualisations - Examinez toujours les plots avant/après pour assurer que le filtrage a du sens biologiquement
Considérer les facteurs spécifiques au dataset - Certains tissus ont naturellement un contenu mitochondrial plus élevé (p. ex., neurones, cardiomyocytes)
Vérifier les annotations de gènes - Les préfixes de gènes mitochondriaux varient selon les espèces (mt- pour la souris, MT- pour l'humain)
Itérer si nécessaire - Les paramètres QC peuvent nécessiter un ajustement en fonction de l'expérience ou du type de tissu spécifique

Matériaux de référence

Pour la méthodologie QC détaillée, la rationale des paramètres et les conseils de dépannage, voir references/scverse_qc_guidelines.md. Cette référence fournit :

Explications détaillées de chaque métrique QC et pourquoi elle importe
Rationale pour les seuils basés sur MAD et pourquoi ils sont meilleurs que les seuils fixes
Directives pour interpréter les visualisations QC (histogrammes, violin plots, scatter plots)
Considérations spécifiques aux espèces pour les annotations de gènes
Quand et comment ajuster les paramètres de filtrage
Considérations QC avancées (correction d'ARN ambiant, détection de doublets)

Chargez cette référence quand les utilisateurs ont besoin d'une compréhension plus profonde de la méthodologie ou lors du dépannage des problèmes QC.

Étapes suivantes après QC

Étapes typiques d'analyse en aval :

Correction d'ARN ambiant (SoupX, CellBender)
Détection de doublets (scDblFinder)
Normalisation (log-normalize, scran)
Sélection de features et réduction de dimensionnalité
Clustering et annotation du type cellulaire

single-cell-rna-qc