Esegui le best practice GATK

Questa pagina spiega come eseguire una pipeline di analisi genomica secondaria su Google Cloud utilizzando le best practice del Genome Analysis Toolkit (GATK). Le best practice GATK sono fornite dal Broad Institute.

Il flusso di lavoro utilizzato in questo tutorial è un'implementazione delle best practice di GATK per la scoperta di varianti nei dati di sequenziamento dell'intero genoma (WGS). Il flusso di lavoro è scritto nel Workflow Definition Language (WDL) del Broad Institute e viene eseguito sul runner WDL Cromwell.

Obiettivi

Dopo aver completato questo tutorial, saprai come:

  • Esegui una pipeline utilizzando le best practice di GATK con i dati della build 38 del genoma di riferimento umano
  • Esegui una pipeline utilizzando le best practice GATK con i tuoi dati

Costi

In questo documento, utilizzi i seguenti componenti fatturabili di Google Cloud:

  • Compute Engine
  • Cloud Storage

Per generare una stima dei costi in base all'utilizzo previsto, utilizza il calcolatore prezzi.

I nuovi Google Cloud utenti potrebbero avere diritto a una prova gratuita.

Prima di iniziare

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud 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. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

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

    gcloud init

  8. After initializing the gcloud CLI, update it and install the required components: 

    gcloud components update
gcloud components install beta

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

    Go to project selector

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

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

    Enable the APIs

  12. Install the Google Cloud CLI.

  13. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

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

    gcloud init

  15. After initializing the gcloud CLI, update it and install the required components: 

    gcloud components update
gcloud components install beta
  16. Installa git per scaricare i file necessari.

    Scarica git

  17. Per impostazione predefinita, Compute Engine dispone di quote delle risorse per evitare utilizzi involontari. Aumentando le quote, puoi avviare più macchine virtuali contemporaneamente, il che aumenta il throughput e riduce il tempo di risposta.

    Per ottenere risultati ottimali in questo tutorial, devi richiedere una quota aggiuntiva rispetto a quella predefinita del tuo progetto. I consigli per gli aumenti di quota sono forniti nell'elenco seguente, così come le quote minime necessarie per eseguire il tutorial. Invia le richieste di quota nella regione us-central1:

    • CPU: 101 (minimo 17)
    • Disco permanente standard (GB): 10.500 (minimo 320)
    • Indirizzi IP in uso: 51 (minimo 2)

    Puoi lasciare vuoti gli altri campi della richiesta di quota per mantenere le quote attuali.

    18. Crea un bucket Cloud Storage

    Crea un bucket Cloud Storage utilizzando il comando gcloud storage buckets create. A causa di un requisito del motore Cromwell, non utilizzare il carattere trattino basso (_) nel nome del bucket, altrimenti si verificherà un errore.

    gcloud storage buckets create gs://BUCKET

    La pipeline restituisce risultati, log e file intermedi a questo bucket.

    Scarica i file di esempio

    Esegui i seguenti comandi per scaricare lo script WDL e helper:

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

    Il repository gatk-workflows/broad-prod-wgs-germline-snps-indels contiene i seguenti file necessari per eseguire la pipeline:

    • *.wdl: Definizione del workflow
    • *.inputs.json: Parametri di input, inclusi i percorsi dei file BAM e del genoma di riferimento
    • *.options.json: Opzioni di runtime del workflow

    Puoi trovare il file di definizione della pipeline Cromwell utilizzato per eseguire le pipeline WDL nel repository broadinstitute/wdl-runner/wdl_runner/.

    Esegui la pipeline utilizzando dati di esempio

    Questa sezione mostra come eseguire la pipeline con i dati WGS utilizzando la build 38 del genoma di riferimento umano. I file di input sono file BAM non allineati.

    Per eseguire la pipeline, completa i seguenti passaggi:

    1. Crea la variabile di ambiente GATK_GOOGLE_DIR che punta alla cartella contenente i file della pipeline Broad:

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

    2. Crea la variabile di ambiente GATK_OUTPUT_DIR che punta al bucket Cloud Storage e a una cartella per output del flusso di lavoro, ai file work intermedi e a logging:

      export GATK_OUTPUT_DIR=gs://BUCKET/FOLDER

    3. Passa alla cartella /wdl_runner nel repository che hai scaricato. Questa directory contiene il file di definizione della pipeline per l'esecuzione di pipeline basate su WDL su Google Cloud:

      cd wdl-runner/wdl_runner/

    4. Esegui la pipeline:

      Scegli una delle seguenti opzioni a seconda che utilizzi un VPC predefinito o un VPC personalizzato:

      VPC predefinito

      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 personalizzato

      1. Crea le variabili di ambiente NETWORK e SUBNETWORK per specificare il nome della rete VPC e della subnet:

        export NETWORK=VPC_NETWORK
