Executar o Nextflow

---

Nesta página, explicamos como executar um pipeline do Nextflow no Google Cloud.

O pipeline usado neste tutorial é uma prova de conceito de um pipeline RNA-Seq destinado a mostrar o uso do Nextflow no Google Cloud.

Observação: você é responsável por seguir os termos do Contrato de licença do Nextflow (em inglês) e o Contrato de licença do pipeline RNAseq-NF (em inglês).

Objetivos

Depois de concluir este tutorial, você saberá como:

• Instale o Nexflow no Cloud Shell.
• configurar um pipeline do Nextflow;
• executar um pipeline usando o Nextflow no Google Cloud.

Custos

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

• Compute Engine
• 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.

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. In the Google Cloud console, on the project selector page, select or create 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.

   Go to project selector

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

4. Enable the Cloud Life Sciences, Compute Engine, and Cloud Storage APIs.

   Enable the APIs

5. In the Google Cloud console, on the project selector page, select or create 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.

   Go to project selector

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

7. Enable the Cloud Life Sciences, Compute Engine, and Cloud Storage APIs.

   Enable the APIs

crie um bucket do Cloud Storage

Crie um bucket com nome exclusivo seguindo as orientações nas diretrizes de nomenclatura de bucket. O bucket armazena arquivos temporários de trabalho e de saída ao longo deste tutorial. Para compatibilidade com DNS, este tutorial não aceita nomes de bucket com sublinhado (_).

Console

1. No console do Google Cloud, acesse a página Navegador do Cloud Storage:

   Acessar o navegador

2. Clique em Criar bucket.

3. Na página Criar um bucket, insira as informações do seu bucket.

4. Clique em Criar.

gcloud

1. Abra o Cloud Shell:

   Acesse o Cloud Shell

2. Use o comando gcloud storage buckets create:

   gcloud storage buckets create gs://BUCKET_NAME
   

   Substitua BUCKET_NAME pelo nome que você quer dar ao bucket, sujeito aos requisitos de nomenclatura. Por exemplo, my-bucket.

   Se a solicitação for bem-sucedida, o comando retornará a seguinte mensagem:

   Creating gs://BUCKET_NAME/...
   

Criar uma conta de serviço e adicionar papéis

Conclua as etapas a seguir para criar uma conta de serviço e adicionar os seguintes papéis do Identity and Access Management:

• Executor de fluxos de trabalho do Cloud Life Sciences
• Usuário da conta de serviço
• Consumidor do Service Usage

• Administrador de objetos do Storage

Console

Crie uma conta de serviço usando o console do Google Cloud:

1. No Console do Google Cloud, acesse a página Contas de serviço.

   Acessar a página "Contas de serviço"

2. Clique em Criar conta de serviço.

3. No campo Nome da conta de serviço, insira nextflow-service-account e clique em Criar.

4. Na seção Conceder acesso a essa conta de serviço ao projeto, adicione os seguintes papéis na lista suspensa Selecionar um papel:

   • Executor de fluxos de trabalho do Cloud Life Sciences
   • Usuário da conta de serviço
   • Consumidor do Service Usage
   • Administrador de objetos do Storage

5. Clique em Continuar e depois em Concluído.

6. Na página Contas de serviço, encontre a conta de serviço que você criou. Na linha da conta de serviço, clique no botão Mais e em Gerenciar chaves.

7. Na página Chaves, clique em Adicionar chave e em Criar nova chave.

8. Selecione JSON como Tipo de chave e clique em Criar.

   O download de um arquivo JSON com sua chave é feito no seu computador.

gcloud

Conclua as seguintes etapas usando o Cloud Shell:

1. Abra o Cloud Shell.

   Acessar o Cloud Shell

2. Defina as variáveis a serem usadas na criação da conta de serviço, substituindo PROJECT_ID pelo ID do projeto.

   export PROJECT=PROJECT_ID
   export SERVICE_ACCOUNT_NAME=nextflow-service-account
   export SERVICE_ACCOUNT_ADDRESS=${SERVICE_ACCOUNT_NAME}@${PROJECT}.iam.gserviceaccount.com

3. Crie a conta de serviço.

   gcloud iam service-accounts create ${SERVICE_ACCOUNT_NAME}

4. A conta precisa dos seguintes papéis do IAM:

   • roles/lifesciences.workflowsRunner
   • roles/iam.serviceAccountUser
   • roles/serviceusage.serviceUsageConsumer
   • roles/storage.objectAdmin

   Conceda esses papéis executando os seguintes comandos no Cloud Shell:

   gcloud projects add-iam-policy-binding ${PROJECT} \
       --member serviceAccount:${SERVICE_ACCOUNT_ADDRESS} \
       --role roles/lifesciences.workflowsRunner
   
   gcloud projects add-iam-policy-binding ${PROJECT} \
       --member serviceAccount:${SERVICE_ACCOUNT_ADDRESS} \
       --role roles/iam.serviceAccountUser
   
   gcloud projects add-iam-policy-binding ${PROJECT} \
       --member serviceAccount:${SERVICE_ACCOUNT_ADDRESS} \
       --role roles/serviceusage.serviceUsageConsumer
   
   gcloud projects add-iam-policy-binding ${PROJECT} \
       --member serviceAccount:${SERVICE_ACCOUNT_ADDRESS} \
       --role roles/storage.objectAdmin

