Orquestre jobs executando pipelines do Nextflow em lote

Neste tutorial, explicamos como executar um pipeline do Nextflow no Batch. Especificamente, este tutorial executa o pipeline de ciências da vida rnaseq-nf de amostra do Nextflow, que quantifica recursos genômicos de dados de leitura curta usando RNA-Seq.

Este tutorial é destinado a usuários 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.

Observação: neste tutorial, fornecemos instruções para trabalhar com este app: Nextflow versão 23.04.1. As instruções podem não representar versões mais recentes do app. Para mais informações, consulte a documentação: Nextflow.

Objetivos

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

• Instale o Nexflow no Cloud Shell.
• Criar um bucket do Cloud Storage.
• configurar um pipeline do Nextflow;
• Executar um pipeline de exemplo usando o Nextflow no Batch.
• Confira as saídas do pipeline.
• Libere espaço para evitar cobranças extras seguindo uma destas opções:
  • Excluir um projeto.
  • Exclua recursos individuais.

Custos

Neste documento, você vai usar os seguintes componentes faturáveis do Google Cloud:

• Batch
• Cloud Storage

Para gerar uma estimativa de custo baseada na projeção de uso deste tutorial, use a calculadora de preços.

Novos usuários do Google Cloud podem estar qualificados para um teste sem custo financeiro.

Os recursos criados neste tutorial normalmente custam menos de um dólar, supondo que você conclua todas as etapas, incluindo a limpeza, em tempo hábil.

Antes de começar

Faça login na sua conta do Google Cloud . Se você começou a usar o Google Cloud, crie uma conta para avaliar o desempenho de nossos produtos em situações reais. Clientes novos também recebem US$ 300 em créditos para executar, testar e implantar cargas de trabalho.

Instale a CLI do Google Cloud.

Ao usar um provedor de identidade (IdP) externo, primeiro faça login na gcloud CLI com sua identidade federada.

Para inicializar a gcloud CLI, execute o seguinte comando:

gcloud init

Crie ou selecione um Google Cloud projeto.

Funções necessárias para selecionar ou criar um projeto

• Selecionar um projeto: não é necessário um papel específico do IAM para selecionar um projeto. Você pode escolher qualquer projeto em que tenha recebido um papel.
• Criar um projeto: para criar um projeto, é necessário ter o papel de Criador de projetos (roles/resourcemanager.projectCreator), que contém a permissão resourcemanager.projects.create. Saiba como conceder papéis.

Observação: se você não pretende manter os recursos criados neste procedimento, crie um projeto novo em vez de selecionar um que já existe. Depois de concluir essas etapas, é possível excluir o projeto. Para fazer isso, basta remover todos os recursos associados a ele.

• Crie um projeto do Google Cloud :

  gcloud projects create PROJECT_ID

  Substitua PROJECT_ID por um nome para o projeto Google Cloud que você está criando.

• Selecione o projeto Google Cloud que você criou:

  gcloud config set project PROJECT_ID

  Substitua PROJECT_ID pelo nome do projeto do Google Cloud .

Verifique se o faturamento está ativado para o projeto do Google Cloud .

Ative as APIs Batch, Cloud Storage, Compute Engine e Logging:

Funções necessárias para ativar APIs

Para ativar as APIs, é necessário ter o papel do IAM de administrador do Service Usage (roles/serviceusage.serviceUsageAdmin), que contém a permissão serviceusage.services.enable. Saiba como conceder papéis.

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

Instale a CLI do Google Cloud.

Ao usar um provedor de identidade (IdP) externo, primeiro faça login na gcloud CLI com sua identidade federada.

Para inicializar a gcloud CLI, execute o seguinte comando:

gcloud init

Crie ou selecione um Google Cloud projeto.

Funções necessárias para selecionar ou criar um projeto

• Selecionar um projeto: não é necessário um papel específico do IAM para selecionar um projeto. Você pode escolher qualquer projeto em que tenha recebido um papel.
• Criar um projeto: para criar um projeto, é necessário ter o papel de Criador de projetos (roles/resourcemanager.projectCreator), que contém a permissão resourcemanager.projects.create. Saiba como conceder papéis.

