Orquestre jobs executando pipelines do Nextflow no Batch

---

Este tutorial explica como executar Nextflow (em inglês) no Batch. Especificamente, este tutorial executa um exemplo pipeline de ciências biológicas que quantifica os atributos genômicos a partir de dados curtos de leitura usando RNA-Seq (link em inglês).

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 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.
• Visualizar as saídas do pipeline.
• Faça uma limpeza para evitar cobranças adicionais:
  • Excluir um projeto.
  • Excluir recursos individuais.

Custos

Neste documento, você 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 uma avaliação gratuita.

Os recursos criados neste tutorial geralmente custam menos de um dólar, supondo que você tenha concluído todas as etapas, incluindo a limpeza, em um 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. Install the Google Cloud CLI.

3. To initialize the gcloud CLI, run the following command:

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

8. To initialize the gcloud CLI, run the following command:

   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. Certifique-se de que o projeto tenha pelo menos conta de serviço com o as permissões necessárias para este tutorial.

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

    Cada job requer uma conta de serviço que permita Agente de serviço em lote para criar e acessar os recursos necessárias para executar o job. Para este tutorial, a conta de serviço do job é Conta de serviço padrão do Compute Engine

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

    • Batch Agent Reporter (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 como conceder papéis, consulte Gerenciar acesso.

    Talvez o administrador também possa conceder à conta de serviço padrão do Compute Engine as permissões necessárias por meio de tags personalizadas ou outras funções predefinidas de rede.

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. Conforme o criador de projeto, você recebe automaticamente o papel de Proprietário (roles/owner) papel do IAM, que já tem todos os as permissões necessárias para este tutorial.

    Para receber as permissões necessárias para concluir este tutorial, faça o seguinte: 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
    

Criar um bucket do Cloud Storage

Criar um bucket do Cloud Storage para armazenar trabalho e saída temporários 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 exclusivo globalmente do 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 método comando gcloud storage buckets create.

gcloud storage buckets create gs://BUCKET_NAME

Substitua BUCKET_NAME por uma um nome exclusivo globalmente para seu bucket.

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

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 do 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 que o pipeline pode usar para armazenar registros e saídas.

      Por exemplo, insira workDir.

   3. Após o campo google.region, adicione o Linha google.project = 'PROJECT_ID' em que PROJECT_ID é o ID do projeto da projeto do Google Cloud.

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

   1. Pressione Control+S.

   2. Digite Y.

   3. Pressione Enter.

Executar o pipeline

Execute o pipeline de amostra 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 fornecidas no etapas anteriores. Essa operação pode levar até 10 minutos para ser concluída.

Depois que a execução do pipeline termina, a saída deve ser semelhante à seguintes:

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

Exibir saídas do pipeline

Após a execução do pipeline, ele armazena arquivos de saída, registros, erros ou arquivos temporários no arquivo results/qc_report.html da Pasta WORK_DIRECTORY do seu Cloud Storage do Google Cloud.

Para verificar os arquivos de saída do pipeline no Pasta WORK_DIRECTORY do seu 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 que você criou na etapas anteriores.

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

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

gcloud

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

gcloud storage ls gs://BUCKET_NAME/WORK_DIRECTORY

Substitua:

• BUCKET_NAME: o nome do bucket que você quer usar criados nas etapas anteriores.

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

A saída lista uma pasta para cada tarefa separada executada pelo pipeline. Cada pasta contém os comandos que foram executados, os arquivos de saída e 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.

Exclua 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 quiser continuar usando o projeto atual, exclua o projeto recursos usados neste tutorial.

Excluir o bucket

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

Excluir os arquivos de saída no bucket

Após a execução do pipeline, ele cria e armazena arquivos de saída no Pasta WORK_DIRECTORY do seu Cloud Storage do Google Cloud.

Para reduzir os encargos do Cloud Storage aos valores conta do Google Cloud, é possível excluir a pasta que contém a usando o console do Google Cloud ou a linha de comando.

Console

Para excluir a pasta WORK_DIRECTORY e todas as 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 que você criou na etapas anteriores.

3. Na página Detalhes do bucket, selecione a linha que contém o 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 todas as arquivos de saída do bucket do Cloud Storage usando o CLI gcloud, use o gcloud storage rm com o --recursive.

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

Substitua:

• BUCKET_NAME: o nome do bucket que você quer usar especificado nas etapas anteriores.

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

A seguir

• Para saber mais sobre como implantar os fluxos de trabalho do Nextflow, consulte Repositório GitHub do Nextflow (em inglês).

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