Exécuter un pipeline à l'aide des bonnes pratiques GATK

Remarque:Ce tutoriel explique comment exécuter un workflow prédéfini dans un contexte d'utilisation limitée mais n'est pas destiné à être exécuté en production.

Cette page explique comment exécuter un pipeline d'analyse génomique secondaire sur Google Cloud à l'aide des bonnes pratiques GATK (Genome Analysis Toolkit). Les bonnes pratiques GATK sont fournies par le Broad Institute.

Le workflow utilisé dans ce tutoriel est une mise en œuvre des bonnes pratiques GATK pour la découverte de variantes dans les données de séquençage du génome entier (WGS). Il est écrit dans le langage de définition de workflow (WDL) du Broad Institute et fonctionne sur l'exécuteur WDL Cromwell.

Remarque : Vous êtes tenu responsable du respect des conditions du Contrat de licence utilisateur final GATK, y compris du critère d'attribution.

Objectifs

À la fin de ce tutoriel, vous saurez :

• exécuter un pipeline à l'aide des bonnes pratiques GATK avec les données issues de la version 38 du génome de référence humain ;
• exécuter un pipeline à l'aide des bonnes pratiques GATK avec vos propres données.

Coûts

Dans ce document, vous utilisez les composants facturables suivants de Google Cloud :

• Compute Engine
• Cloud Storage

Obtenez une estimation des coûts en fonction de votre utilisation prévue à l'aide du simulateur de coût. Les nouveaux utilisateurs de Google Cloud peuvent bénéficier d'un essai gratuit.

Avant de commencer

1. Connectez-vous à votre compte Google Cloud. Si vous débutez sur Google Cloud, créez un compte pour évaluer les performances de nos produits en conditions réelles. Les nouveaux clients bénéficient également de 300 $ de crédits gratuits pour exécuter, tester et déployer des charges de travail.

2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

3. Make sure that billing is enabled for your Google Cloud project.

4. Enable the Cloud Life Sciences, Compute Engine, and Cloud Storage APIs.

   Enable the APIs

5. Install the Google Cloud CLI.

6. To initialize the gcloud CLI, run the following command:

   gcloud init

7. Update and install gcloud components:

   gcloud components update
   gcloud components install beta

8. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

9. Make sure that billing is enabled for your Google Cloud project.

10. Enable the Cloud Life Sciences, Compute Engine, and Cloud Storage APIs.

    Enable the APIs

11. Install the Google Cloud CLI.

12. To initialize the gcloud CLI, run the following command:

    gcloud init

13. Update and install gcloud components:

    gcloud components update
    gcloud components install beta

14. Installez git pour télécharger les fichiers requis.

    Télécharger git

15. Par défaut, Compute Engine a mis en place des quotas de ressources qui permettent d'éviter toute utilisation accidentelle. En augmentant les quotas, vous pouvez lancer plus de machines virtuelles simultanément, ce qui augmente le débit et réduit les délais d'exécution.

    Pour réussir au mieux ce tutoriel, vous devez demander un quota supplémentaire par rapport au quota par défaut de votre projet. La liste suivante contient des recommandations sur l’augmentation des quotas, ainsi que sur les quotas minimaux nécessaires à l’exécution du tutoriel. Effectuez vos demandes de quota dans la région us-central1 :

    • Processeurs : 101 (minimum 17)
    • Disque persistant standard (Go) : 10 500 (minimum 320)
    • Adresses IP en cours d'utilisation : 51 (minimum 2)

    Vous pouvez laisser vides les autres champs de la demande pour conserver vos quotas actuels.

    Remarque : Si votre projet a été créé dans le cadre de l'essai gratuit, vous devez demander des quotas plus élevés pour pouvoir exécuter les bonnes pratiques GATK sur GCP.

Créer un bucket Cloud Storage

Créer un bucket Cloud Storage à l'aide de gcloud storage buckets create . En raison d'une exigence du moteur Cromwell, n'utilisez pas de trait de soulignement (_) dans le nom du bucket pour éviter une erreur.

gcloud storage buckets create gs://BUCKET

