Esegui Nextflow

---

Questa pagina spiega come eseguire una pipeline Nextflow su Google Cloud.

La pipeline utilizzata in questo tutorial è una proof of concept di una pipeline RNA-Seq finalizzata a mostrare l'utilizzo di Nextflow su Google Cloud.

Nota: sei responsabile della conformità ai termini del contratto di licenza Nextflow e del contratto di licenza della pipeline RNAseq-NF.

Obiettivi

Al termine di questo tutorial, saprai come:

• Installa Nextflow in Cloud Shell.
• Configura una pipeline Nextflow.
• Esegui una pipeline utilizzando Nextflow su Google Cloud.

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 utenti di Google Cloud potrebbero essere idonei per 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.

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

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

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

   Enable the APIs

Crea un bucket Cloud Storage

Crea un bucket con un nome univoco seguendo le indicazioni riportate nelle linee guida per la denominazione dei bucket. Il bucket memorizza i file di lavoro e di output temporanei durante questo tutorial. Per motivi di compatibilità DNS, questo tutorial non funziona con i nomi dei bucket contenenti un underscore (_).

Console

1. Nella console Google Cloud, vai alla pagina Browser in Cloud Storage:

   Vai al browser

2. Fai clic su Crea bucket.

3. Nella pagina Crea un bucket, inserisci le informazioni del bucket.

4. Fai clic su Crea.

gcloud

1. Apri Cloud Shell:

   Vai a Cloud Shell

2. Utilizza il comando gcloud storage buckets create:

   gcloud storage buckets create gs://BUCKET_NAME
   

   Sostituisci BUCKET_NAME con il nome che vuoi assegnare al bucket, rispettando i requisiti di denominazione. Ad esempio: my-bucket.

   Se la richiesta riesce, il comando restituisce il seguente messaggio:

   Creating gs://BUCKET_NAME/...
   

Crea un account di servizio e aggiungi i ruoli

Completa i seguenti passaggi per creare un account di servizio e aggiungere i seguenti ruoli di Identity and Access Management:

• Cloud Life Sciences Workflows Runner
• Utente account di servizio
• Service Usage Consumer

• Storage Object Admin

Console

Crea un account di servizio utilizzando la console Google Cloud:

1. Nella console Google Cloud, vai alla pagina Account di servizio.

   Vai alla pagina Account di servizio

2. Fai clic su Crea account di servizio.

3. Nel campo Nome account di servizio, inserisci nextflow-service-account e fai clic su Crea.

4. Nella sezione Concedi a questo account di servizio l'accesso al progetto, aggiungi i seguenti ruoli dall'elenco a discesa Seleziona un ruolo:

   • Cloud Life Sciences Workflows Runner
   • Utente account di servizio
   • Service Usage Consumer
   • Storage Object Admin

5. Fai clic su Continua e poi su Fine.

6. Nella pagina Account di servizio, individua l'account di servizio che hai creato. Nella riga dell'account di servizio, fai clic sul pulsante Altro e poi su Gestisci chiavi.

7. Nella pagina Chiavi, fai clic su Aggiungi chiave e poi su Crea nuova chiave.

8. Seleziona JSON per il Tipo di chiave e fai clic su Crea.

   Un file JSON contenente la chiave viene scaricato sul computer.

gcloud

Completa i seguenti passaggi utilizzando Cloud Shell:

1. Apri Cloud Shell.

   Vai a Cloud Shell

2. Imposta le variabili da utilizzare per la creazione dell'account di servizio, sostituendo PROJECT_ID con l'ID del tuo progetto.

   export PROJECT=PROJECT_ID
   export SERVICE_ACCOUNT_NAME=nextflow-service-account
   export SERVICE_ACCOUNT_ADDRESS=${SERVICE_ACCOUNT_NAME}@${PROJECT}.iam.gserviceaccount.com

3. Crea il service account.

   gcloud iam service-accounts create ${SERVICE_ACCOUNT_NAME}

