deepTools

deepTools : Toolkit d'analyse de données NGS

Présentation

deepTools est une suite complète d'outils en ligne de commande Python conçus pour le traitement et l'analyse de données de séquençage à haut débit. Utilisez deepTools pour effectuer le contrôle qualité, normaliser les données, comparer des échantillons et générer des visualisations de qualité publication pour les expériences ChIP-seq, RNA-seq, ATAC-seq, MNase-seq et autres expériences NGS.

Fonctionnalités principales :

• Conversion des alignements BAM en pistes de couverture normalisées (bigWig/bedGraph)
• Évaluation du contrôle qualité (empreinte, corrélation, couverture)
• Comparaison d'échantillons et analyse de corrélation
• Génération de cartes de chaleur et de profils autour de régions génomiques
• Analyse d'enrichissement et visualisation de régions de pics

Quand utiliser cette compétence

Cette compétence doit être utilisée lorsque :

• Conversion de fichiers : "Convertir BAM en bigWig", "générer des pistes de couverture", "normaliser des données ChIP-seq"
• Contrôle qualité : "vérifier la qualité ChIP", "comparer des réplicats", "évaluer la profondeur de séquençage", "analyse QC"
• Visualisation : "créer une carte de chaleur autour du TSS", "tracer le signal ChIP", "visualiser l'enrichissement", "générer un profil"
• Comparaison d'échantillons : "comparer traitement vs contrôle", "corréler des échantillons", "analyse ACP"
• Workflows d'analyse : "analyser des données ChIP-seq", "couverture RNA-seq", "analyse ATAC-seq", "workflow complet"
• Travailler avec des types de fichiers spécifiques : fichiers BAM, fichiers bigWig, fichiers de régions BED dans un contexte génomique

Démarrage rapide

Pour les nouveaux utilisateurs de deepTools, commencez par la validation des fichiers et les workflows courants :

1. Valider les fichiers d'entrée

Avant d'exécuter une analyse, validez les fichiers BAM, bigWig et BED à l'aide du script de validation :

python scripts/validate_files.py --bam echantillon1.bam echantillon2.bam --bed regions.bed

Ceci vérifie l'existence des fichiers, les index BAM et la correction du format.

2. Générer un modèle de workflow

Pour les analyses standard, utilisez le générateur de workflow pour créer des scripts personnalisés :

# Lister les workflows disponibles
python scripts/workflow_generator.py --list

# Générer un workflow QC ChIP-seq
python scripts/workflow_generator.py chipseq_qc -o qc_workflow.sh \
    --input-bam Input.bam --chip-bams "ChIP1.bam ChIP2.bam" \
    --genome-size 2913022398

# Rendre exécutable et exécuter
chmod +x qc_workflow.sh
./qc_workflow.sh

3. Opérations les plus courantes

Consultez assets/quick_reference.md pour les commandes et paramètres fréquemment utilisés.

Installation

uv pip install deepTools==3.5.6

L'équipe de développement recommande conda/bioconda pour une résolution complète des dépendances, en particulier sur les systèmes HPC partagés :

conda install -c conda-forge -c bioconda deeptools

Sur Apple Silicon, la documentation indique soit la voie PyPI ci-dessus, soit un environnement conda osx-64 lorsque les packages conda natifs ne sont pas disponibles.

Workflows principaux et catégories d'outils

Les séquences de commandes complètes pour le QC ChIP-seq, l'analyse ChIP-seq complète, la couverture RNA-seq et l'analyse ATAC-seq — ainsi que les catégories d'outils de traitement BAM/bigWig, de contrôle qualité et de visualisation — se trouvent dans references/core_workflows.md et references/workflows.md. Les options par outil se trouvent dans references/tools_reference.md.

Méthodes de normalisation

Choisir la normalisation correcte est crucial pour des comparaisons valides. Consultez references/normalization_methods.md pour des conseils complets.

Guide de sélection rapide :

• Couverture ChIP-seq : Utilisez RPGC ou CPM
• Comparaison ChIP-seq : Utilisez bamCompare avec log2 et readCount
• Bins RNA-seq : Utilisez CPM
• Gènes RNA-seq : Utilisez RPKM (tient compte de la longueur du gène)
• ATAC-seq : Utilisez RPGC ou CPM

Méthodes de normalisation :

