Orchestra i job eseguendo pipeline Nextflow su Batch

---

Questo tutorial spiega come eseguire una pipeline Nextflow su Batch. In particolare, questo tutorial esegue una pipeline di scienze biologiche di esempio che quantifica le caratteristiche genomiche da brevi dati letti utilizzando RNA-Seq.

Questo tutorial è destinato agli utenti di Batch che vogliono utilizzare Nextflow con Batch.

Nextflow è un software open source per l'orchestrazione di flussi di lavoro bioinformatici.

Nota: questo tutorial fornisce istruzioni per lavorare con questa app: Nextflow version 23.04.1. Le istruzioni potrebbero non rappresentare versioni più recenti dell'app. Per saperne di più, consulta la documentazione: Nextflow.

Obiettivi

In questo tutorial imparerai a:

• Installa Nextflow in Cloud Shell.
• Creare un bucket Cloud Storage.
• Configurare una pipeline Nextflow.
• Eseguire una pipeline di esempio utilizzando Nextflow su Batch.
• Visualizza gli output della pipeline.
• Esegui la pulizia per evitare addebiti aggiuntivi effettuando una delle seguenti operazioni:
  • Eliminare un progetto.
  • Eliminare le singole risorse.

Costi

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

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

Le risorse create in questo tutorial in genere costano meno di un dollaro, supponendo che tu completi tutti i passaggi, inclusa la pulizia, in modo tempestivo.

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. Installa Google Cloud CLI.

3. Per initialize gcloud CLI, esegui questo comando:

   gcloud init

4. Create or select 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.

   • Create a Google Cloud project:

     gcloud projects create PROJECT_ID

     Replace PROJECT_ID with a name for the Google Cloud project you are creating.

   • Select the Google Cloud project that you created:

     gcloud config set project PROJECT_ID

     Replace PROJECT_ID with your Google Cloud project name.

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

6. Abilita le API Batch, Cloud Storage, Compute Engine, and Logging.

   gcloud services enable batch.googleapis.com compute.googleapis.com logging.googleapis.com storage.googleapis.com

7. Installa Google Cloud CLI.

8. Per initialize gcloud CLI, esegui questo comando:

   gcloud init

9. Create or select 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.

   • Create a Google Cloud project:

     gcloud projects create PROJECT_ID

     Replace PROJECT_ID with a name for the Google Cloud project you are creating.

   • Select the Google Cloud project that you created:

     gcloud config set project PROJECT_ID

     Replace PROJECT_ID with your Google Cloud project name.

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

11. Abilita le API Batch, Cloud Storage, Compute Engine, and Logging.

    gcloud services enable batch.googleapis.com compute.googleapis.com logging.googleapis.com storage.googleapis.com

12. Assicurati che il progetto abbia almeno un account di servizio con le autorizzazioni necessarie per questo tutorial.

    Nota: se utilizzi un nuovo progetto, questo passaggio non è obbligatorio a meno che la tua organizzazione non impedisca la concessione automatica di ruoli per gli account di servizio predefiniti. Per impostazione predefinita, all'account di servizio predefinito di Compute Engine viene concesso automaticamente il ruolo IAM Editor (roles/editor), che dispone già di tutte le autorizzazioni necessarie per questo tutorial.

    Ogni job richiede un account di servizio che consente all'agente di servizio Batch di creare e accedere alle risorse necessarie per eseguire il job. Per questo tutorial, l'account di servizio del job è l'account di servizio predefinito di Compute Engine.

    Per assicurarti che l'account di servizio predefinito di Compute Engine disponga delle autorizzazioni necessarie per consentire all'agente di servizio Batch di creare e accedere alle risorse per i job batch, chiedi all'amministratore di concedere all'account di servizio predefinito Compute Engine i seguenti ruoli IAM:

    • Reporter agente batch (roles/batch.agentReporter) nel progetto
    • Amministratore archiviazione (roles/storage.admin) del progetto
    • (Consigliato) Consenti ai job di generare log in Cloud Logging: Writer log (roles/logging.logWriter) sul progetto

    Per saperne di più sulla concessione dei ruoli, consulta Gestire l'accesso.

    L'amministratore potrebbe anche essere in grado di concedere all'account di servizio predefinito di Compute Engine le autorizzazioni richieste tramite ruoli personalizzati o altri ruoli predefiniti.

13. Assicurati di disporre delle autorizzazioni necessarie per questo tutorial.

    Nota: se hai creato questo progetto, questo passaggio non è obbligatorio. In qualità di creatore del progetto, ti viene concesso automaticamente il ruolo IAM Proprietario (roles/owner), che dispone già di tutte le autorizzazioni necessarie per questo tutorial.

    Per ottenere le autorizzazioni necessarie per completare questo tutorial, chiedi all'amministratore di concederti i ruoli IAM seguenti:

    • Editor job batch (roles/batch.jobsEditor) nel progetto
    • Utente account di servizio (roles/iam.serviceAccountUser) sull'account di servizio del job, che per questo tutorial è l'account di servizio predefinito di Compute Engine
    • Amministratore oggetti Storage (roles/storage.objectAdmin) nel progetto