Le pipeline génère les résultats, les journaux et les fichiers intermédiaires dans ce bucket.

Télécharger les fichiers d'exemple

Exécutez les commandes suivantes pour télécharger le fichier WDL et le script d'aide :

git clone https://github.com/broadinstitute/wdl-runner.git
git clone https://github.com/gatk-workflows/broad-prod-wgs-germline-snps-indels.git

Le dépôt gatk-workflows/broad-prod-wgs-germline-snps-indels contient les fichiers nécessaires à l'exécution du pipeline :

• *.wdl : définition du workflow
• *.inputs.json : paramètres d'entrée, y compris les chemins d'accès aux fichiers BAM et au génome de référence
• *.options.json : options d'exécution du workflow

Vous trouverez le fichier de définition de pipeline Cromwell utilisé pour exécuter des pipelines WDL dans l'instance broadinstitute/wdl-runner/wdl_runner/ un dépôt de clés.

Exécuter le pipeline à l'aide de données d'échantillons

Cette section explique comment exécuter le pipeline avec des données WGS à l'aide de la version 38 du génome de référence humain. Les fichiers d'entrée sont des fichiers BAM non alignés.

Pour exécuter le pipeline, procédez comme suit :

1. Créez la variable d'environnement GATK_GOOGLE_DIR qui pointe vers le dossier contenant les fichiers de pipeline Broad :

   export GATK_GOOGLE_DIR="${PWD}"/broad-prod-wgs-germline-snps-indels

2. Créez la variable d'environnement GATK_OUTPUT_DIR qui pointe vers le bucket et un dossier Cloud Storage pour la sortie (output) du workflow, les fichiers work intermédiaires et la journalisation (logging) :

   export GATK_OUTPUT_DIR=gs://BUCKET/FOLDER

3. Remplacez le répertoire par le dossier /wdl_runner du dépôt que vous avez téléchargé. Ce répertoire contient le fichier de définition de pipeline pour l'exécution sur Google Cloud de pipelines basés sur WDL :

   cd wdl-runner/wdl_runner/

4. Exécutez le pipeline :

   Important: : Si le message d'erreur "ERROR: (gcloud.beta.lifesciences.pipelines.run) INVALID_ARGUMENT: Error: validating pipeline: zones and regions cannot be specified together" s'affiche, consultez la section Dépannage.

   Choisissez l'une des options suivantes selon que vous utilisez un VPC par défaut ou un VPC personnalisé :

   VPC par défaut

   gcloud beta lifesciences pipelines run \
   --pipeline-file wdl_pipeline.yaml \
   --location us-central1 \
   --regions us-central1 \
   --inputs-from-file WDL=${GATK_GOOGLE_DIR}/PairedEndSingleSampleWf.wdl,\
   WORKFLOW_INPUTS=${GATK_GOOGLE_DIR}/PairedEndSingleSampleWf.hg38.inputs.json,\
   WORKFLOW_OPTIONS=${GATK_GOOGLE_DIR}/PairedEndSingleSampleWf.options.json \
   --env-vars WORKSPACE=${GATK_OUTPUT_DIR}/work,\
   OUTPUTS=${GATK_OUTPUT_DIR}/output \
   --logging ${GATK_OUTPUT_DIR}/logging/

   VPC personnalisé

   1. Créez les variables d'environnement NETWORK et SUBNETWORK pour spécifier les noms du réseau et du sous-réseau VPC :

      export NETWORK=VPC_NETWORK
      export SUBNETWORK=VPC_SUBNET

   2. Modifiez le fichier PairedEndSingleSampleWf.options.json situé dans le répertoire broad-prod-wgs-germline-snps-indels, puis modifiez les zones afin de n'inclure que les zones de la région de votre sous-réseau. Par exemple, si vous utilisez un sous-réseau us-central1, le champ zones doit ressembler à ceci : "zones": "us-central1-a us-central1-b us-central1-c us-central1-f".

   3. gcloud beta lifesciences pipelines run \
      --pipeline-file wdl_pipeline.yaml \
      --location us-central1 \
      --regions us-central1 \
      --network ${NETWORK} \
      --subnetwork ${SUBNETWORK} \
      --inputs-from-file WDL=${GATK_GOOGLE_DIR}/PairedEndSingleSampleWf.wdl,\
      WORKFLOW_INPUTS=${GATK_GOOGLE_DIR}/PairedEndSingleSampleWf.hg38.inputs.json,\
      WORKFLOW_OPTIONS=${GATK_GOOGLE_DIR}/PairedEndSingleSampleWf.options.json \
      --env-vars WORKSPACE=${GATK_OUTPUT_DIR}/work,\
      OUTPUTS=${GATK_OUTPUT_DIR}/output,\
      NETWORK=${NETWORK},\
      SUBNETWORK=${SUBNETWORK} \
      --logging ${GATK_OUTPUT_DIR}/logging/