Fornecer credenciais para seu aplicativo

É possível fornecer credenciais de autenticação ao código ou aos comandos do aplicativo definindo a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS como o caminho do arquivo JSON que contém a chave da conta de serviço.

As etapas a seguir mostram como definir a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS.

Console

1. Abra o Cloud Shell.

   Acessar o Cloud Shell

2. No menu Mais do Cloud Shell, selecione Fazer upload do arquivo e escolha o arquivo de chave JSON que você criou. O arquivo é enviado para o diretório inicial da sua instância do Cloud Shell.

3. Confirme se o arquivo enviado está no diretório atual e o nome do arquivo executando o seguinte comando:

   ls

4. Defina as credenciais, substituindo KEY_FILENAME.json pelo nome do arquivo de chave.

   export GOOGLE_APPLICATION_CREDENTIALS=${PWD}/KEY_FILENAME.json

gcloud

Conclua as seguintes etapas usando o Cloud Shell:

1. Abra o Cloud Shell.

   Acessar o Cloud Shell

2. No menu Mais do Cloud Shell, selecione Fazer upload do arquivo e escolha o arquivo de chave JSON que você criou. O arquivo é enviado para o diretório inicial da sua instância do Cloud Shell.

3. Confirme se o arquivo enviado está no diretório atual e o nome do arquivo executando o seguinte comando:

   ls

4. Defina o arquivo de chave privada como a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS:

   export SERVICE_ACCOUNT_KEY=${SERVICE_ACCOUNT_NAME}-private-key.json
   gcloud iam service-accounts keys create \
     --iam-account=${SERVICE_ACCOUNT_ADDRESS} \
     --key-file-type=json ${SERVICE_ACCOUNT_KEY}
   export SERVICE_ACCOUNT_KEY_FILE=${PWD}/${SERVICE_ACCOUNT_KEY}
   export GOOGLE_APPLICATION_CREDENTIALS=${PWD}/${SERVICE_ACCOUNT_KEY}

Instalar e configurar o Nextflow no Cloud Shell

Para evitar a instalação de software na sua máquina, continue executando todos os comandos do terminal neste tutorial a partir do Cloud Shell.

1. Se ainda não estiver aberto, abra o Cloud Shell.

   Acessar o Cloud Shell

2. Instale o Nextflow executando os seguintes comandos:

   export NXF_VER=21.10.0
   export NXF_MODE=google
   curl https://get.nextflow.io | bash

   Se a instalação for concluída com êxito, a seguinte mensagem será exibida:

       N E X T F L O W
   version 21.10.0 build 5430
   created 01-11-2020 15:14 UTC (10:14 EDT)
   cite doi:10.1038/nbt.3820
   http://nextflow.io
   
   Nextflow installation completed. Please note:
   ‐ the executable file `nextflow` has been created in the folder: DIRECTORY
   ‐ you may complete the installation by moving it to a directory in your $PATH
   

3. Execute o comando a seguir para clonar o repositório do pipeline de amostra. O repositório inclui o pipeline a ser executado e os dados de amostra que o pipeline usa.

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

4. Conclua as etapas a seguir para configurar o Nextflow:

   1. Mude para a pasta rnaseq-nf.

      cd rnaseq-nf
      git checkout v2.0

   2. Usando um editor de texto de sua escolha, edite o arquivo chamado nextflow.config e faça as seguintes atualizações na seção gls:

      • Adicione a linha google.project caso ela não esteja presente.
      • Substitua PROJECT_ID pela ID do seu projeto.
      • Se quiser, altere o valor de google.location. Ele precisa ser um dos locais disponíveis da API Cloud Life Sciences.
      • Se quiser, altere o valor de google.region que especifica a região em que as VMs do Compute Engine são iniciadas. Consulte as regiões e zonas disponíveis do Compute Engine.
      • Substitua BUCKET pelo nome do bucket criado anteriormente.
      • Substitua WORK_DIR pelo nome de uma pasta a ser usada para geração de registros e saída. Use um novo nome de diretório que ainda não exista no seu bucket.
      Observação: o local da variável workDir precisa conter pelo menos um subdiretório. Não use apenas o nome do bucket.

      gls {
         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-lifesciences'
         process.container = 'nextflow/rnaseq-nf:latest'
         workDir = 'gs://BUCKET/WORK_DIR'
         google.location = 'europe-west2'
         google.region  = 'europe-west1'
         google.project = 'PROJECT_ID'
      }

   3. Volte para a pasta anterior.

      cd ..

Execute o pipeline com o Nextflow

