GATK/fr
Le Genome Analysis Toolkit (GATK) est une boîte à outils conçue pour l'analyse bioinformatique des données de séquençage haut débit (HTS) et du format Variant Call (VCF). Elle est beaucoup employée pour la découverte des variantes courtes des lignées germinales à partir de données de séquençage du génome entier et de l'exome. GATK est à l'avant-plan de la recherche génomique en termes de meilleures pratiques.
Charger un module¶
Plusieurs versions sont disponibles sur nos grappes. Pour obtenir l'information sur la version, lancez la commande :
Vous obtiendrez de l'information sur GATK et les versions :
gatk/3.7
gatk/3.8
gatk/4.0.0.0
gatk/4.0.8.1
gatk/4.0.12.0
gatk/4.1.0.0
gatk/4.1.2.0
gatk/4.1.7.0
gatk/4.1.8.0
gatk/4.1.8.1
gatk/4.2.2.0
gatk/4.2.4.0
gatk/4.2.5.0
Pour plus d'information sur une version particulière, utilisez :
Comme vous pouvez voir, seul le module StdEnv/2020 est prérequis; chargez-le avec :
Ou, puisque StdEnv/2020 est chargé par défaut, simplement :
Utilisation¶
Les versions plus récentes (>=4.0.0.0) offrent un enveloppeur (wrapper) pour les exécutables Java (.jar). En chargeant les modules GATK, vous obtiendrez la plupart des variables d'environnement nécessaires.
La commande module spider fournit des renseignements sur l'utilisation ainsi que des exemples.
Usage
=====
gatk [--java-options "-Xmx4G"] ToolName [GATK args]
Examples
========
gatk --java-options "-Xmx8G" HaplotypeCaller -R reference.fasta -I input.bam -O output.vcf
Dans cet exemple, vous avez probablement remarqué que certains arguments sont directement passés à Java avec les --java-options, comme la mémoire maximale du tas (heap memory) de -Xmx8G réservée pour l'instance.
Tip
Nous recommandons de toujours utiliser -DGATK_STACKTRACE_ON_USER_EXCEPTION=true puisque vous obtiendrez plus d'information pour le débogage en cas d'échec du programme. Assurez-vous que toutes les options passées par --java-options sont entre guillemets (").
Utilisation sur nos grappes¶
Optimisation des fichiers temporaires et des E/S
Pour les tâches sbatch, nous recommandons l'option --tmp-dir avec la configuration ${SLURM_TMPDIR}; les fichiers temporaires sont alors redirigés vers le stockage local.
Si vous utilisez GenomicsDBImport, assurez-vous que l'option --genomicsdb-shared-posixfs-optimizations est activée; ceci peut optimiser l'utilisation et la performance avec des systèmes de fichiers partagés Posix comme NFS et Lustre. Si ce n'est pas possible ou si vous utilisez GNU Parallel pour exécuter plusieurs intervalles simultanément, copiez votre base de données dans ${SLURM_TMPDIR} et lancez-y l'exécution afin d'éviter que les opérations d'entrée-sortie perturbent le système de fichiers; comme ${SLURM_TMPDIR} est un espace de stockage local, il est plus rapide et les opérations d'entrées-sortie n'affectent pas les autres utilisateurs et utilisatrices.
Versions antérieures à GATK 4¶
Les versions antérieures n'offrent pas la commande gatk; invoquez plutôt le fichier jar.
GenomeAnalysisTK.jar doit se trouver dans PATH. Sur nos grappes, les variables d'environnement $EBROOTPICARD pour Picard (dans GATK >= 4) et $EBROOTGATK pour GATK contiennent le chemin vers le fichier jar. Ainsi, pour appeler GATK <= 3, lancez :
Pour les particularités de GATK <= 3, voyez le guide GATK3.
Utilisation avec plusieurs cœurs¶
La plupart des outils GATK (>=4) ne peuvent pas utiliser plusieurs cœurs par défaut; vous devriez donc demander un seul cœur quand vous faites appel à ce type d'outil. Pour certains calculs, quelques outils utilisent des fils (par exemple Mutect2 avec --native-pair-hmm-threads) et donc vous pouvez demander plus de CPU, dans certains cas jusqu'à 4 fils. Quelques commandes Spark sont cependant disponibles avec GATK4.
Spark n'est pas utilisé par tous les outils GATK.
Les outils qui utilisent GATK le mentionnent dans leur documentation respective.
Certains outils GATK ont des versions qui supportent Spark et d'autres non. Les noms des versions pouvant travailler avec Spark ont le suffixe spark. Plusieurs de ces versions sont encore au stade expérimental, mais nous prévoyons éventuellement n'offrir qu'une version par outil.
Certains outils GATX n'ont qu'une version qui supporte Spark; leurs noms n'ont pas le suffixe spark.
--- tiré de GATK et SPARK
Avec les commandes qui utilisent Spark, vous pouvez demander plusieurs CPU. Veuillez indiquer le nombre exact de CPU dans la commande Spark; par exemple, si vous demandez 10 CPU, utilisez --spark-master local[10] plutôt que --spark-master local[*]. Pour travailler en multinœuds, vous devez d'abord déployer une grappe Spark puis configurer les variables appropriées dans la commande GATK.
Travailler avec Apptainer¶
Si vous obtenez des erreurs comme IllegalArgumentException dans votre utilisation des modules installés sur nos grappes, nous vous recommandons d'essayer de travailler autrement en passant par Apptainer.
Vous pouvez trouver une image Docker ici ainsi que d'autres versions sur cette page. Vous devez d'abord construire une image Apptainer à partir d'une image Docker. Pour obtenir les plus récentes versions, lancez les commandes suivantes sur la grappe :
ou, pour une version spécifique :
Dans votre script SBATCH, vous devriez utiliser quelque chose comme :
module load apptainer
apptainer exec -B /home -B /project -B /scratch -B /localscratch \
<path to the image>/gatk.sif gatk [--java-options "-Xmx4G"] ToolName [GATK args]
Pour plus d'information sur Apptainer, visionnez ce séminaire web.
Foire aux questions¶
Ajouter une étiquette RG (read group) dans un fichier bam¶
Pour ajouter une étiquette (nommée ici tag) au fichier input.bam, vous pouvez utiliser la commande GATK/PICARD AddOrReplaceReadGroups :
gatk AddOrReplaceReadGroups \
-I input.bam \
-O output.bam \
--RGLB tag \
--RGPL ILLUMINA \
--RGPU tag \
--RGSM tag \
--SORT_ORDER 'coordinate' \
--CREATE_INDEX true
Ceci suppose que votre fichier en entrée est trié selon les coordonnées et qu'un index est généré avec le résultat annoté (--CREATE_INDEX true).
Message java.lang.OutOfMemoryError: Java heap space¶
Les sous-programmes GATK nécessitent souvent plus de mémoire pour traiter vos fichiers. Si vous n'utilisiez pas la commande -Xms, ajoutez-la à --java-options. Par exemple, vous lanceriez :
Si vous obtenez l'erreur java.lang.OutOfMemoryError: Java heap space, essayez ceci :
gatk MarkDuplicates \
--java-options "-Xmx8G -DGATK_STACKTRACE_ON_USER_EXCEPTION=true" \
-I input.bam \
-O marked_duplicates.bam \
-M marked_dup_metrics.txt
Si ça ne fonctionne toujours pas, essayez d'augmenter la mémoire jusqu'à ce que vous trouviez la capacité nécessaire à votre ensemble de données.
Warning
N'oubliez pas de demander suffisamment de mémoire quand vous travaillez dans nos systèmes.
Pour en apprendre davantage au sujet du tas avec Java, lisez ceci.
Augmenter la mémoire pour le tas donne toujours l'erreur java.lang.OutOfMemoryError: Java heap space¶
Dans certains cas, le fait d'augmenter la mémoire ne résout pas le problème. Ceci se produit souvent avec des organismes qui ne sont pas des modèles et quand vos références sont trop échafaudées. Nous vous recommandons alors de supprimer les niveaux moins importants et de créer des sous-ensembles pour vos références. Par conséquent, vous devrez effectuer plusieurs MAPS et exécuter les pipelines dans chacun des sous-ensembles.
Approche de sous-ensembles
Cette approche ne fonctionne pas pour tous les pipelines, donc révisez bien les résultats obtenus. La boîte à outils GATK est conçue en fonction du génome humain; plusieurs paramètres et pipelines doivent être adaptés pour d'autres organismes.
Utiliser plus de ressources que ce qui a été demandé¶
Les applications GATK/JAVA utilisent souvent plus de mémoire ou de CPU et de fils que ce qui a été demandé. Ceci est souvent dû au processus de Garbage Collection de Java. Pour contourner ceci, vous pouvez ajouter -XX:ConcGCThreads=1 à l'argument --java-options.
Foire aux questions de GATK¶
Voir Troubleshooting GATK4 Issues.