Esegui le best practice di GATK

Avviso: questo tutorial mostra come eseguire un flusso di lavoro predefinito in un uso limitato ma non è destinato all'esecuzione in produzione. Per informazioni su come di eseguire l'elaborazione dei dati genomici in un ambiente di produzione su Google Cloud, consulta l'articolo sull'architettura di riferimento per l'elaborazione dei dati genomici.

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

Il flusso di lavoro utilizzato in questo tutorial è un'implementazione degli strumenti GATK Best Pratiche per la scoperta di varianti nei dati di sequenziamento dell'intero genoma (WGS). Il flusso di lavoro è scritto nel flusso di lavoro del Broad Institute's Workflows Definition Language (WDL) e funziona sul circuito Cromwell WDL runner.

Nota: è tua responsabilità rispettare i termini di il Contratto di licenza con l'utente finale GATK, incluso il requisito di attribuzione.

Obiettivi

Dopo aver completato questo tutorial, saprai come:

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

Costi

In questo documento vengono utilizzati i seguenti componenti fatturabili di Google Cloud:

• Compute Engine
• Cloud Storage

Per generare una stima dei costi basata sull'utilizzo previsto, utilizza il Calcolatore prezzi. I nuovi utenti di Google Cloud potrebbero essere idonei per una prova gratuita.

Prima di iniziare

1. Accedi al tuo account Google Cloud. Se non conosci Google Cloud, crea un account per valutare le prestazioni dei nostri prodotti in scenari reali. I nuovi clienti ricevono anche 300 $di crediti gratuiti per l'esecuzione, il test e il deployment dei carichi di lavoro.

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. Assicurati che la fatturazione sia attivata per il tuo progetto Google Cloud.

4. Abilita le API Cloud Life Sciences, Compute Engine, and Cloud Storage.

   Abilita le API

5. Installa Google Cloud CLI.

6. Per initialize gcloud CLI, esegui questo comando:

   gcloud init

7. Aggiorna e installa i componenti di gcloud:

   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. Assicurati che la fatturazione sia attivata per il tuo progetto Google Cloud.

10. Abilita le API Cloud Life Sciences, Compute Engine, and Cloud Storage.

    Abilita le API

11. Installa Google Cloud CLI.

12. Per initialize gcloud CLI, esegui questo comando:

    gcloud init

13. Aggiorna e installa i componenti di gcloud:

    gcloud components update
    gcloud components install beta

14. Installa git per scaricare i file richiesti.

    Scarica Git

15. Per impostazione predefinita, Compute Engine prevede le quote delle risorse per evitare utilizzi involontari. Aumentando le quote, puoi avviare di macchine virtuali contemporaneamente, con conseguente aumento della velocità effettiva e i tempi di risposta.

    Per ottenere i migliori risultati in questo tutorial, devi: richiedere una quota aggiuntiva rispetto a quello predefinito del progetto. I suggerimenti per gli aumenti della quota sono forniti nella seguente e le quote minime necessarie per eseguire il tutorial. Effettua le tue richieste di quota nella regione us-central1:

    • CPU: 101 (minimo 17)
    • Persistent Disk Standard (GB): 10.500 (minimo 320)
    • Indirizzi IP in uso: 51 (minimo 2)

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

    Nota: se il progetto è stato creato utilizzando la prova gratuita, devi richiedere quote più elevate per eseguire le best practice GATK in Google Cloud.

Crea un bucket Cloud Storage

Crea un bucket Cloud Storage utilizzando il comando gsutil mb. A causa di un nel motore Cromwell, non utilizzare il trattino basso (_) nel nome del bucket, altrimenti riscontrerai un errore.

gsutil mb gs://BUCKET

La pipeline invia risultati, log e file intermedi a questo di sincronizzare la directory di una VM con un bucket.

Scarica i file di esempio

Esegui questi 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

gatk-workflows/broad-prod-wgs-germline-snps-indels contiene i seguenti file necessari esegui la pipeline:

• *.wdl: definizione del flusso di lavoro
• *.inputs.json: parametri di input, inclusi i percorsi dei file BAM e genoma di riferimento
• *.options.json: opzioni di runtime del flusso di lavoro

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

Esegui la pipeline utilizzando dati di esempio

