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 delle best practice di GATK 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.
Obiettivi
Al termine di 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 di 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 basata sull'utilizzo previsto,
utilizza il Calcolatore prezzi.
Prima di iniziare
- 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.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Make sure that billing is enabled for your Google Cloud project.
-
Enable the Cloud Life Sciences, Compute Engine, and Cloud Storage APIs.
- Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
-
Update and install
gcloud
components:gcloud components update
gcloud components install beta -
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Make sure that billing is enabled for your Google Cloud project.
-
Enable the Cloud Life Sciences, Compute Engine, and Cloud Storage APIs.
- Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
-
Update and install
gcloud
components:gcloud components update
gcloud components install beta - Installa git per scaricare i file richiesti.
-
Per impostazione predefinita, Compute Engine prevede le quote delle risorse
per evitare utilizzi involontari. Aumentando le quote, puoi avviare
più macchine virtuali contemporaneamente, con conseguente aumento della velocità effettiva e
i tempi di risposta.
Per ottenere risultati ottimali in questo tutorial, devi richiedere una quota aggiuntiva superiore a quella predefinita del progetto. Nel seguente elenco sono riportati i consigli per gli aumenti di quota e le quote minime necessarie per eseguire il tutorial. Invia le richieste di quota nella regione
us-central1
:- CPU: 101 (minima 17)
- Disco permanente standard (GB): 10.500 (min 320)
- Indirizzi IP in uso: 51 (min 2)
Puoi lasciare vuoti gli altri campi di richiesta di quota per mantenere le quote attuali.
Crea un bucket Cloud Storage
Crea un bucket Cloud Storage utilizzando il comando gcloud storage buckets create
. A causa di un requisito nel motore Cromwell, non utilizzare il trattino basso
(_
) nel nome del bucket, altrimenti riscontrerai un errore.
gcloud storage buckets create 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 i seguenti comandi per scaricare lo script WDL e di supporto:
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 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 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:
Crea la variabile di ambiente
GATK_GOOGLE_DIR
che indirizzi alla cartella contenente i file della pipeline Broad:export GATK_GOOGLE_DIR="${PWD}"/broad-prod-wgs-germline-snps-indels
Crea la variabile di ambiente
GATK_OUTPUT_DIR
che punta a del bucket Cloud Storage e di una cartella peroutput
del flusso di lavoro.work
file intermedi elogging
:export GATK_OUTPUT_DIR=gs://BUCKET/FOLDER
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/
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
Crea le variabili di ambiente
NETWORK
eSUBNETWORK
per specificare il nome della rete e della subnet VPC:export NETWORK=VPC_NETWORK export SUBNETWORK=VPC_SUBNET
Modifica il file
PairedEndSingleSampleWf.options.json
che si trova nella directorybroad-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 subnetus-central1
, il campozones
sarà simile al seguente:"zones": "us-central1-a us-central1-b us-central1-c us-central1-f"
.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/
Il comando restituisce un ID operazione nel formato
Running [operations/OPERATION_ID]
. Puoi utilizzare logcloud 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)'
Il comando
operations describe
restituiscedone: true
al termine della pipeline.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
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 quelli da conservare oppure rimuoverli per ridurre i costi associati a Cloud Storage. Per rimuovere i file, consulta l'articolo 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 file di input
La pipeline può essere eseguita con file BAM non allineati archiviati in Cloud Storage. Se i file sono in un formato diverso, ad esempio BAM o FASTQ allineati, devi convertirli prima di poterli caricare su Cloud Storage. Puoi convertirli localmente oppure utilizzare l'API Pipelines per farlo nel cloud.
L'esempio seguente mostra come copiare un singolo file da un file system locale in un bucket Cloud Storage:
gcloud storage cp FILE gs://BUCKET/FOLDER
Per altri esempi su come copiare i file in un bucket Cloud Storage, consulta la sezione sulla copia dei dati in Cloud Storage.
L'interfaccia a riga di comando gcloud verifica automaticamente i checksum, pertanto, se il trasferimento va a buon fine, i dati sono compatibili per l'utilizzo con le Best Practice di GATK.
Esegui la pipeline sui dati
Per eseguire le best practice di GATK sui tuoi file BAM non allineati, crea una copia di
PairedEndSingleSampleWf.hg38.inputs.json
,
quindi aggiorna i percorsi in modo che rimandino ai tuoi file in un bucket Cloud Storage.
Poi puoi 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 genomi di riferimento, sequenziamento dell'esoma, panel mirati e dati somatici, devi utilizzare flussi di lavoro diversi. Per ulteriori informazioni, visita 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 l'interfaccia a riga di comando gcloud, viene utilizzata automaticamente una regione e una zona predefinite in base alla posizione 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 la sezione Risoluzione dei problemi relativi all'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 di GATK non va a buon fine, puoi controllare i log eseguendo il seguente comando:
gcloud storage ls gs://BUCKET/FOLDER/logging
Se riscontri errori di autorizzazione, verifica che il tuo account di servizio abbia accesso in lettura ai file di input e in scrittura al percorso del bucket di output. Se stai scrivendo file di output in un bucket di un progetto Google Cloud non di tua proprietà, 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, i file intermedi vengono archiviati 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 utilizzata 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 la
seguente comando:
gcloud storage 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:
- Nella console Google Cloud, vai alla pagina Progetti.
- Nell'elenco dei progetti, selezionare quello da eliminare e fai clic su Elimina progetto.
- Nella finestra di dialogo, digita l'ID del progetto e fai clic su Chiudi per eliminare il progetto.
Passaggi successivi
- Il sito GATK del Broad Institute e forum offrono informazioni di base, documentazione e supporto per gli strumenti GATK e WDL.