• RPGC : Couverture 1× du génome (nécessite --effectiveGenomeSize)
• CPM : Comptes par million de lectures alignées
• RPKM : Lectures par kb par million (mise à l'échelle par longueur de bin et taille de la bibliothèque)
• BPM : Bins par million, analogue à une mise à l'échelle de type TPM pour le signal par bins
• Aucune : Comptes bruts (non recommandé pour les comparaisons)

Explication complète : references/normalization_methods.md

Tailles effectives du génome

La normalisation RPGC nécessite la taille effective du génome. Valeurs courantes :

Organisme	Assemblage	Taille	Utilisation
Humain	GRCh38/hg38	2 913 022 398	--effectiveGenomeSize 2913022398
Humain	T2T/CHM13CAT_v2	3 117 292 070	--effectiveGenomeSize 3117292070
Souris	GRCm39/mm39	2 654 621 783	--effectiveGenomeSize 2654621783
Souris	GRCm38/mm10	2 652 783 500	--effectiveGenomeSize 2652783500
Poisson zèbre	GRCz11	1 368 780 147	--effectiveGenomeSize 1368780147
Drosophila	dm6	142 573 017	--effectiveGenomeSize 142573017
C. elegans	ce10/ce11	100 286 401	--effectiveGenomeSize 100286401

Tableau complet avec des valeurs spécifiques à la longueur de lecture : references/effective_genome_sizes.md

Paramètres communs à tous les outils

De nombreuses commandes deepTools partagent ces options :

Performance :

• --numberOfProcessors, -p : Activer le traitement parallèle (toujours utiliser les cœurs disponibles)
• max / max/2 : Valeurs prises en charge pour --numberOfProcessors ; utiles sous les ordonnanceurs car les versions récentes de deepTools détectent plus précisément l'affinité CPU
• --region : Traiter des régions spécifiques pour les tests (par ex. chr1:1-1000000)

Filtrage des lectures :

• --ignoreDuplicates : Supprimer les duplicats PCR (recommandé pour la plupart des analyses)
• --minMappingQuality : Filtrer par qualité d'alignement (par ex. --minMappingQuality 10)
• --minFragmentLength / --maxFragmentLength : Limites de longueur des fragments
• --samFlagInclude / --samFlagExclude : Filtrage par drapeaux SAM

Traitement des lectures :

• --extendReads : Étendre à la longueur du fragment (ChIP-seq : OUI, RNA-seq : NON)
• --centerReads : Centrer au point médian du fragment pour des signaux plus nets

Bonnes pratiques

Validation des fichiers

Validez toujours les fichiers d'abord à l'aide de scripts/validate_files.py pour vérifier :

• L'existence et la lisibilité des fichiers
• La présence des index BAM (fichiers .bai)
• La correction du format BED
• La taille raisonnable des fichiers

Stratégie d'analyse

1. Commencez par le QC : Effectuez l'analyse de corrélation, de couverture et d'empreinte avant de poursuivre
2. Testez sur de petites régions : Utilisez --region chr1:1-10000000 pour les tests de paramètres
3. Documentez les commandes : Enregistrez les lignes de commande complètes pour la reproductibilité
4. Utilisez une normalisation cohérente : Appliquez la même méthode à tous les échantillons dans les comparaisons
5. Vérifiez l'assemblage du génome : Assurez-vous que les fichiers BAM et BED utilisent des assemblages génomiques correspondants

Spécifique au ChIP-seq

• Étendez toujours les lectures pour le ChIP-seq : --extendReads 200
• Supprimez les duplicats : Utilisez --ignoreDuplicates dans la plupart des cas
• Vérifiez d'abord l'enrichissement : Exécutez plotFingerprint avant l'analyse détaillée
• Correction GC : Appliquez-la uniquement si un biais significatif est détecté ; n'utilisez jamais --ignoreDuplicates après la correction GC

Spécifique au RNA-seq

• N'étendez jamais les lectures pour le RNA-seq (cela traverserait les jonctions d'épissage)
• Spécificité de brin : Utilisez --filterRNAstrand forward/backward pour les bibliothèques stranded de type dUTP courantes ; confirmez l'orientation de la bibliothèque avant d'interpréter les étiquettes de brin
• Normalisation : CPM pour les bins, RPKM pour les gènes

Spécifique à l'ATAC-seq

