Orquestre jobs executando pipelines do Nextflow no Batch

---

Neste tutorial, explicamos como executar um pipeline do Nextflow no Batch. Especificamente, neste tutorial, é executado um exemplo de pipeline de ciências biológicas, que quantifica atributos genômicos de dados de leitura curta usando RNA-Seq.

Este tutorial é destinado a usuários do Batch que querem usar o Nextflow com ele.

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 version 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ê 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 amostra usando o Nextflow no Batch.
• Conferir saídas do pipeline.
• Faça uma limpeza para evitar cobranças adicionais realizando um dos seguintes procedimentos:
  • Excluir um projeto.
  • Excluir recursos individuais.

Custos

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

• Lote
• 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 uma avaliação gratuita.

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

Antes de começar

1. Faça login na sua conta do Google Cloud. Se você começou a usar o Google Cloud agora, 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.
2. Instale a CLI do Google Cloud.

3. Para inicializar a CLI gcloud, execute o seguinte comando:

   gcloud init

4. Crie ou selecione um projeto do Google Cloud.

   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 do Google Cloud que você está criando.

   • Selecione o projeto do Google Cloud que você criou:

     gcloud config set project PROJECT_ID

     Substitua PROJECT_ID pelo nome do projeto do Google Cloud.

5. Verifique se a cobrança está ativada para o seu projeto do Google Cloud.

6. Ative as APIs Batch, Cloud Storage, Compute Engine, and Logging:

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

7. Instale a CLI do Google Cloud.

8. Para inicializar a CLI gcloud, execute o seguinte comando:

   gcloud init

9. Crie ou selecione um projeto do Google Cloud.

   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 do Google Cloud que você está criando.

   • Selecione o projeto do Google Cloud que você criou:

     gcloud config set project PROJECT_ID

     Substitua PROJECT_ID pelo nome do projeto do Google Cloud.

10. Verifique se a cobrança está ativada para o seu projeto do Google Cloud.

11. Ative as APIs Batch, Cloud Storage, Compute Engine, and Logging:

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

12. Verifique se o projeto tem pelo menos uma conta de serviço com as permissões necessárias para este tutorial.

    Observação: se você estiver usando um novo projeto, esta etapa não será necessária, a menos que sua organização impeça concessões automáticas de papéis para contas de serviço padrão. Por padrão, a conta de serviço padrão do Compute Engine recebe automaticamente o papel de Editor (roles/editor) do IAM, que já tem todas as permissões necessárias para este tutorial.

    Cada job requer uma conta de serviço que permite que o agente de serviço do Batch crie e acesse os recursos necessários para executar o job. Neste tutorial, a conta de serviço do job é a conta de serviço padrão do Compute Engine.

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

    • Relatório do agente em lote (roles/batch.agentReporter) no projeto
    • Administrador de armazenamento (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 como conceder papéis, consulte Gerenciar acesso.

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

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

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

    Para ter as permissões necessárias para 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, que, neste tutorial, é a conta de serviço padrão do Compute Engine.
    • Administrador de objetos do Storage (roles/storage.objectAdmin) no projeto

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

Crie um bucket do Cloud Storage

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

Console

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

1. No console do 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.

Linha de comando

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

gsutil

Para criar um bucket do Cloud Storage usando a ferramenta gsutil, use o comando gsutil mb.

gsutil mb 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 execução no Batch, siga estas etapas na linha de comando:

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

   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:

   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. Na seção gcb, 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. Depois do campo google.region, adicione a linha google.project = 'PROJECT_ID', em que PROJECT_ID é o ID do projeto atual do Google Cloud.

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

   1. Pressione Control+S.

   2. Digite Y.

   3. Pressione Enter.

execute o pipeline

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

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

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

Depois que a execução do pipeline for concluída, 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

Conferir 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 na 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 do 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 do 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 que foram executados, os arquivos de saída e os arquivos temporários criados pelo pipeline.

Linha de comando

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.

gsutil

Para verificar os arquivos de saída do pipeline com a ferramenta gsutil, use o comando gsutil ls.

gsutil 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 cobranças é excluindo o projeto atual.

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

Console

Cuidado: excluir um projeto tem os seguintes efeitos:

• Tudo no projeto é excluído. Se você tiver usado um projeto existente para as tarefas neste documento, a exclusão dele incluirá a exclusão de quaisquer outros trabalhos feitos no projeto.
• Os IDs do projeto personalizados são perdidos. Ao criar o projeto, você pode ter criado um código 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 passar por várias arquiteturas, tutoriais ou guias de início rápido, a reutilização de projetos pode evitar que você exceda os limites da cota do projeto.

1. No Console do 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 existente para as tarefas neste documento, a exclusão dele incluirá a exclusão de quaisquer outros trabalhos feitos no projeto.
• Os IDs do projeto personalizados são perdidos. Ao criar o projeto, você pode ter criado um código 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 passar por várias arquiteturas, tutoriais ou guias de início rápido, a reutilização de projetos pode evitar que você exceda os limites da cota do projeto.

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

Exclua os arquivos de saída no bucket

Depois que o pipeline termina de ser executado, ele cria e armazena arquivos de saída na pasta WORK_DIRECTORY do bucket do Cloud Storage.

Para reduzir as cobranças do Cloud Storage na conta atual do Google Cloud, exclua a pasta que contém os arquivos de saída do pipeline usando o console do 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 console do Google Cloud, siga estas etapas:

1. No console do 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.

Linha de comando

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 sinalização --recursive.

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

Substitua:

• BUCKET_NAME: o nome do bucket especificado nas etapas anteriores.

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

gsutil

Para excluir a pasta WORK_DIRECTORY e todos os arquivos de saída do bucket do Cloud Storage usando a ferramenta gsutil, use o comando gsutil rm com as opções -m e -r.

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

Substitua:

• BUCKET_NAME: o nome do bucket especificado 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 a implantação de fluxos de trabalho do Nextflow, consulte o repositório do Nextflow no GitHub.

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