4. L'account di servizio ha bisogno dei seguenti ruoli IAM:

   • roles/lifesciences.workflowsRunner
   • roles/iam.serviceAccountUser
   • roles/serviceusage.serviceUsageConsumer
   • roles/storage.objectAdmin

   Concedi questi ruoli eseguendo i seguenti comandi in Cloud Shell:

   gcloud projects add-iam-policy-binding ${PROJECT} \
       --member serviceAccount:${SERVICE_ACCOUNT_ADDRESS} \
       --role roles/lifesciences.workflowsRunner
   
   gcloud projects add-iam-policy-binding ${PROJECT} \
       --member serviceAccount:${SERVICE_ACCOUNT_ADDRESS} \
       --role roles/iam.serviceAccountUser
   
   gcloud projects add-iam-policy-binding ${PROJECT} \
       --member serviceAccount:${SERVICE_ACCOUNT_ADDRESS} \
       --role roles/serviceusage.serviceUsageConsumer
   
   gcloud projects add-iam-policy-binding ${PROJECT} \
       --member serviceAccount:${SERVICE_ACCOUNT_ADDRESS} \
       --role roles/storage.objectAdmin

Fornisci le credenziali alla tua applicazione

Puoi fornire le credenziali di autenticazione al codice o ai comandi dell'applicazione impostando la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS sul percorso del file JSON contenente la chiave dell'account di servizio.

I seguenti passaggi mostrano come impostare la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS:

Console

1. Apri Cloud Shell.

   Vai a Cloud Shell

2. Nel menu Altro di Cloud Shell, seleziona Carica file e seleziona il file di chiave JSON che hai creato. Il file viene caricato nella home directory dell'istanza Cloud Shell.

3. Verifica che il file caricato sia nella directory corrente e conferma il nome del file eseguendo il seguente comando:

   ls

4. Imposta le credenziali, sostituendo KEY_FILENAME.json con il nome del file della chiave.

   export GOOGLE_APPLICATION_CREDENTIALS=${PWD}/KEY_FILENAME.json

gcloud

Completa i seguenti passaggi utilizzando Cloud Shell:

1. Apri Cloud Shell.

   Vai a Cloud Shell

2. Nel menu Altro di Cloud Shell, seleziona Carica file e seleziona il file di chiave JSON che hai creato. Il file viene caricato nella home directory dell'istanza Cloud Shell.

3. Verifica che il file caricato sia nella directory corrente e conferma il nome del file eseguendo il seguente comando:

   ls

4. Imposta il file della chiave privata sulla variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS:

   export SERVICE_ACCOUNT_KEY=${SERVICE_ACCOUNT_NAME}-private-key.json
   gcloud iam service-accounts keys create \
     --iam-account=${SERVICE_ACCOUNT_ADDRESS} \
     --key-file-type=json ${SERVICE_ACCOUNT_KEY}
   export SERVICE_ACCOUNT_KEY_FILE=${PWD}/${SERVICE_ACCOUNT_KEY}
   export GOOGLE_APPLICATION_CREDENTIALS=${PWD}/${SERVICE_ACCOUNT_KEY}

Installare e configurare Nextflow in Cloud Shell

Per evitare di dover installare software sulla tua macchina, continua a eseguire tutti i comandi del terminale in questo tutorial da Cloud Shell.

1. Se non è già aperta, apri Cloud Shell.

   Vai a Cloud Shell

2. Installa Nextflow eseguendo i seguenti comandi:

   export NXF_VER=21.10.0
   export NXF_MODE=google
   curl https://get.nextflow.io | bash

   Se l'installazione viene completata correttamente, viene visualizzato il seguente messaggio:

       N E X T F L O W
   version 21.10.0 build 5430
   created 01-11-2020 15:14 UTC (10:14 EDT)
   cite doi:10.1038/nbt.3820
   http://nextflow.io
   
   Nextflow installation completed. Please note:
   ‐ the executable file `nextflow` has been created in the folder: DIRECTORY
   ‐ you may complete the installation by moving it to a directory in your $PATH
   