14. Installa Nextflow:

    curl -s -L https://github.com/nextflow-io/nextflow/releases/download/v23.04.1/nextflow | bash
    

    L'output dovrebbe essere simile al seguente:

    N E X T F L O W
    version 23.04.1 build 5866
    created 15-04-2023 06:51 UTC
    cite doi:10.1038/nbt.3820
    http://nextflow.io
    
    Nextflow installation completed. Please note:
    - the executable file `nextflow` has been created in the folder: ...
    - you may complete the installation by moving it to a directory in your $PATH
    

Crea un bucket Cloud Storage

Per creare un bucket Cloud Storage per archiviare file temporanei di lavoro e di output della pipeline Nextflow, utilizza la console Google Cloud o la riga di comando.

Console

Per creare un bucket Cloud Storage utilizzando la console Google Cloud, segui questi passaggi:

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

   Vai a Bucket

2. Fai clic su Crea.

3. Nella pagina Crea un bucket, inserisci un nome univoco a livello globale per il bucket.

4. Fai clic su Crea.

5. Nella finestra L'accesso pubblico verrà vietato, fai clic su Conferma.

Riga di comando

gcloud

Per creare un bucket Cloud Storage utilizzando Google Cloud CLI, utilizza il comando gcloud storage buckets create.

gcloud storage buckets create gs://BUCKET_NAME

Sostituisci BUCKET_NAME con un nome univoco a livello globale per il bucket.

Se la richiesta ha esito positivo, l'output dovrebbe essere simile al seguente:

Creating gs://BUCKET_NAME/...

gsutil

Per creare un bucket Cloud Storage utilizzando lo strumento gsutil, utilizza il comando gsutil mb.

gsutil mb gs://BUCKET_NAME

Sostituisci BUCKET_NAME con un nome univoco a livello globale per il bucket.

Se la richiesta ha esito positivo, l'output dovrebbe essere simile al seguente:

Creating gs://BUCKET_NAME/...

Configura Nextflow

Per configurare la pipeline Nextflow in modo che venga eseguita su Batch, segui questi passaggi nella riga di comando:

1. Clona il repository della pipeline di esempio:

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

2. Vai alla cartella rnaseq-nf:

   cd rnaseq-nf
   

3. Apri il file nextflow.config:

   nano nextflow.config
   

   Il file deve contenere la seguente sezione:

   gcb {
     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-batch'
     process.container = 'quay.io/nextflow/rnaseq-nf:v1.1'
     workDir = 'gs://BUCKET_NAME/WORK_DIRECTORY'
     google.region  = 'us-central1'
   }
   ...
   

4. Nella sezione gcb, procedi nel seguente modo:

   1. Sostituisci BUCKET_NAME con il nome del bucket Cloud Storage creato nei passaggi precedenti.

   2. Sostituisci WORK_DIRECTORY con il nome di una nuova cartella che la pipeline può utilizzare per archiviare log e output.

      Ad esempio, inserisci workDir.

   3. Dopo il campo google.region, aggiungi la riga google.project = 'PROJECT_ID', dove PROJECT_ID è l'ID del progetto Google Cloud attuale.

5. Per salvare le modifiche:

   1. Premi Control+S.

   2. Inserisci Y.

   3. Premi Enter.

esegui la pipeline.

Esegui la pipeline Nextflow di esempio utilizzando la riga di comando:

../nextflow run nextflow-io/rnaseq-nf -profile gcb

La pipeline esegue un piccolo set di dati utilizzando le impostazioni che hai fornito nei passaggi precedenti. Questa operazione potrebbe richiedere fino a 10 minuti.

Al termine della pipeline, l'output dovrebbe essere simile al seguente:

N E X T F L O W  ~  version 23.04.1
Launching `https://github.com/nextflow-io/rnaseq-nf` [crazy_curry] DSL2 - revision: 88b8ef803a [master]
 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

Uploading local `bin` scripts folder to gs://example-bucket/workdir/tmp/53/2847f2b832456a88a8e4cd44eec00a/bin
executor >  google-batch (4)
[67/71b856] process > RNASEQ:INDEX (transcript)     [100%] 1 of 1 ✔
[0c/2c79c6] process > RNASEQ:FASTQC (FASTQC on gut) [100%] 1 of 1 ✔
[a9/571723] process > RNASEQ:QUANT (gut)            [100%] 1 of 1 ✔
[9a/1f0dd4] process > MULTIQC                       [100%] 1 of 1 ✔

Done! Open the following report in your browser --> results/multiqc_report.html

Completed at: 20-Apr-2023 15:44:55
Duration    : 10m 13s
CPU hours   : (a few seconds)
Succeeded   : 4

Visualizza output della pipeline

Al termine della pipeline, i file di output, i log, gli errori o i file temporanei vengono archiviati nel file results/qc_report.html all'interno della cartella WORK_DIRECTORY del bucket Cloud Storage.

Per verificare i file di output della pipeline nella cartella WORK_DIRECTORY del bucket Cloud Storage, puoi utilizzare la console Google Cloud o la riga di comando.

Console

Per controllare i file di output della pipeline utilizzando la console Google Cloud, segui questi passaggi:

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

   Vai a Bucket