Execute o pipeline com o Nextflow. Depois de iniciar o pipeline, ele continuará em execução em segundo plano até a conclusão. Pode levar até 10 minutos para o pipeline ser concluído.

./nextflow run rnaseq-nf/main.nf -profile gls

Depois que o pipeline for concluído, a seguinte mensagem será exibida:

N E X T F L O W  ~  version 21.10.0
Launching `rnaseq-nf/main.nf` [suspicious_mestorf] - revision: ef908c0bfd
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
executor >  google-lifesciences (4)
[db/2af640] process > RNASEQ:INDEX (transcript)     [100%] 1 of 1 ✔
[a6/927725] process > RNASEQ:FASTQC (FASTQC on gut) [100%] 1 of 1 ✔
[59/438177] process > RNASEQ:QUANT (gut)            [100%] 1 of 1 ✔
[9a/9743b9] process > MULTIQC                       [100%] 1 of 1 ✔
Done! Open the following report in your browser --> results/multiqc_report.html
Completed at: DATE TIME
Duration    : 10m
CPU hours   : 0.2
Succeeded   : 4

Como visualizar a saída do pipeline do Nextflow

Depois que o pipeline for concluído, será possível verificar a saída e os registros, erros, comandos executados e arquivos temporários.

O pipeline salva o arquivo de saída final, results/qc_report.html, no bucket do Cloud Storage especificado no arquivo nextflow.config.

Para verificar arquivos de saída individuais de cada tarefa e arquivos intermediários, siga estas etapas:

Console

1. No Console do Cloud Storage, abra a página Navegador do Storage:

   Ir para o navegador do Cloud Storage

2. Acesse BUCKET e navegue até o WORK_DIR especificado no arquivo nextflow.config.

3. Há uma pasta para cada tarefa separada que foi executada no pipeline.

4. A pasta contém os comandos que foram executados, os arquivos de saída e os arquivos temporários usados no fluxo de trabalho.

gcloud

1. Para ver os arquivos de saída no Cloud Shell, primeiro abra o Cloud Shell:

   Acessar o Cloud Shell

2. Execute o seguinte comando para listar as saídas no bucket do Cloud Storage. Atualize BUCKET e WORK_DIR para as variáveis especificadas no arquivo nextflow.config.

   gcloud storage ls gs://BUCKET/WORK_DIR

3. O resultado mostra uma pasta para cada tarefa executada. Continue listando o conteúdo dos subdiretórios subsequentes para ver todos os arquivos criados pelo pipeline. Atualize TASK_FOLDER uma das pastas de tarefas listadas no comando anterior.

   gcloud storage ls gs://BUCKET/WORK_DIR/FOLDER/TASK_FOLDER

Você pode ver os arquivos intermediários criados pelo canal e escolher os que quer manter, ou removê-los para reduzir os custos associados ao Cloud Storage. Para remover os arquivos, consulte Como excluir arquivos intermediários do bucket do Cloud Storage.

Solução de problemas

• Se você encontrar problemas ao executar o pipeline, consulte a Solução de problemas da API do Cloud Life Sciences.

• Se o pipeline falhar, será possível verificar os registros de cada tarefa analisando os arquivos de registro em cada uma das pastas no Cloud Storage, como .command.err, .command.log, .command.out e assim por diante.

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.

Depois de concluir o tutorial, limpe os recursos que você criou para que eles parem de usar a cota e incorrer em cobranças. Nas seções a seguir, você aprenderá a excluir e desativar esses recursos.

Excluir arquivos intermediários do bucket do Cloud Storage

Quando você executa o pipeline, ele armazena arquivos intermediários em gs://BUCKET/WORK_DIR. É possível remover os arquivos após a conclusão do fluxo de trabalho para reduzir as cobranças do Cloud Storage.

Para visualizar a quantidade de espaço usada no diretório, execute seguinte comando:

gcloud storage du gs://BUCKET/WORK_DIR --readable-sizes --summarize

Para remover os arquivos do WORK_DIR, siga estas etapas:

Console

1. No Console do Cloud Storage, abra a página Navegador do Storage:

   Ir para o navegador do Cloud Storage

2. Acesse o BUCKET e navegue até o WORK_DIR especificado no arquivo nextflow.config.

3. Navegue pelas subpastas e exclua os arquivos ou diretórios indesejados. Para excluir todos os arquivos, exclua todo o WORK_DIR.

gcloud

1. Abra o Cloud Shell e execute o seguinte:

   Acessar o Cloud Shell

2. Para remover os arquivos intermediários do diretório WORK_DIR, execute o seguinte comando:

   gcloud storage rm gs://BUCKET/WORK_DIR/**

Exclua o projeto

O jeito mais fácil de evitar cobranças é excluindo o projeto que você criou para o tutorial.

Para excluir o projeto:

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.

A seguir

As seguintes páginas incluem mais informações, documentação e suporte para usar o Nextflow:

• Site do Nextflow (em inglês)
• Repositório do GitHub do Nextflow
• Documentação do Nextflow (em inglês)