Orquestre tarefas executando pipelines do Nextflow no Batch

---

Este tutorial explica como executar um pipeline do Nextflow no Batch. Especificamente, este tutorial executa o pipeline de ciências da vida de exemplo rnaseq-nf do Nextflow, que quantifica as caraterísticas genómicas a partir de dados de leitura curta através do RNA-Seq.

Este tutorial destina-se a utilizadores do Batch que querem usar o Nextflow com o Batch.

O Nextflow é um software de código aberto para orquestrar fluxos de trabalho de bioinformática.

Nota: este tutorial fornece instruções para trabalhar com esta app: Nextflow version 23.04.1. As instruções podem não representar versões mais recentes da app. Para mais informações, consulte a documentação: Nextflow.

Objetivos

Ao concluir este tutorial, vai aprender a fazer o seguinte:

• Instale o Nextflow no Cloud Shell.
• Crie um contentor do Cloud Storage.
• Configure um pipeline do Nextflow.
• Execute um pipeline de exemplo com o Nextflow no Batch.
• Veja as saídas do pipeline.
• Para evitar incorrer em custos adicionais, faça uma das seguintes ações:
  • Elimine um projeto.
  • Elimine recursos individuais.

Custos

Neste documento, usa os seguintes componentes faturáveis do Google Cloud:

• Batch
• Cloud Storage

Para gerar uma estimativa de custos com base na sua utilização projetada, use a calculadora de preços.

Os novos Google Cloud utilizadores podem ser elegíveis para uma avaliação gratuita.

Normalmente, os recursos criados neste tutorial custam menos de 1 €, se concluir todos os passos, incluindo a limpeza, de forma atempada.

Antes de começar

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.

Install the Google Cloud CLI.

Se estiver a usar um fornecedor de identidade (IdP) externo, tem primeiro de iniciar sessão na CLI gcloud com a sua identidade federada.

Para inicializar a CLI gcloud, execute o seguinte comando:

gcloud init

Create or select a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

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.

Verify that billing is enabled for your Google Cloud project.

Enable the Batch, Cloud Storage, Compute Engine, and Logging APIs:

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

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

Install the Google Cloud CLI.

Se estiver a usar um fornecedor de identidade (IdP) externo, tem primeiro de iniciar sessão na CLI gcloud com a sua identidade federada.

Para inicializar a CLI gcloud, execute o seguinte comando:

gcloud init

Create or select a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

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.

Verify that billing is enabled for your Google Cloud project.

Enable the Batch, Cloud Storage, Compute Engine, and Logging APIs:

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

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

1. Certifique-se de que o seu projeto tem uma rede da nuvem virtual privada (VPC) com uma configuração de rede válida para este tutorial.

   Nota: não é necessária nenhuma ação para este passo, a menos que a sua organização desative a criação de redes default ativando a compute.skipDefaultNetworkCreation restrição de política ou o seu projeto tenha modificado a respetiva rede default.

   Este tutorial pressupõe que está a usar a rede default. Por predefinição, Google Cloud os recursos usam a rede default, que fornece o acesso à rede necessário para este tutorial.

   Objetivo: opcionalmente, se quiser que uma tarefa em lote para um pipeline do Nextflow use uma rede diferente, pode modificar o ficheiro nextflow.config neste tutorial para também definir a rede e a sub-rede da tarefa usando os campos google.batch.network e google.batch.subnetwork do Nextflow, respetivamente. No entanto, também tem de se certificar de que a rede e a sub-rede estão configuradas corretamente para a sua carga de trabalho. Para mais informações, consulte o artigo Vista geral da rede em lote.

2. Certifique-se de que o seu projeto tem, pelo menos, uma conta de serviço com as autorizações necessárias para executar a tarefa em lote neste tutorial.

   Por predefinição, as tarefas usam a conta de serviço predefinida do Compute Engine, à qual é concedida automaticamente a função do IAM Editor (roles/editor) e que já tem todas as autorizações necessárias para este tutorial.

   Nota: não é necessária nenhuma ação para este passo, a menos que a sua organização desative as autorizações automáticas para contas de serviço predefinidas ativando a restrição da política iam.automaticIamGrantsForDefaultServiceAccounts, o seu projeto tenha modificado a conta de serviço predefinida do Compute Engine ou queira usar uma conta de serviço diferente.

   Para garantir que a conta de serviço da tarefa tem as autorizações necessárias para permitir que o agente do serviço Batch crie e aceda a recursos para tarefas do Batch, peça ao seu administrador para conceder à conta de serviço da tarefa as seguintes funções do IAM:

   Importante: tem de conceder estas funções à conta de serviço da tarefa e não à sua conta de utilizador. Se não conceder as funções ao principal correto, podem ocorrer erros de autorização.
   • Batch Agent Reporter (roles/batch.agentReporter) no projeto
   • Administrador de armazenamento (roles/storage.admin) no projeto
   • (Recomendado) Permitir que os trabalhos gerem registos no Cloud Logging: Logs Writer (roles/logging.logWriter) no projeto

   Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

   O administrador também pode conceder à conta de serviço da tarefa as autorizações necessárias através de funções personalizadas ou outras funções predefinidas.