2. Nella colonna Nome, fai clic sul nome del bucket creato nei passaggi precedenti.

3. Nella pagina Dettagli bucket, apri la cartella WORK_DIRECTORY.

È presente una cartella per ogni attività eseguita dal flusso di lavoro. Ogni cartella contiene i comandi che sono stati eseguiti, i file di output e i file temporanei creati dalla pipeline.

Riga di comando

gcloud

Per controllare i file di output della pipeline utilizzando gcloud CLI, utilizza il comando gcloud storage ls.

gcloud storage ls gs://BUCKET_NAME/WORK_DIRECTORY

Sostituisci quanto segue:

• BUCKET_NAME: il nome del bucket che hai creato nei passaggi precedenti.

• WORK_DIRECTORY: la directory specificata nel file nextflow.config.

L'output elenca una cartella per ogni attività separata eseguita dalla pipeline. Ogni cartella contiene i comandi eseguiti, i file di output e i file temporanei creati dalla pipeline.

gsutil

Per controllare i file di output della pipeline utilizzando lo strumento gsutil, utilizza il comando gsutil ls.

gsutil ls gs://BUCKET_NAME/WORK_DIRECTORY

Sostituisci quanto segue:

• BUCKET_NAME: il nome del bucket che hai creato nei passaggi precedenti.

• WORK_DIRECTORY: la directory specificata nel file nextflow.config.

L'output elenca una cartella per ogni attività separata eseguita dalla pipeline. Ogni cartella contiene i comandi eseguiti, i file di output e i file temporanei creati dalla pipeline.

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.

Elimina il progetto

Il modo più semplice per eliminare la fatturazione è eliminare il progetto corrente.

Per eliminare il progetto attuale, utilizza la console Google Cloud o gcloud CLI.

Console

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à in questo documento, quando lo elimini elimini anche qualsiasi altro 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, puoi riutilizzare i progetti ed evitare così di superare i limiti di quota.

1. Nella console Google Cloud, vai alla pagina Gestisci risorse.

   Vai a Gestisci risorse

2. Nell'elenco dei progetti, seleziona il progetto che vuoi eliminare, quindi fai clic su Elimina.
3. Nella finestra di dialogo, digita l'ID del progetto e fai clic su Chiudi per eliminare il progetto.

gcloud

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à in questo documento, quando lo elimini elimini anche qualsiasi altro 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, puoi riutilizzare i progetti ed evitare così di superare i limiti di quota.

Elimina un progetto Google Cloud:

gcloud projects delete PROJECT_ID

Elimina singole risorse

Se vuoi continuare a utilizzare il progetto attuale, elimina le singole risorse utilizzate in questo tutorial.

Elimina il bucket

Se non hai più bisogno del bucket che hai utilizzato in questo tutorial, elimina il bucket.

Elimina i file di output nel bucket

Al termine dell'esecuzione, la pipeline crea e archivia i file di output nella cartella WORK_DIRECTORY del tuo bucket Cloud Storage.

Per ridurre gli addebiti di Cloud Storage all'account Google Cloud attuale, puoi eliminare la cartella contenente i file di output della pipeline utilizzando la console Google Cloud o la riga di comando.

Console

Per eliminare la cartella WORK_DIRECTORY e tutti i file di output dal bucket Cloud Storage utilizzando la console Google Cloud, segui questi passaggi:

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

   Vai a Bucket

2. Nella colonna Nome, fai clic sul nome del bucket creato nei passaggi precedenti.

3. Nella pagina Dettagli bucket, seleziona la riga contenente la cartella WORK_DIRECTORY, quindi segui questi passaggi:

   1. Fai clic su Elimina.

   2. Per confermare, inserisci DELETE e fai clic su Elimina.

Riga di comando

gcloud

Per eliminare la cartella WORK_DIRECTORY e tutti i file di output dal bucket Cloud Storage utilizzando gcloud CLI, utilizza il comando gcloud storage rm con il flag --recursive.

gcloud storage rm gs://BUCKET_NAME/WORK_DIRECTORY \
    --recursive

Sostituisci quanto segue:

• BUCKET_NAME: il nome del bucket specificato nei passaggi precedenti.

• WORK_DIRECTORY: la directory in cui archiviare i file di output della pipeline specificati nei passaggi precedenti.

gsutil

Per eliminare la cartella WORK_DIRECTORY e tutti i file di output dal bucket Cloud Storage utilizzando lo strumento gsutil, utilizza il comando gsutil rm con le opzioni -m e -r.

gsutil -m rm -r gs://BUCKET_NAME/WORK_DIRECTORY

Sostituisci quanto segue:

• BUCKET_NAME: il nome del bucket specificato nei passaggi precedenti.

• WORK_DIRECTORY: la directory in cui archiviare i file di output della pipeline specificati nei passaggi precedenti.

Passaggi successivi

• Per scoprire di più sul deployment dei flussi di lavoro Nextflow, consulta Repository GitHub di Nextflow.

• Per scoprire di più su processi, script e opzioni di configurazione di Nextflow, consulta la documentazione di Nextflow.