GATK

From Alliance Doc
Jump to navigation Jump to search
This site replaces the former Compute Canada documentation site, and is now being managed by the Digital Research Alliance of Canada.

Ce site remplace l'ancien site de documentation de Calcul Canada et est maintenant géré par l'Alliance de recherche numérique du Canada.

This page is a translated version of the page GATK and the translation is 100% complete.
Other languages:


La boîte d'outils Genome Analysis Toolkit (GATK) est 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

[name@server ~]$ module spider gatk


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

[name@server ~]$ module spider gatk/4.1.8.1


Comme vous pouvez voir, seul le module StdEnv/2020 est prérequis; chargez-le avec

[name@server ~]$ module load StdEnv/2020 gatk/4.1.8.1


Ou, puisque StdEnv/2020 est chargé par défaut, simplement

[name@server ~]$ module load gatk/4.1.8.1


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. 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

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.

java -jar GenomeAnalysisTK.jar PROGRAM OPTIONS

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

module load nixpkgs/16.09 gatk/3.8
java -jar "${EBROOTGATK}"/GenomeAnalysisTK.jar PROGRAM OPTIONS

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[1]

[traduction libre]
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.

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 :

module load apptainer
apptainer build gatk.sif docker://broadinstitute/gatk

ou, pour une version spécifique

module load apptainer
apptainer build gatk_VERSION.sif docker://broadinstitute/gatk:VERSION

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

gatk MarkDuplicates \
    -I input.bam \
    -O marked_duplicates.bam \
    -M marked_dup_metrics.txt 

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. 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. 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.

Références

Site web GATK

GATK et SPARK

Make GATK tools run faster