Observação: se você não pretende manter os recursos criados neste procedimento, crie um projeto novo em vez de selecionar um que já existe. Depois de concluir essas etapas, é possível excluir o projeto. Para fazer isso, basta remover todos os recursos associados a ele.

• Crie um projeto do Google Cloud :

  gcloud projects create PROJECT_ID

  Substitua PROJECT_ID por um nome para o projeto Google Cloud que você está criando.

• Selecione o projeto Google Cloud que você criou:

  gcloud config set project PROJECT_ID

  Substitua PROJECT_ID pelo nome do projeto do Google Cloud .

Verifique se o faturamento está ativado para o projeto do Google Cloud .

Ative as APIs Batch, Cloud Storage, Compute Engine e Logging:

Funções necessárias para ativar APIs

Para ativar as APIs, é necessário ter o papel do IAM de administrador do Service Usage (roles/serviceusage.serviceUsageAdmin), que contém a permissão serviceusage.services.enable. Saiba como conceder papéis.

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

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

   Observação:nenhuma ação é necessária nesta etapa, a menos que sua organização desative a criação de rede default ativando a restrição de política compute.skipDefaultNetworkCreation ou que o projeto tenha modificado a rede default.

   Neste tutorial, presumimos que você esteja usando a rede default. Por padrão,os recursos do Google Cloud usam a rede default, que fornece o acesso à rede necessário para este tutorial.

   Objetivo:opcionalmente, se você quiser que um job em lote para um pipeline do Nextflow use uma rede diferente, modifique o arquivo nextflow.config neste tutorial para definir também a rede e a sub-rede do job usando os campos google.batch.network e google.batch.subnetwork do Nextflow, respectivamente. No entanto, também é preciso garantir que a rede e a sub-rede estejam configuradas corretamente para sua carga de trabalho. Para mais informações, consulte Visão geral da rede em lote.

2. Verifique se o projeto tem pelo menos uma conta de serviço com as permissões necessárias para executar o job do Batch neste tutorial.

   Por padrão, os jobs usam a conta de serviço padrão do Compute Engine, que recebe automaticamente o papel de editor (roles/editor) do IAM e já tem todas as permissões necessárias para este tutorial.

   Observação:nenhuma ação é necessária nesta etapa, a menos que sua organização desative as permissões automáticas para contas de serviço padrão ao ativar a restrição de política iam.automaticIamGrantsForDefaultServiceAccounts, seu projeto tenha modificado a conta de serviço padrão do Compute Engine ou você queira usar uma conta de serviço diferente.

   Para garantir que a conta de serviço do job tenha as permissões necessárias para permitir que o agente de serviço do Batch crie e acesse recursos para jobs em lote, peça ao administrador para conceder os seguintes papéis do IAM à conta de serviço do job:

   Importante:conceda esses papéis à conta de serviço do job, não à sua conta de usuário. Se o papel não for concedido ao principal correto, poderão ocorrer erros de permissão.
   • Relator do agente em lote (roles/batch.agentReporter) no projeto
   • Administrador do Storage (roles/storage.admin) no projeto
   • (Recomendado) Permita que os jobs gerem registros no Cloud Logging: Gravador de registros (roles/logging.logWriter) no projeto

   Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

   O administrador também pode conceder à conta de serviço do job as permissões necessárias por meio de papéis personalizados ou outros papéis predefinidos.