• Appliquez la correction Tn5 : Utilisez alignmentSieve avec --ATACshift
• Utilisez uniquement les paires correctes pour le décalage : --ATACshift équivaut à --shift 4 -5 5 -4 et filtre pour ne conserver que les fragments correctement appariés
• Filtrage des fragments : Définissez des longueurs de fragment min/max appropriées
• Vérifiez le motif des nucléosomes : Le graphique de taille des fragments doit montrer un motif en échelle

Optimisation des performances

1. Utilisez plusieurs processeurs : --numberOfProcessors 8 (ou les cœurs disponibles)
2. Augmentez la taille du bin pour un traitement plus rapide et des fichiers plus petits
3. Traitez les chromosomes séparément pour les systèmes à mémoire limitée
4. Pré-filtrez les fichiers BAM à l'aide d'alignmentSieve pour créer des fichiers filtrés réutilisables
5. Utilisez bigWig plutôt que bedGraph : compressé et plus rapide à traiter

Dépannage

Problèmes courants

Index BAM manquant :

samtools index input.bam

Mémoire insuffisante : Traitez les chromosomes individuellement en utilisant --region :

bamCoverage --bam input.bam -o chr1.bw --region chr1

Traitement lent : Augmentez --numberOfProcessors et/ou augmentez --binSize

Fichiers bigWig trop volumineux : Augmentez la taille du bin : --binSize 50 ou plus

Erreurs de validation

Exécutez le script de validation pour identifier les problèmes :

python scripts/validate_files.py --bam *.bam --bed regions.bed

Les erreurs courantes et leurs solutions sont expliquées dans la sortie du script.

Documentation de référence

Cette compétence comprend une documentation de référence complète :

references/tools_reference.md

Documentation complète de toutes les commandes deepTools organisées par catégorie :

• Outils de traitement BAM et bigWig (9 outils)
• Outils de contrôle qualité (6 outils)
• Outils de visualisation (3 outils)
• Outils divers (3 outils, dont bigwigAverage)

Chaque outil comprend :

• Objectif et présentation
• Paramètres clés avec explications
• Exemples d'utilisation
• Notes importantes et bonnes pratiques

Utilisez cette référence lorsque : Les utilisateurs posent des questions sur des outils spécifiques, des paramètres ou une utilisation détaillée.

references/workflows.md

Exemples complets de workflow pour les analyses courantes :

• Workflow de contrôle qualité ChIP-seq
• Workflow d'analyse complète ChIP-seq
• Workflow de couverture RNA-seq
• Workflow d'analyse ATAC-seq
• Workflow de comparaison multi-échantillons
• Workflow d'analyse de régions de pics
• Conseils de dépannage et de performance

Utilisez cette référence lorsque : Les utilisateurs ont besoin de pipelines d'analyse complètes ou d'exemples de workflow.

references/normalization_methods.md

Guide complet des méthodes de normalisation :

• Explication détaillée de chaque méthode (RPGC, CPM, RPKM, BPM, etc.)
• Quand utiliser chaque méthode
• Formules et interprétation
• Guide de sélection par type d'expérience
• Pièges courants et solutions
• Tableau de référence rapide

Utilisez cette référence lorsque : Les utilisateurs posent des questions sur la normalisation, la comparaison d'échantillons ou la méthode à utiliser.

references/effective_genome_sizes.md

Valeurs des tailles effectives du génome et leur utilisation :

• Valeurs pour les organismes courants (humain, souris, drosophile, ver, poisson zèbre)
• Valeurs spécifiques à la longueur de lecture
• Méthodes de calcul
• Quand et comment utiliser dans les commandes
• Instructions de calcul pour les génomes personnalisés

Utilisez cette référence lorsque : Les utilisateurs ont besoin de la taille du génome pour la normalisation RPGC ou la correction du biais GC.

Scripts d'assistance

scripts/validate_files.py

Valide les fichiers BAM, bigWig et BED pour l'analyse deepTools. Vérifie l'existence des fichiers, les index et le format.

Utilisation :

python scripts/validate_files.py --bam echantillon1.bam echantillon2.bam \
    --bed sommets.bed --bigwig signal.bw

Quand l'utiliser : Avant de commencer une analyse, ou lors du dépannage d'erreurs.

scripts/workflow_generator.py

Génère des modèles de scripts bash personnalisables pour les workflows deepTools courants.

Workflows disponibles :

• chipseq_qc : Contrôle qualité ChIP-seq
• chipseq_analysis : Analyse complète ChIP-seq
• rnaseq_coverage : Couverture RNA-seq spécifique au brin
• atacseq : ATAC-seq avec correction Tn5