3. Esegui il comando seguente per clonare il repository della pipeline di esempio. Il repository include la pipeline da eseguire e i dati di esempio utilizzati dalla pipeline.

   git clone https://github.com/nextflow-io/rnaseq-nf.git

4. Per configurare Nextflow:

   1. Passa alla cartella rnaseq-nf.

      cd rnaseq-nf
      git checkout v2.0

   2. Utilizzando un editor di testo a tua scelta, modifica il file nextflow.config e apporta i seguenti aggiornamenti alla sezione gls:

      • Aggiungi la riga google.project se non è presente.
      • Sostituisci PROJECT_ID con l'ID progetto.
      • Se vuoi, modifica il valore di google.location. Deve essere una delle località dell'API Cloud Life Sciences attualmente disponibili.
      • Se vuoi, modifica il valore di google.region che specifica la regione in cui vengono avviate le VM Compute Engine. Consulta le regioni e le zone Compute Engine disponibili.
      • Sostituisci BUCKET con il nome del bucket creato in precedenza.
      • Sostituisci WORK_DIR con il nome di una cartella da utilizzare per il logging e l'output. Utilizza un nuovo nome di directory che non esiste ancora nel bucket.
      Nota: la posizione della variabile workDir deve contenere almeno una sottodirectory. Non utilizzare solo il nome del bucket.

      gls {
         params.transcriptome = 'gs://rnaseq-nf/data/ggal/transcript.fa'
         params.reads = 'gs://rnaseq-nf/data/ggal/gut_{1,2}.fq'
         params.multiqc = 'gs://rnaseq-nf/multiqc'
         process.executor = 'google-lifesciences'
         process.container = 'nextflow/rnaseq-nf:latest'
         workDir = 'gs://BUCKET/WORK_DIR'
         google.location = 'europe-west2'
         google.region  = 'europe-west1'
         google.project = 'PROJECT_ID'
      }

   3. Torna alla cartella precedente

      cd ..

Esegui la pipeline con Nextflow

Esegui la pipeline con Nextflow. Dopo l'avvio, la pipeline continua a funzionare in background fino al completamento. Il completamento della pipeline potrebbe richiedere fino a 10 minuti.

./nextflow run rnaseq-nf/main.nf -profile gls

Al termine della pipeline viene visualizzato il seguente messaggio:

N E X T F L O W  ~  version 21.10.0
Launching `rnaseq-nf/main.nf` [suspicious_mestorf] - revision: ef908c0bfd
R N A S E Q - N F   P I P E L I N E
 ===================================
 transcriptome: gs://rnaseq-nf/data/ggal/transcript.fa
 reads        : gs://rnaseq-nf/data/ggal/gut_{1,2}.fq
 outdir       : results
executor >  google-lifesciences (4)
[db/2af640] process > RNASEQ:INDEX (transcript)     [100%] 1 of 1 ✔
[a6/927725] process > RNASEQ:FASTQC (FASTQC on gut) [100%] 1 of 1 ✔
[59/438177] process > RNASEQ:QUANT (gut)            [100%] 1 of 1 ✔
[9a/9743b9] process > MULTIQC                       [100%] 1 of 1 ✔
Done! Open the following report in your browser --> results/multiqc_report.html
Completed at: DATE TIME
Duration    : 10m
CPU hours   : 0.2
Succeeded   : 4

Visualizzazione dell'output della pipeline Nextflow

Al termine della pipeline, puoi controllare l'output e eventuali log, errori, comandi eseguiti e file temporanei.

La pipeline salva il file di output finale, results/qc_report.html, nel bucket Cloud Storage specificato nel file nextflow.config.

Per controllare i singoli file di output di ogni attività e i file intermedi:

Console

1. Nella console Cloud Storage, apri la pagina Browser di archiviazione:

   Vai al browser Cloud Storage

2. Vai a BUCKET e vai a WORK_DIR specificato nel file nextflow.config.

3. Esiste una cartella per ogni attività separata eseguita nella pipeline.

