Cette page a été traduite par l'API Cloud Translation.
Switch to English

Exécuter le pipeline de bonnes pratiques GATK

Cette page explique comment exécuter un pipeline sur Google Cloud à l'aide des bonnes pratiques GATK 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.

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

Ce tutoriel utilise des composants facturables de Google Cloud, dont :

  • Instance
  • Cloud Storage.

Utilisez le Simulateur de coût pour générer une estimation des coûts en fonction de votre utilisation prévue. Les nouveaux utilisateurs de Cloud Platform peuvent bénéficier d'un essai gratuit.

Avant de commencer

  1. Connectez-vous à votre compte Google.

    Si vous n'en possédez pas déjà un, vous devez en créer un.

  2. Dans Google Cloud Console, sur la page de sélection du projet, sélectionnez ou créez un projet Google Cloud.

    Accéder à la page de sélection du projet

  3. Assurez-vous que la facturation est activée pour votre projet Cloud. Découvrez comment vérifier que la facturation est activée pour votre projet.

  4. Activer les API Cloud Life Sciences, Compute Engine, and Cloud Storage.

    Activer les API

  5. Installez et initialisez le SDK Cloud.
  6. Mettez à jour et installez les composants gcloud :
    gcloud components update &&
    gcloud components install beta
  7. Installez git pour télécharger les fichiers requis.

    Télécharger git

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

Créer un bucket Cloud Storage

Créez un bucket Cloud Storage à l'aide de la commande gsutil mb : N'utilisez pas de trait de soulignement (_) dans le nom du bucket. Vous risquez de rencontrer une erreur due à une exigence du moteur Cromwell.

gsutil mb gs://BUCKET

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

Télécharger les fichiers d'exemple

Téléchargez le script 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

Le fichier de définition de pipeline Cromwell utilisé pour exécuter les pipelines WDL se trouve dans le dépôt broadinstitute/wdl-runner/wdl_runner/.

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

Le pipeline fonctionne 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 :

    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/
    
  5. La commande renvoie un ID d'opération au format Running [operations/OPERATION_ID]. Vous pouvez utiliser l'ID d'opération pour suivre l'état du pipeline en exécutant 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 :

    gsutil 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 dans un bucket Cloud Storage :

gsutil -m -o 'GSUtil:parallel_composite_upload_threshold=150M' 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.

L'outil de ligne de commande gsutil vérifie toujours les sommes de contrôle automatiquement. Ainsi, quand le transfert aboutit, vos données sont compatibles avec l'utilisation des bonnes pratiques GATK.

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 devrez utiliser des flux de travail différents. Pour en savoir plus, consultez le forum d'assistance GATK et le dépôt GitHub du Broad Institute.

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 l'outil gcloud, il utilise automatiquement une région et une zone par défaut en fonction de l’emplacement dans lequel 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 :

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

gsutil du -sh gs://BUCKET/FOLDER/work

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

gsutil -m 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 :

  1. Dans Cloud Console, 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. Après avoir coché la case à côté du nom du projet, 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

  • Ce tutoriel explique comment exécuter un workflow prédéfini dans un cas d'utilisation limité, mais n'est pas conçu pour être exécuté en production. Pour en savoir plus sur le traitement des données génomiques dans un environnement de production sur Google Cloud, consultez la page Architecture de référence du traitement des données génomiques.
  • Le site GATK et les forums du Broad Institute fournissent des informations de contexte, une documentation et une assistance associés aux outils GATK et WDL.