Utilisation :

# Lister les workflows
python scripts/workflow_generator.py --list

# Générer un workflow
python scripts/workflow_generator.py chipseq_qc -o qc.sh \
    --input-bam Input.bam --chip-bams "ChIP1.bam ChIP2.bam" \
    --genome-size 2913022398 --threads 8

# Exécuter le workflow généré
chmod +x qc.sh
./qc.sh

Quand l'utiliser : Les utilisateurs demandent des workflows standard ou ont besoin de modèles de scripts à personnaliser.

Ressources

assets/quick_reference.md

Carte de référence rapide avec les commandes les plus courantes, les tailles effectives du génome et le modèle de workflow typique.

Quand l'utiliser : Les utilisateurs ont besoin d'exemples de commandes rapides sans documentation détaillée.

Gestion des demandes des utilisateurs

Pour les nouveaux utilisateurs

1. Commencer par la vérification de l'installation
2. Valider les fichiers d'entrée à l'aide de scripts/validate_files.py
3. Recommander le workflow approprié en fonction du type d'expérience
4. Générer un modèle de workflow à l'aide de scripts/workflow_generator.py
5. Guider la personnalisation et l'exécution

Pour les utilisateurs expérimentés

1. Fournir des commandes d'outil spécifiques pour les opérations demandées
2. Référer aux sections appropriées dans references/tools_reference.md
3. Suggérer des optimisations et des bonnes pratiques
4. Proposer un dépannage pour les problèmes

Pour des tâches spécifiques

"Convertir BAM en bigWig" :

• Utilisez bamCoverage avec une normalisation appropriée
• Recommandez RPGC ou CPM en fonction du cas d'utilisation
• Fournissez la taille effective du génome pour l'organisme
• Suggérez les paramètres pertinents (extendReads, ignoreDuplicates, binSize)

"Vérifier la qualité ChIP" :

• Exécutez le workflow QC complet ou utilisez plotFingerprint spécifiquement
• Expliquez l'interprétation des résultats
• Suggérez des actions de suivi en fonction des résultats

"Créer une carte de chaleur" :

• Guidez le processus en deux étapes : computeMatrix → plotHeatmap
• Aidez à choisir le mode de matrice approprié (reference-point vs scale-regions)
• Suggérez des paramètres de visualisation et des options de clustering

"Comparer des échantillons" :

• Recommandez bamCompare pour la comparaison de deux échantillons
• Suggérez multiBamSummary + plotCorrelation pour plusieurs échantillons
• Guidez la sélection de la méthode de normalisation

Référencement de la documentation

Lorsque les utilisateurs ont besoin d'informations détaillées :

• Détails des outils : Dirigez vers des sections spécifiques dans references/tools_reference.md
• Workflows : Utilisez references/workflows.md pour les pipelines d'analyse complètes
• Normalisation : Consultez references/normalization_methods.md pour la sélection de la méthode
• Tailles du génome : Référencez references/effective_genome_sizes.md

Exemples d'interactions

Utilisateur : "J'ai besoin d'analyser mes données ChIP-seq"

Approche de réponse :

1. Demandez quels fichiers sont disponibles (BAM, pics, gènes)
2. Validez les fichiers à l'aide du script de validation
3. Générez un modèle de workflow chipseq_analysis
4. Personnalisez-le pour leurs fichiers et leur organisme spécifiques
5. Expliquez chaque étape au fur et à mesure de l'exécution du script

Utilisateur : "Quelle normalisation dois-je utiliser ?"

Approche de réponse :

1. Demandez le type d'expérience (ChIP-seq, RNA-seq, etc.)
2. Demandez l'objectif de la comparaison (au sein d'un échantillon ou entre échantillons)
3. Consultez le guide de sélection dans references/normalization_methods.md
4. Recommandez la méthode appropriée avec justification
5. Fournissez un exemple de commande avec paramètres

Utilisateur : "Créez une carte de chaleur autour du TSS"

Approche de réponse :

1. Vérifiez la disponibilité des fichiers bigWig et des annotations génomiques (fichier BED/GFF des TSS)
2. Guidez l'utilisation de computeMatrix pour calculer les scores dans les régions
3. Expliquez comment utiliser plotHeatmap et plotProfile pour visualiser
4. Suggérez des options de personnalisation (groupes, ordre de tri, palette de couleurs)