3. Certifique-se de que tem as autorizações necessárias para este tutorial.

   Nota: se criou o projeto que planeia usar para este tutorial, não é necessária nenhuma ação para este passo. Como criador do projeto, tem automaticamente o papel do IAM de proprietário (roles/owner), que já tem todas as autorizações necessárias para este tutorial.

   Para receber as autorizações de que precisa para concluir este tutorial, peça ao seu administrador que lhe conceda as seguintes funções do IAM:

   • Editor de tarefas em lote (roles/batch.jobsEditor) no projeto
   • Utilizador da conta de serviço (roles/iam.serviceAccountUser) na conta de serviço da tarefa
   • Administrador de objetos de armazenamento (roles/storage.objectAdmin) no projeto

4. Instale o Nextflow:

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

   O resultado deve ser semelhante ao seguinte:

   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
   

Crie um contentor do Cloud Storage

Para criar um contentor do Cloud Storage para armazenar ficheiros de trabalho e saída temporários do pipeline Nextflow, use a Google Cloud consola ou a linha de comandos.

Consola

Para criar um contentor do Cloud Storage através da Google Cloud consola, siga estes passos:

1. Na Google Cloud consola, aceda à página Recipientes.

   Aceda a Recipientes

2. Clique em Criar.

3. Na página Criar um contentor, introduza um nome globalmente exclusivo para o seu contentor.

4. Clique em Criar.

5. Na janela O acesso público vai ser impedido, clique em Confirmar.

gcloud

Para criar um contentor do Cloud Storage através da CLI do Google Cloud, use o comando gcloud storage buckets create.

gcloud storage buckets create gs://BUCKET_NAME

Substitua BUCKET_NAME por um nome globalmente exclusivo para o seu contentor.

Se o pedido for bem-sucedido, a saída deve ser semelhante à seguinte:

Creating gs://BUCKET_NAME/...
   ```

Configure o Nextflow

Para configurar o pipeline do Nextflow para ser executado no Batch, siga estes passos na linha de comandos:

1. Clone o repositório de tubagens de exemplo:

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

2. Aceda à pasta rnaseq-nf:

   cd rnaseq-nf
   

3. Abra o ficheiro nextflow.config:

   nano nextflow.config
   

   O ficheiro deve conter a seguinte secção gcb:

   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  = 'REGION'
   }
   

4. Na secção gcb, faça o seguinte:

   1. Substitua BUCKET_NAME pelo nome do contentor do Cloud Storage que criou nos passos anteriores.

   2. Substitua WORK_DIRECTORY pelo nome de uma nova pasta que o pipeline pode usar para armazenar registos e resultados.

      Por exemplo, introduza workDir.

   3. Substitua REGION pela região a usar.

      Por exemplo, introduza us-central1.

   4. Após o campo google.region, adicione os seguintes campos:

      1. Adicione o campo google.project:

         google.project = 'PROJECT_ID'
         

         Substitua PROJECT_ID pelo ID do projeto do projeto Google Cloud atual.

      2. Se não estiver a usar a conta de serviço predefinida do Compute Engine como conta de serviço da tarefa, adicione o campo google.batch.serviceAccountEmail:

         google.batch.serviceAccountEmail = 'SERVICE_ACCOUNT_EMAIL'
         

         Substitua SERVICE_ACCOUNT_EMAIL pelo endereço de email da conta de serviço da tarefa que preparou para este tutorial.

      Objetivo: para saber mais sobre todos os campos que pode especificar para configurar a tarefa em lote para um pipeline do Nextflow, consulte a documentação do Nextflow para o âmbito da configuração em lote.

5. Para guardar as edições, faça o seguinte:

   1. Prima Control+S.

   2. Introduza Y.

   3. Prima Enter.

Execute a pipeline

Execute o pipeline de exemplo do Nextflow através da linha de comandos:

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

O pipeline executa um pequeno conjunto de dados com as definições que forneceu nos passos anteriores. Esta operação pode demorar até 10 minutos a ser concluída.

Depois de a pipeline terminar a execução, o resultado deve ser semelhante ao seguinte:

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

Veja as saídas do pipeline

Após a conclusão da execução do pipeline, este armazena ficheiros de saída, registos, erros ou ficheiros temporários no ficheiro results/qc_report.html na pasta WORK_DIRECTORY do seu contentor do Cloud Storage.

Para verificar os ficheiros de saída do pipeline na pasta WORK_DIRECTORY do seu contentor do Cloud Storage, pode usar a consola Google Cloud ou a linha de comandos.

Consola

Para verificar os ficheiros de saída do pipeline através da Google Cloud consola, siga estes passos:

1. Na Google Cloud consola, aceda à página Recipientes.

   Aceda a Recipientes

2. Na coluna Nome, clique no nome do contentor que criou nos passos anteriores.

3. Na página Detalhes do contentor, abra a pasta WORK_DIRECTORY.

Existe uma pasta para cada tarefa separada que o fluxo de trabalho executa. Cada pasta contém os comandos executados, os ficheiros de saída e os ficheiros temporários criados pelo pipeline.

gcloud

Para verificar os ficheiros de saída do pipeline através da CLI gcloud, use o comando gcloud storage ls.

gcloud storage ls gs://BUCKET_NAME/WORK_DIRECTORY

Substitua o seguinte:

• BUCKET_NAME: o nome do contentor que criou nos passos anteriores.

• WORK_DIRECTORY: o diretório que especificou no ficheiro nextflow.config.

A saída apresenta uma pasta para cada tarefa separada que o pipeline executa. Cada pasta contém os comandos executados, os ficheiros de saída e os ficheiros temporários criados pelo pipeline.

Limpar

Para evitar incorrer em custos na sua conta do Google Cloud pelos recursos usados neste tutorial, elimine o projeto que contém os recursos ou mantenha o projeto e elimine os recursos individuais.

Elimine o projeto

A forma mais fácil de eliminar a faturação é eliminar o projeto atual.

Para eliminar o projeto atual, use a Google Cloud consola ou a CLI gcloud.

Consola

Atenção: a eliminação de um projeto tem os seguintes efeitos:

• Tudo no projeto é eliminado. Se usou um projeto existente para as tarefas neste documento, quando o elimina, também elimina qualquer outro trabalho que tenha feito no projeto.
• Os IDs dos projetos personalizados são perdidos. Quando criou este projeto, pode ter criado um ID do projeto personalizado que quer usar no futuro. Para preservar os URLs que usam o ID do projeto, como um URL appspot.com, elimine os recursos selecionados no projeto em vez de eliminar o projeto inteiro.

Se planeia explorar várias arquiteturas, tutoriais ou inícios rápidos, a reutilização de projetos pode ajudar a evitar exceder os limites de quota de projetos.

Delete a Google Cloud project:

gcloud projects delete PROJECT_ID

gcloud

Atenção: a eliminação de um projeto tem os seguintes efeitos:

• Tudo no projeto é eliminado. Se usou um projeto existente para as tarefas neste documento, quando o elimina, também elimina qualquer outro trabalho que tenha feito no projeto.
• Os IDs dos projetos personalizados são perdidos. Quando criou este projeto, pode ter criado um ID do projeto personalizado que quer usar no futuro. Para preservar os URLs que usam o ID do projeto, como um URL appspot.com, elimine os recursos selecionados no projeto em vez de eliminar o projeto inteiro.

Se planeia explorar várias arquiteturas, tutoriais ou inícios rápidos, a reutilização de projetos pode ajudar a evitar exceder os limites de quota de projetos.

Delete a Google Cloud project:

gcloud projects delete PROJECT_ID

Elimine recursos individuais

Se quiser continuar a usar o projeto atual, elimine os recursos individuais usados neste tutorial.

Elimine o contentor

Se já não precisar do contentor que usou neste tutorial, elimine-o.

Elimine os ficheiros de saída no contentor

Depois de a pipeline terminar a execução, cria e armazena ficheiros de saída na pasta WORK_DIRECTORY do seu contentor do Cloud Storage.

Para reduzir os custos do armazenamento na nuvem para a conta atual, pode eliminar a pasta que contém os ficheiros de saída do pipeline através da consola ou da linha de comandos.Google Cloud Google Cloud

Consola

Para eliminar a pasta WORK_DIRECTORY e todos os ficheiros de saída do seu contentor do Cloud Storage através da consolaGoogle Cloud , siga estes passos:

1. Na Google Cloud consola, aceda à página Recipientes.

   Aceda a Recipientes

2. Na coluna Nome, clique no nome do contentor que criou nos passos anteriores.

3. Na página Detalhes do contentor, selecione a linha que contém a pasta WORK_DIRECTORY e, de seguida, faça o seguinte:

   1. Clique em Eliminar.

   2. Para confirmar, introduza DELETE e, de seguida, clique em Eliminar.

gcloud

Para eliminar a pasta WORK_DIRECTORY e todos os ficheiros de saída do seu contentor do Cloud Storage através da CLI gcloud, use o comando gcloud storage rm com a flag --recursive.

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

Substitua o seguinte:

• BUCKET_NAME: o nome do contentor que especificou nos passos anteriores.

• WORK_DIRECTORY: o diretório para armazenar os ficheiros de saída do pipeline que especificou nos passos anteriores.

O que se segue?

• Para saber como implementar fluxos de trabalho do Nextflow, consulte o repositório do GitHub do Nextflow.

• Para saber mais sobre os processos, os scripts e as opções de configuração do Nextflow, consulte a documentação do Nextflow.