export SUBNETWORK=VPC_SUBNET

      2. Modifica il file PairedEndSingleSampleWf.options.json che si trova nella directory broad-prod-wgs-germline-snps-indels e modifica le zone in modo da includere solo quelle all'interno della regione della subnet. Ad esempio, se utilizzi una subnet us-central1, il campo zones avrà il seguente aspetto: "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. Il comando restituisce un ID operazione nel formato Running [operations/OPERATION_ID]. Puoi utilizzare il comando gcloud beta lifesciences describe per monitorare lo stato della pipeline eseguendo il seguente comando (assicurati che il valore del flag --location corrisponda alla località specificata nel passaggio precedente):

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

    6. Il comando operations describe restituisce done: true al termine della pipeline.

      Puoi eseguire uno script incluso in wdl_runner per controllare ogni 300 secondi se il job è in esecuzione, è stato completato o ha restituito un errore:

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

    7. Al termine della pipeline, esegui il seguente comando per elencare gli output nel bucket Cloud Storage:

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

    Puoi visualizzare i file intermedi creati dalla pipeline e scegliere quali conservare o rimuoverli per ridurre i costi associati a Cloud Storage. Per rimuovere i file, consulta Eliminare i file intermedi nel bucket Cloud Storage.

    Esegui la pipeline di best practice GATK sui tuoi dati

    Prima di eseguire la pipeline sui dati locali, devi copiare i dati in un bucket Cloud Storage.

    Copia i file di input

    La pipeline può essere eseguita con file BAM non allineati archiviati in Cloud Storage. Se i tuoi file sono in un formato diverso, ad esempio BAM o FASTQ allineato, devi convertirli prima di poterli caricare in Cloud Storage. Puoi convertirli localmente oppure utilizzare l'API Pipelines per convertirli nel cloud.

    L'esempio seguente mostra come copiare un singolo file da un file system locale a un bucket Cloud Storage:

    gcloud storage cp FILE gs://BUCKET/FOLDER

    Per altri esempi di come copiare i file in un bucket Cloud Storage, consulta la sezione Copia dei dati in Cloud Storage.

    gcloud CLI verifica automaticamente i checksum, quindi quando il trasferimento va a buon fine, i tuoi dati sono compatibili per l'utilizzo con le procedure consigliate di GATK.

    Esegui la pipeline sui tuoi dati

    Per eseguire le best practice di GATK sui tuoi file BAM non allineati, crea una copia di PairedEndSingleSampleWf.hg38.inputs.json, poi aggiorna i percorsi in modo che puntino ai tuoi file in un bucket Cloud Storage. Puoi quindi seguire i passaggi descritti in Esegui la pipeline utilizzando i dati di esempio, utilizzando il file PairedEndSingleSampleWf.hg38.inputs.json aggiornato.

    Se i tuoi dati non sono costituiti da file BAM non allineati e contengono genomi di riferimento, sequenziamento dell'esoma, pannelli mirati e dati somatici, devi utilizzare flussi di lavoro diversi. Per maggiori informazioni, consulta il forum di assistenza GATK e il repository GitHub del Broad Institute.

    Risoluzione dei problemi

    • La pipeline è configurata per utilizzare le istanze Compute Engine in regioni e zone specifiche. Quando esegui gcloud CLI, utilizza automaticamente una regione e una zona predefinite in base alla località in cui è stato creato il tuo progetto Google Cloud . Ciò può comportare la visualizzazione del seguente messaggio di errore durante l'esecuzione della pipeline:

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

      Per risolvere il problema, rimuovi la regione e la zona predefinite eseguendo i seguenti comandi, quindi esegui di nuovo la pipeline:

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

      Per ulteriori informazioni sull'impostazione della regione e della zona predefinite per il tuo progettoGoogle Cloud , consulta Modifica della zona o della regione predefinita.

    • Se riscontri problemi durante l'esecuzione della pipeline, consulta Risoluzione dei problemi dell'API Cloud Life Sciences.

    • GATK ha aspettative rigorose sui formati dei file di input. Per evitare problemi, puoi verificare che i tuoi file superino il test ValidateSamFile.

    • Se l'esecuzione di GATK non va a buon fine, puoi controllare i log eseguendo il seguente comando:

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

    • Se si verificano errori di autorizzazione, verifica che il tuo service account disponga dell'accesso in lettura ai file di input e dell'accesso in scrittura al percorso del bucket di output. Se stai scrivendo file di output in un bucket di un progettoGoogle Cloud che non è tuo, devi concedere all'account di servizio l'autorizzazione per accedere al bucket.

    Pulizia

    Eliminazione dei file intermedi nel bucket Cloud Storage

    Quando esegui la pipeline, archivia i file intermedi in gs://BUCKET/FOLDER/work. Puoi rimuovere i file al termine del flusso di lavoro per ridurre i costi di Cloud Storage.

    Per visualizzare la quantità di spazio utilizzato nella directory work, esegui questo comando. L'esecuzione del comando potrebbe richiedere diversi minuti a causa delle dimensioni dei file nella directory.

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

    Per rimuovere i file intermedi nella directory work, esegui questo comando:

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

    Eliminazione del progetto

    Il modo più semplice per eliminare la fatturazione è quello di eliminare il progetto utilizzato per il tutorial.

    Per eliminare il progetto:

    1. Nella console Google Cloud , vai alla pagina Progetti.

      Vai alla pagina Progetti

    2. Nell'elenco dei progetti, selezionare quello da eliminare e fai clic su Elimina progetto. Dopo aver selezionato la casella di controllo accanto al nome del progetto, fai clic su Elimina progetto.
    3. Nella finestra di dialogo, digita l'ID del progetto e fai clic su Chiudi per eliminare il progetto.

    Passaggi successivi

    • Il sito e i forum del Broad Institute forniscono ulteriori informazioni di base, documentazione e supporto per gli strumenti GATK e WDL.