4. La cartella contiene i comandi eseguiti, i file di output e i file temporanei utilizzati durante il flusso di lavoro.

gcloud

1. Per visualizzare i file di output in Cloud Shell, apri prima Cloud Shell:

   Vai a Cloud Shell

2. Esegui il comando seguente per elencare le uscite nel bucket Cloud Storage. Aggiorna BUCKET e WORK_DIR con le variabili specificate nel file nextflow.config.

   gcloud storage ls gs://BUCKET/WORK_DIR

3. L'output mostra una cartella per ogni attività eseguita. Continua a elencare i contenuti delle sottodirectory successive per visualizzare tutti i file creati dalla pipeline. Aggiorna TASK_FOLDER una delle cartelle delle attività elencate nel comando precedente.

   gcloud storage ls gs://BUCKET/WORK_DIR/FOLDER/TASK_FOLDER

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.

Risoluzione dei problemi

• Se riscontri problemi durante l'esecuzione della pipeline, consulta la sezione Risoluzione dei problemi relativi all'API Cloud Life Sciences.

• Se la pipeline non va a buon fine, puoi controllare i log di ogni attività esaminando i file log in ciascuna delle cartelle di Cloud Storage, ad esempio.command.err, .command.log, .command.out e così via.

Esegui la pulizia

Per evitare che al tuo account Google Cloud vengano addebitati costi relativi alle risorse utilizzate in questo tutorial, elimina il progetto che contiene le risorse oppure mantieni il progetto ed elimina le singole risorse.

Al termine del tutorial, puoi eliminare le risorse che hai creato in modo che smettano di utilizzare la quota e di generare addebiti. Le sezioni seguenti descrivono come eliminare o disattivare queste risorse.

Eliminare i file intermedi nel bucket Cloud Storage

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

Per visualizzare lo spazio utilizzato nella directory, esegui il seguente comando:

gcloud storage du gs://BUCKET/WORK_DIR --readable-sizes --summarize

Per rimuovere i file da WORK_DIR:

Console

1. Nella console Cloud Storage, apri la pagina Browser di archiviazione:

   Vai al browser Cloud Storage

2. Vai a BUCKET e individua WORK_DIR specificato nel file nextflow.config.

3. Sfoglia le sottocartelle ed elimina eventuali file o directory indesiderati. Per eliminare tutti i file, elimina l'intero WORK_DIR.

gcloud

1. Apri Cloud Shell ed esegui quanto segue:

   Vai a Cloud Shell

2. Per rimuovere i file intermedi nella directory WORK_DIR, esegui il seguente comando:

   gcloud storage rm gs://BUCKET/WORK_DIR/**

Elimina il progetto

Il modo più semplice per eliminare la fatturazione è eliminare il progetto che hai creato per il tutorial.

Per eliminare il progetto:

Attenzione: l'eliminazione di un progetto ha i seguenti effetti:

• L'intero contenuto del progetto viene eliminato. Se hai utilizzato un progetto esistente per le attività descritte in questo documento, quando lo elimini elimini anche tutto il lavoro svolto nel progetto.
• Gli ID progetto personalizzati non sono più disponibili. Quando hai creato questo progetto, potresti aver creato un ID progetto personalizzato che vuoi utilizzare in futuro. Per conservare gli URL che utilizzano l'ID progetto, ad esempio un URL appspot.com, elimina le risorse selezionate all'interno del progetto anziché eliminare l'intero progetto.

Se intendi esplorare più architetture, tutorial o guide rapide, il riuso dei progetti può aiutarti a non superare i limiti di quota.

1. In the Google Cloud console, go to the Manage resources page.

   Go to Manage resources

2. In the project list, select the project that you want to delete, and then click Delete.
3. In the dialog, type the project ID, and then click Shut down to delete the project.

Passaggi successivi

Le seguenti pagine forniscono ulteriori informazioni di contesto, documentazione e assistenza per l'utilizzo di Nextflow:

• Sito Nextflow
• Repository GitHub di Nextflow
• Documentazione di Nextflow