Questa sezione mostra come eseguire la pipeline con 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 contenenti i file Broad pipeline:

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

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

   export GATK_OUTPUT_DIR=gs://BUCKET/FOLDER
   

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

   cd wdl-runner/wdl_runner/
   

4. Esegui la pipeline:

   Importante: se visualizzi il messaggio di errore "ERROR: (gcloud.beta.lifesciences.pipelines.run) INVALID_ARGUMENT: Error: validating pipeline: zones and regions cannot be specified together", consulta la sezione Risoluzione dei problemi.

   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 e della subnet VPC:

      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 tua subnet. Ad esempio, se utilizzi una subnet us-central1, il campo zones sarà simile a questo: "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 lo gcloud beta lifesciences describe per monitorare lo stato della pipeline eseguendo questo comando: (assicurati che il valore del flag --location corrisponda alla posizione 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 quando la pipeline finiture in cui sono finite.

   Puoi eseguire uno script incluso con wdl_runner per eseguire un controllo 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 questo comando per elencare gli output nel tuo bucket Cloud Storage:

   gsutil ls gs://BUCKET/FOLDER/output/
   

Puoi visualizzare i file intermedi creati dalla pipeline e scegliere quali conservare o rimuoverle per ridurre i costi associate a Cloud Storage. Per rimuovere i file, consulta l'articolo sull'eliminazione dei 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 e copiare i dati in un bucket Cloud Storage.

Copia file di input

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

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

gsutil -m -o 'GSUtil:parallel_composite_upload_threshold=150M' cp FILE \
    gs://BUCKET/FOLDER

Per altri esempi su come copiare i file in un bucket Cloud Storage, vedi Copia di dati in Cloud Storage.

Lo strumento a riga di comando gsutil verifica automaticamente i checksum, quindi quando il trasferimento va a buon fine, i tuoi dati sono compatibili per l'uso con il Pratiche.

Esegui la pipeline sui tuoi dati

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

Se i dati non sono costituiti da file BAM non allineati e contengono riferimenti genomi, sequenziamento degli esoma, riquadri mirati e dati somatici, devi usare flussi di lavoro diversi. Consulta il forum di assistenza di GATK e il repository GitHub di Broad Institute per ulteriori informazioni.

Risoluzione dei problemi

• La pipeline è configurata per utilizzare le istanze di Compute Engine 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 progetto Google Cloud. Questo può comportare il 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 questo comando ed 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 nel progetto Google Cloud, consulta Modifica della zona o della regione predefinite.

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

• GATK ha aspettative rigide in merito ai formati dei file di input. Per evitare problemi, verificare che i file superino ValidateSamFile.

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

  gsutil ls gs://BUCKET/FOLDER/logging
  

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

esegui la pulizia

Eliminazione dei file intermedi nel bucket Cloud Storage

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

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

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

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

gsutil -m rm gs://BUCKET/FOLDER/work/**

Elimina il progetto

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

Per eliminare il progetto:

Avviso:l'eliminazione di un progetto include quanto segue conseguenze:

• Se hai utilizzato un progetto esistente, eliminerai anche tutto il lavoro effettuato nel progetto.
• Non puoi riutilizzare l'ID di un progetto eliminato. Se hai creato un ID personalizzato che hai intenzione di utilizzare in futuro, elimina le risorse all'interno del progetto. Questo passaggio garantisce che gli URL che utilizzano l'ID progetto, ad esempio come URL appspot.com, rimani disponibile.

Se stai esplorando più tutorial e guide di avvio rapido, puoi riutilizzare i progetti invece di eliminarli, in modo da non superare i limiti di quota.

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.
3. Nella finestra di dialogo, digita l'ID del progetto e fai clic su Chiudi per eliminare il progetto.

Passaggi successivi

• Questo tutorial mostra come eseguire un flusso di lavoro predefinito in un uso limitato ma non è destinato all'esecuzione in produzione. Per informazioni su come di eseguire l'elaborazione dei dati genomici in un ambiente di produzione su Google Cloud, consulta l'articolo sull'architettura di riferimento per l'elaborazione dei dati genomici.
• Il sito GATK del Broad Institute e i forum offrono altre informazioni di base, documentazione e supporto per gli strumenti GATK e WDL.