Cloud Life Sciences è ritirato e non sarà più disponibile su Google Cloud dopo l'8 luglio 2025. I casi d'uso di Cloud Life Sciences sono ora supportati da Batch. Per informazioni su come eseguire la migrazione del carico di lavoro, vedi Migrazione a un batch.

Esegui le best practice GATK

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

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

Obiettivi

Una volta completato il tutorial, saprai come:

Esegui una pipeline utilizzando le best practice GATK con i dati della build 38 del genoma di riferimento umano
Esegui una pipeline utilizzando le best practice GATK utilizzando 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 in base all'utilizzo previsto, utilizza il Calcolatore prezzi. I nuovi utenti di Google Cloud possono essere idonei a una prova senza costi aggiuntivi.

Prima di iniziare

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.

Nella pagina del selettore di progetti della console Google Cloud, seleziona o crea un progetto Google Cloud.

Vai al selettore progetti

Assicurati che la fatturazione sia attivata per il tuo progetto Google Cloud.

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

Abilita le API

Installa Google Cloud CLI.

Per initialize gcloud CLI, esegui questo comando:

gcloud init

Aggiorna e installa i componenti di gcloud:

gcloud components update
gcloud components install beta

Nella pagina del selettore di progetti della console Google Cloud, seleziona o crea un progetto Google Cloud.

Vai al selettore progetti

Assicurati che la fatturazione sia attivata per il tuo progetto Google Cloud.

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

Abilita le API

Installa Google Cloud CLI.

Per initialize gcloud CLI, esegui questo comando:

gcloud init

Aggiorna e installa i componenti di gcloud:

gcloud components update
gcloud components install beta

Installa Git per scaricare i file richiesti.
Scarica Git
Per impostazione predefinita, Compute Engine prevede la quota delle risorse per impedire l'utilizzo involontario. Aumentando le quote, puoi avviare più macchine virtuali contemporaneamente, aumentando la velocità effettiva e riducendo i tempi di esecuzione.
Per ottenere i migliori risultati in questo tutorial, devi richiedere una quota aggiuntiva superiore a quella predefinita del tuo progetto. I suggerimenti per gli aumenti delle quote sono riportati nel seguente elenco e le quote minime necessarie per eseguire il tutorial. Effettua 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 della richiesta di 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 su Google Cloud.

Crea un bucket Cloud Storage

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

gsutil mb gs://BUCKET

La pipeline genera risultati, log e file intermedi in questo bucket.

Scarica i file di esempio

Esegui questi comandi per scaricare il WDL e lo script 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 il genoma di riferimento
*.options.json: opzioni di runtime del flusso di lavoro

Il file di definizione della pipeline Cromwell utilizzato per eseguire le pipeline WDL è disponibile nel repository broadinstitute/wdl-runner/wdl_runner/.

Eseguire 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 rimanda alla cartella contenente i file di pipeline Broad:
```
export GATK_GOOGLE_DIR="${PWD}"/broad-prod-wgs-germline-snps-indels
```
Crea la variabile di ambiente GATK_OUTPUT_DIR che punta al bucket Cloud Storage e una cartella per il output del flusso di lavoro, i file work intermedi e logging:
```
export GATK_OUTPUT_DIR=gs://BUCKET/FOLDER
```
Cambia la directory nella 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/
```

Esegui la pipeline:

Scegli una delle seguenti opzioni a seconda che tu stia utilizzando 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 e SUBNETWORK per specificare il nome della rete VPC e della subnet:
```
export NETWORK=VPC_NETWORK
export SUBNETWORK=VPC_SUBNET
```
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 le zone all'interno della regione della tua subnet. Ad esempio, se utilizzi una subnet us-central1, il campo zones 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 usare il comando gcloud beta lifesciences describe per monitorare lo stato della pipeline eseguendo questo 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)'
```
Il comando operations describe restituisce done: true al termine della pipeline.

Puoi eseguire uno script incluso con wdl_runner per verificare ogni 300 secondi se il job è in esecuzione, è terminato o ha restituito un errore:
```
../monitoring_tools/monitor_wdl_pipeline.sh OPERATION_ID us-central1 300
```
Al termine della pipeline, esegui il comando seguente per elencare gli output nel bucket Cloud Storage:
```
gsutil ls gs://BUCKET/FOLDER/output/
```

Puoi visualizzare i file intermedi creati dalla pipeline e scegliere quali mantenere, oppure rimuoverli per ridurre i costi associati a Cloud Storage. Per rimuovere i file, vedi Eliminazione dei file intermedi nel bucket Cloud Storage.

Eseguire la pipeline Best practice per GATK sui 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 poter essere caricati in Cloud Storage. Puoi convertirli localmente o utilizzando l'API Pipelines per convertirli 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 di come copiare file in un bucket Cloud Storage, consulta la sezione Copiare i dati in Cloud Storage.

Lo strumento a riga di comando gsutil verifica automaticamente i checksum quindi, quando il trasferimento ha esito positivo, i dati sono compatibili per l'utilizzo con le best practice GATK.

Esegui la pipeline sui tuoi dati

Per eseguire le best practice GATK sui tuoi file BAM non allineati, crea una copia di PairedEndSingleSampleWf.hg38.inputs.json, quindi aggiorna i percorsi per indirizzare i tuoi file in un bucket Cloud Storage. Puoi quindi seguire i passaggi descritti in Eseguire la pipeline utilizzando i 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, sequenza esotica, riquadri target e dati somatici, devi utilizzare flussi di lavoro diversi. Per ulteriori informazioni, visita il forum di assistenza GATK e il repository GitHub di Broad Institute.

Risolvere i problemi

La pipeline è configurata per utilizzare le istanze di Compute Engine in aree geografiche e zone specifiche. Quando esegui l'interfaccia a riga di comando gcloud, utilizza automaticamente una regione e una zona predefinite in base alla località in cui è stato creato il progetto Google Cloud. Questo può causare 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 questo problema, rimuovi l'area geografica e la zona predefinite eseguendo questi 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 progetto Google Cloud, consulta Modificare la zona o la regione predefinita.
Se riscontri problemi durante l'esecuzione della pipeline, consulta la sezione Risoluzione dei problemi dell'API Cloud Life Sciences.
GATK ha rigorose aspettative sui formati di file di input. Per evitare problemi, puoi verificare che i file superino il metodo ValidateSamFile.
Se l'esecuzione GATK non va a buon fine, puoi controllare i log eseguendo il comando seguente:
```
gsutil ls gs://BUCKET/FOLDER/logging
```
In caso di errori di autorizzazione, verifica che il tuo account di servizio abbia accesso in lettura ai file di input e accesso in scrittura al percorso del bucket di output. Se stai scrivendo file di output in un bucket in un progetto Google Cloud non tuo, devi concedere all'account di servizio l'autorizzazione per accedere al bucket.

Eseguire 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 gli addebiti di Cloud Storage.

Per visualizzare la quantità di spazio utilizzata nella directory work, esegui il comando seguente. 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 il comando seguente:

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:

Nella console Google Cloud, vai alla pagina Progetti.
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

Questo tutorial mostra come eseguire un flusso di lavoro predefinito in un caso d'uso limitato, ma non è pensato per essere eseguito in produzione. Per informazioni su come eseguire l'elaborazione dei dati genomici in un ambiente di produzione su Google Cloud, consulta l'architettura di riferimento per l'elaborazione dei dati genomici.
Il sito GATK e i forum del Broad Institute forniscono ulteriori informazioni di base, documentazione e supporto per gli strumenti GATK e WDL.