Orquestre jobs executando pipelines do Nextflow em lote

---

Neste tutorial, explicamos como executar um Nextflow. pipeline no Batch. Especificamente, este tutorial executa o pipeline de amostra rnaseq-nf do Nextflow para ciências da vida, que quantifica os 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 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;
• Execute um pipeline de exemplo usando o Nextflow no Batch.
• Conferir as saídas do pipeline.
• Faça uma limpeza para evitar cobranças extras seguindo um destes procedimentos:
  • 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. 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.
2. Install the Google Cloud CLI.

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

   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. Make sure that billing is enabled for your Google Cloud project.

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

   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. 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. Make sure that billing is enabled for your Google Cloud project.

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

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

12. 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 para esta 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 seu 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 um job em lote para pipeline do Nextflow para usar uma rede diferente, é possível modificar nextflow.config neste tutorial para também definir o rede e sub-rede usando o google.batch.network e google.batch.subnetwork Campos Nextflow, respectivamente. No entanto, você também precisa garantir que a rede e sub-rede estejam configurados corretamente para sua carga de trabalho. Para mais informações, consulte Visão geral da rede em lote.

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

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

    Observação:nenhuma ação é necessária nessa etapa, a menos que sua organização desativa as permissões automáticas das contas de serviço padrão ativando a restrição de política iam.automaticIamGrantsForDefaultServiceAccounts, seu projeto tiver modificado a conta de serviço padrão do Compute Engine, ou você querem 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 do Batch, peça ao administrador para conceder à conta de serviço do job os seguintes papéis do IAM:

    • 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 de outros papéis predefinidos.

14. 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 do IAM de proprietário (roles/owner), que já tem todas as permissões necessárias para este tutorial.

    Para conseguir 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
    • Administrador de objetos do Storage (roles/storage.objectAdmin) no projeto

15. 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 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 exemplo do 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 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 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. 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 do no projeto atual do 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 trabalho que você preparou para este tutorial.

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

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

Depois que o pipeline terminar a execução, 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

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

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. In the Google Cloud console, go to the Manage resources page.

   Go to Manage resources

2. In the project list, select the project that you want to delete, and then click Delete.
3. In the dialog, type the project ID, and then click Shut down to delete the project.

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.

Delete a Google Cloud project:

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

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 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 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 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 o os arquivos de saída do pipeline especificados nas etapas anteriores.

A seguir

• Para saber mais sobre a implantação dos fluxos de trabalho do Nextflow, consulte a Repositório GitHub do Nextflow (em inglês).

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