3. Verifique se você tem as permissões necessárias para este tutorial.

   Observação:se você criou o projeto que pretende usar neste tutorial, não é necessário fazer nada nesta etapa. Como criador do projeto, você recebe automaticamente o papel de Proprietário (roles/owner) do IAM, que já tem todas as permissões necessárias para este tutorial.

   Para conseguir as permissões necessárias a fim de concluir este tutorial, peça ao administrador para conceder a você os seguintes papéis do IAM:

   • Editor de jobs em lote (roles/batch.jobsEditor) no projeto
   • Usuário da conta de serviço (roles/iam.serviceAccountUser) na conta de serviço do job
   • Administrador de objetos do Storage (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
   

   A saída será semelhante a esta:

   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
   

Criar um bucket do Cloud Storage

Para criar um bucket do Cloud Storage e armazenar arquivos de trabalho temporários e de saída do pipeline do Nextflow, use o console Google Cloud ou a linha de comando.

Console

Para criar um bucket do Cloud Storage usando o console Google Cloud , siga estas etapas:

1. No console Google Cloud , acesse a página Buckets.

   Acessar buckets

2. Clique em Criar.

3. Na página Criar um bucket, insira um nome globalmente exclusivo para o bucket.

4. Clique em Criar.

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

gcloud

Para criar um bucket do Cloud Storage usando a Google Cloud CLI, use o comando gcloud storage buckets create.

gcloud storage buckets create gs://BUCKET_NAME

Substitua BUCKET_NAME por um nome globalmente exclusivo para o bucket.

Se a solicitação for bem-sucedida, a saída será semelhante a esta:

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

Configurar o Nextflow

Para configurar o pipeline do Nextflow para ser executado no Batch, siga estas etapas na linha de comando:

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

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

2. Acesse a pasta rnaseq-nf:

   cd rnaseq-nf
   

3. Abra o arquivo nextflow.config.

   nano nextflow.config
   

   O arquivo precisa conter a seguinte seção google-batch:

   'google-batch' {
       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 = 'docker.io/nextflow/rnaseq-nf:v1.3.1'
       /*
        * replace with your own bucket!
        */
       workDir = 'gs://BUCKET_NAME/WORK_DIRECTORY'
       google.region  = 'REGION'
   }
   

4. Na seção google-batch, faça o seguinte:

   1. Substitua BUCKET_NAME pelo nome do bucket do Cloud Storage criado nas etapas anteriores.

   2. Substitua WORK_DIRECTORY pelo nome de uma nova pasta que o pipeline pode usar para armazenar registros e saídas.

      Por exemplo, insira workDir.

   3. Substitua REGION pela região a ser usada.

      Por exemplo, insira us-central1.

   4. Depois do campo google.region, adicione os seguintes campos:

      1. Adicione o campo google.project:

         google.project = 'PROJECT_ID'
         

         Substitua PROJECT_ID pelo ID do projeto atual Google Cloud .

      2. Se você não estiver usando a conta de serviço padrão do Compute Engine como a conta de serviço do job, adicione o campo google.batch.serviceAccountEmail:

         google.batch.serviceAccountEmail = 'SERVICE_ACCOUNT_EMAIL'
         

         Substitua SERVICE_ACCOUNT_EMAIL pelo endereço de e-mail da conta de serviço do job que você preparou para este tutorial.

      Objetivo: para saber mais sobre todos os campos que podem ser especificados para configurar o job em lote para um pipeline do Nextflow, consulte a documentação do Nextflow sobre o escopo da configuração do Batch.

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

   1. Pressione Control+S.

   2. Digite Y.

   3. Pressione Enter.

Executar o pipeline

Execute o pipeline de exemplo do Nextflow usando a linha de comando:

../nextflow run nextflow-io/rnaseq-nf -profile google-batch

O pipeline executa um pequeno conjunto de dados usando as configurações fornecidas nas etapas anteriores. Essa operação pode levar até 10 minutos para ser concluída.

Depois que o pipeline terminar de ser executado, a saída será semelhante a esta:

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

Ver saídas do pipeline

Depois que o pipeline termina de ser executado, ele armazena arquivos de saída, registros, erros ou arquivos temporários no arquivo results/qc_report.html dentro da pasta WORK_DIRECTORY do bucket do Cloud Storage.

Para verificar os arquivos de saída do pipeline na pasta WORK_DIRECTORY do bucket do Cloud Storage, use o console Google Cloud ou a linha de comando.

Console

Para verificar os arquivos de saída do pipeline usando o console do Google Cloud , siga estas etapas:

1. No console Google Cloud , acesse a página Buckets.

   Acessar buckets

2. Na coluna Nome, clique no nome do bucket criado nas etapas anteriores.

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

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

gcloud

Para verificar os arquivos de saída do pipeline usando a CLI gcloud, use o comando gcloud storage ls.

gcloud storage ls gs://BUCKET_NAME/WORK_DIRECTORY

Substitua:

• BUCKET_NAME: o nome do bucket que você criou nas etapas anteriores.

• WORK_DIRECTORY: o diretório especificado no arquivo nextflow.config.

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

Limpar

Para evitar cobranças na sua conta do Google Cloud pelos recursos usados no tutorial, exclua o projeto que os contém ou mantenha o projeto e exclua os recursos individuais.

Excluir o projeto

A maneira mais fácil de evitar o faturamento é excluir o projeto atual.

Para excluir o projeto atual, use o Google Cloud console ou a CLI gcloud.

Console

Cuidado: excluir um projeto tem os seguintes efeitos:

• Tudo no projeto é excluído. Se você tiver usado um projeto atual para as tarefas neste documento, a exclusão dele incluirá a exclusão de quaisquer outros trabalhos feitos nele.
• Os IDs do projeto personalizados são perdidos. Ao criar o projeto, você pode ter criado um ID do projeto personalizado para ser usado no futuro. Para preservar os URLs que usam o ID do projeto, como um URL appspot.com, exclua recursos específicos do projeto, em vez de excluir o projeto inteiro.

Se você planeja explorar várias arquiteturas, tutoriais e guias de início rápido, a reutilização de projetos pode evitar que você exceda limites da cota.

1. No console Google Cloud , acesse a página Gerenciar recursos.

   Acessar "Gerenciar recursos"

2. Na lista de projetos, selecione o projeto que você quer excluir e clique em Excluir .
3. Na caixa de diálogo, digite o ID do projeto e clique em Encerrar para excluí-lo.

gcloud

Cuidado: excluir um projeto tem os seguintes efeitos:

• Tudo no projeto é excluído. Se você tiver usado um projeto atual para as tarefas neste documento, a exclusão dele incluirá a exclusão de quaisquer outros trabalhos feitos nele.
• Os IDs do projeto personalizados são perdidos. Ao criar o projeto, você pode ter criado um ID do projeto personalizado para ser usado no futuro. Para preservar os URLs que usam o ID do projeto, como um URL appspot.com, exclua recursos específicos do projeto, em vez de excluir o projeto inteiro.

Se você planeja explorar várias arquiteturas, tutoriais e guias de início rápido, a reutilização de projetos pode evitar que você exceda limites da cota.

Excluir um projeto do Google Cloud :

gcloud projects delete PROJECT_ID

Excluir recursos individuais

Se você quiser continuar usando o projeto atual, exclua os recursos individuais usados neste tutorial.

Excluir o bucket

Se você não precisar mais do bucket usado neste tutorial, exclua-o.

Exclua os arquivos de saída no bucket

Depois que o pipeline terminar de ser executado, ele vai criar e armazenar arquivos de saída na pasta WORK_DIRECTORY do bucket do Cloud Storage.

Para reduzir as cobranças do Cloud Storage na conta Google Cloud atual, exclua a pasta que contém os arquivos de saída do pipeline usando o console Google Cloud ou a linha de comando.

Console

Para excluir a pasta WORK_DIRECTORY e todos os arquivos de saída do bucket do Cloud Storage usando o consoleGoogle Cloud , siga estas etapas:

1. No console Google Cloud , acesse a página Buckets.

   Acessar buckets

2. Na coluna Nome, clique no nome do bucket criado nas etapas anteriores.

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

   1. Clique em Excluir.

   2. Para confirmar, digite DELETE e clique em Excluir.

gcloud

Para excluir a pasta WORK_DIRECTORY e todos os arquivos de saída do bucket do Cloud Storage usando a CLI gcloud, use o comando gcloud storage rm com a flag --recursive.

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

Substitua:

• BUCKET_NAME: o nome do bucket que você especificou nas etapas anteriores.

• WORK_DIRECTORY: o diretório para armazenar os arquivos de saída do pipeline especificados nas etapas anteriores.

A seguir

• Para saber mais sobre como implantar fluxos de trabalho do Nextflow, consulte o repositório do Nextflow no GitHub.

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