5. La commande renvoie un ID d'opération au format Running [operations/OPERATION_ID]. Vous pouvez utiliser la commande gcloud beta lifesciences describe pour suivre l'état du pipeline. Exécutez pour cela la commande suivante (assurez-vous que la valeur de l'option --location correspond à l'emplacement spécifié à l'étape précédente) :

   gcloud beta lifesciences operations describe OPERATION_ID \
       --location=us-central1 \
       --format='yaml(done, error, metadata.events)'

6. La commande operations describe renvoie done: true une fois le pipeline terminé.

   Vous pouvez exécuter un script fourni avec wdl_runner pour vérifier toutes les 300 secondes si la tâche est en cours d'exécution, si elle est terminée ou si elle a renvoyé une erreur :

   ../monitoring_tools/monitor_wdl_pipeline.sh OPERATION_ID us-central1 300

7. Une fois le pipeline terminé, exécutez la commande suivante pour répertorier les résultats dans votre bucket Cloud Storage :

   gcloud storage ls gs://BUCKET/FOLDER/output/

Vous pouvez afficher les fichiers intermédiaires créés par le pipeline et sélectionner ceux que vous souhaitez conserver, ou les supprimer pour réduire les coûts associés à Cloud Storage. Pour supprimer les fichiers, reportez-vous à la section Supprimer des fichiers intermédiaires du bucket Cloud Storage.

Exécuter le pipeline des bonnes pratiques GATK sur vos données

Avant d'exécuter le pipeline sur vos données locales, vous devez les copier dans un bucket Cloud Storage.

Copier les fichiers d'entrée

Le pipeline peut s'exécuter avec des fichiers BAM non alignés, stockés dans Cloud Storage. Si vous avez des fichiers dans un format différent, comme des fichiers BAM ou FASTQ alignés, vous devez les convertir avant de pouvoir les importer sur Cloud Storage. Vous pouvez réaliser cette opération localement ou utiliser l'API Pipelines pour les convertir dans le cloud.

L'exemple suivant montre comment copier un seul fichier d'un système de fichiers local vers un bucket Cloud Storage :

gcloud storage cp FILE gs://BUCKET/FOLDER

Pour plus d'exemples sur la copie de fichiers dans un bucket Cloud Storage, consultez la section Copier des données dans Cloud Storage.

La gcloud CLI vérifie automatiquement les sommes de contrôle. Ainsi, lorsque transfert réussi, vos données peuvent être utilisées avec le pratiques.

Exécuter le pipeline sur vos données

Pour exécuter les bonnes pratiques GATK sur vos propres fichiers BAM non alignés, effectuez une copie de PairedEndSingleSampleWf.hg38.inputs.json, puis une mise à jour des chemins d'accès à vos fichiers dans un bucket Cloud Storage. Vous pouvez ensuite suivre les étapes présentées dans la section Exécuter le pipeline à l'aide de données d'échantillons en utilisant le fichier PairedEndSingleSampleWf.hg38.inputs.json.

Si vos données ne sont pas composées de fichiers BAM non alignés et contiennent des génomes de référence, un séquençage des exomes, des panels ciblés et des données somatiques, vous devez utiliser des workflows différents. Consultez le forum d'assistance GATK. et le dépôt GitHub du Broad Institute pour en savoir plus.

Dépannage

• Le pipeline est configuré pour utiliser des instances Compute Engine dans des régions et des zones spécifiques. Lorsque vous exécutez la gcloud CLI, elle utilise automatiquement une région et une zone par défaut selon l'emplacement où votre projet Google Cloud a été créé. Il se peut que le message d'erreur suivant s'affiche lors de l'exécution du pipeline :

  "ERROR: (gcloud.beta.lifesciences.pipelines.run) INVALID_ARGUMENT: Error: validating pipeline: zones and regions cannot be specified together"

  Pour résoudre ce problème, supprimez la région et la zone par défaut en exécutant les commandes suivantes, puis exécutez de nouveau le pipeline :

  gcloud config unset compute/zone
  gcloud config unset compute/region
  

  Pour en savoir plus sur la configuration de la région et de la zone par défaut de votre projet Google Cloud, consultez la page Modifier la région ou la zone par défaut.

• Si vous rencontrez des problèmes lors de l'exécution du pipeline, consultez la page Dépannage de l'API Cloud Life Sciences.

• Les exigences de GATK sont strictes en matière de format des fichiers d'entrée. Pour éviter les problèmes, vous pouvez confirmer la validité de vos fichiers à l'aide de ValidateSamFile.

• Si votre exécution GATK échoue, vous pouvez consulter les journaux à l'aide de la commande suivante :

  gcloud storage ls gs://BUCKET/FOLDER/logging

• Si vous rencontrez des erreurs d'autorisation, vérifiez que votre compte de service dispose de l'accès en lecture aux fichiers d'entrée et de l'accès en écriture au chemin d'accès du bucket de sortie. Si vous écrivez des fichiers de sortie dans un bucket situé dans un projet Google Cloud qui n'est pas le vôtre, vous devez autoriser le compte de service à accéder au bucket.

Nettoyer

Supprimer des fichiers intermédiaires du bucket Cloud Storage

Lorsque vous exécutez le pipeline, celui-ci stocke les fichiers intermédiaires dans le répertoire gs://BUCKET/FOLDER/work. Vous pouvez supprimer ces fichiers une fois le workflow terminé afin de réduire les frais générés par Cloud Storage.

Pour afficher la quantité d'espace utilisée dans le répertoire work, exécutez la commande suivante. L'exécution de la commande peut prendre plusieurs minutes en raison de la taille des fichiers du répertoire.

gcloud storage du gs://BUCKET/FOLDER/work --readable-sizes --summarize

Pour supprimer les fichiers intermédiaires du répertoire work, exécutez la commande suivante :

gcloud storage rm gs://BUCKET/FOLDER/work/**

Supprimer le projet

Le moyen le plus simple d'empêcher la facturation est de supprimer le projet que vous avez utilisé dans le cadre de ce tutoriel.

Pour supprimer le projet :

Avertissement : La suppression d'un projet entraîne les conséquences suivantes :

• Si vous avez utilisé un projet existant, vous supprimerez également tout autre travail effectué dans le projet.
• Vous ne pouvez pas réutiliser l'ID d'un projet supprimé. Si vous avez créé un ID de projet personnalisé que vous prévoyez d'utiliser à l'avenir, supprimez les ressources du projet. Cette étape permet de garantir que les URL qui utilisent l'ID du projet, telles qu'une URL appspot.com, restent disponibles.

Si vous consultez plusieurs tutoriels et guides de démarrage rapide, vous pouvez constater que réutiliser des projets au lieu de les supprimer vous évite de dépasser les limites de quotas des projets.

1. Dans la console Google Cloud, accédez à la page "Projets".

   Accéder à la page Projets

2. Dans la liste des projets, sélectionnez celui que vous souhaitez supprimer, puis cliquez sur Supprimer le projet.
3. Dans la boîte de dialogue, saisissez l'ID du projet, puis cliquez sur Arrêter pour supprimer le projet.

Étape suivante

• Le site GATK et les forums du Broad Institute fournissent des informations de contexte, une documentation et une assistance pour les outils GATK et WDL.