Aplicar as práticas recomendadas do GATK

Aviso:este tutorial mostra como executar um fluxo de trabalho predefinido em um caso de uso limitado, mas não deve ser executado na produção.

Nesta página, explicamos como executar um pipeline de análise genômica secundária no Google Cloud usando as práticas recomendadas do Genome Analysis Toolkit (GATK). As práticas recomendadas do GATK são fornecidas pelo Broad Institute (em inglês).

O fluxo de trabalho usado neste tutorial é uma implementação das práticas recomendadas do GATK referentes à descoberta de variantes nos dados de sequenciamento do genoma inteiro (WGS, na sigla em inglês). O fluxo de trabalho é gravado na linguagem de definição de fluxo de trabalho (WDL, na sigla em inglês) do Broad Institute e processado pelo executor da WDL, Cromwell (links em inglês).

Observação: você é responsável por cumprir os termos do Contrato de Licença de Usuário Final do GATK, incluindo o requisito de atribuição.

Objetivos

Depois de concluir este tutorial, você saberá:

• Como executar um pipeline usando as práticas recomendadas do GATK com dados da versão 38 (em inglês) do genoma humano de referência
• Como executar um canal usando as práticas recomendadas do GATK com seus próprios dados

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

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

   Enable the APIs

5. Install the Google Cloud CLI.

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

   gcloud init

7. Update and install gcloud components:

   gcloud components update
   gcloud components install beta

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

9. Make sure that billing is enabled for your Google Cloud project.

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

    Enable the APIs

11. Install the Google Cloud CLI.

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

    gcloud init

13. Update and install gcloud components:

    gcloud components update
    gcloud components install beta

14. Instale o git para fazer o download dos arquivos necessários.

    Fazer o download do git

15. Por padrão, o Compute Engine tem cotas de recursos para impedir o uso inadvertido. Ao aumentar as cotas, é possível iniciar mais máquinas virtuais simultaneamente, o que aumenta a capacidade de processamento e reduz o tempo de retorno.

    Para os melhores resultados neste tutorial, você precisa solicitar mais cota acima do padrão do seu projeto. Veja recomendações para aumentos de cota na lista a seguir, além das cotas mínimas necessárias para executar o tutorial. Faça as solicitações de cota na região us-central1:

    • CPUs: 101 (mínimo de 17)
    • Padrão de disco permanente (GB): 10.500 (mínimo de 320)
    • Endereços IP em uso: 51 (mínimo de 2)

    É possível deixar outros campos de solicitação de cota vazios para manter suas cotas atuais.

    Observação: se o projeto foi criado usando a avaliação gratuita, você precisa solicitar o aumento das cotas para executar as práticas recomendadas do GATK no Google Cloud.

Criar um bucket do Cloud Storage

Crie um bucket do Cloud Storage usando o comando gcloud storage buckets create. Devido a um requisito no mecanismo do Cromwell, não use um caractere de sublinhado (_) no nome do bucket ou você encontrará um erro.

gcloud storage buckets create gs://BUCKET

O pipeline gera resultados, registros e arquivos intermediários para esse bucket.

Fazer o download de arquivos de exemplo

Execute os seguintes comandos para fazer o download do WDL e do script auxiliar:

git clone https://github.com/broadinstitute/wdl-runner.git
git clone https://github.com/gatk-workflows/broad-prod-wgs-germline-snps-indels.git

O repositório gatk-workflows/broad-prod-wgs-germline-snps-indels contém os seguintes arquivos necessários para executar o pipeline:

• *.wdl: definição do fluxo de trabalho
• *.inputs.json: parâmetros de entrada, incluindo caminhos para os arquivos BAM e o genoma de referencial
• *.options.json: opções de ambiente de execução do fluxo de trabalho

O arquivo de definição de canal do Cromwell usado para executar canais WDL fica no repositório broadinstitute/wdl-runner/wdl_runner/.

Executar o canal usando dados de amostra

Nesta seção, mostramos como executar o pipeline com dados do WGS usando o build 38 (em inglês) do genoma de referência humana. Os arquivos de entrada são arquivos BAM desalinhados.

Para executar o pipeline, conclua as seguintes etapas:

1. Crie a variável de ambiente GATK_GOOGLE_DIR que aponta para a pasta que contém os arquivos de canal Broad:

   export GATK_GOOGLE_DIR="${PWD}"/broad-prod-wgs-germline-snps-indels

2. Crie a variável de ambiente GATK_OUTPUT_DIR que aponta para o bucket do Cloud Storage e uma pasta para output do fluxo de trabalho, logging e arquivos intermediários work:

   export GATK_OUTPUT_DIR=gs://BUCKET/FOLDER

3. Altere o diretório para a pasta /wdl_runner no repositório de que você fez o download. Esse diretório contém o arquivo de definição de pipeline para executar pipelines baseados em WDL no Google Cloud:

   cd wdl-runner/wdl_runner/

4. Execute o canal:

   Importante: se você encontrar a mensagem de erro "ERROR: (gcloud.beta.lifesciences.pipelines.run) INVALID_ARGUMENT: Error: validating pipeline: zones and regions cannot be specified together", consulte Solução de problemas.

   Escolha uma das seguintes opções dependendo se você está usando uma VPC padrão ou uma VPC personalizada:

   VPC padrão

   gcloud beta lifesciences pipelines run \
   --pipeline-file wdl_pipeline.yaml \
   --location us-central1 \
   --regions us-central1 \
   --inputs-from-file WDL=${GATK_GOOGLE_DIR}/PairedEndSingleSampleWf.wdl,\
   WORKFLOW_INPUTS=${GATK_GOOGLE_DIR}/PairedEndSingleSampleWf.hg38.inputs.json,\
   WORKFLOW_OPTIONS=${GATK_GOOGLE_DIR}/PairedEndSingleSampleWf.options.json \
   --env-vars WORKSPACE=${GATK_OUTPUT_DIR}/work,\
   OUTPUTS=${GATK_OUTPUT_DIR}/output \
   --logging ${GATK_OUTPUT_DIR}/logging/

   VPC personalizada

   1. Crie as variáveis de ambiente NETWORK e SUBNETWORK para especificar o nome da sua rede VPC e da sub-rede:

      export NETWORK=VPC_NETWORK
      export SUBNETWORK=VPC_SUBNET

   2. Edite o arquivo PairedEndSingleSampleWf.options.json localizado no diretório broad-prod-wgs-germline-snps-indels e modifique as zonas para incluir apenas as que fazem parte da região da sub-rede. Por exemplo, se você estiver usando uma sub-rede us-central1, o campo zones será "zones": "us-central1-a us-central1-b us-central1-c us-central1-f".

   3. gcloud beta lifesciences pipelines run \
      --pipeline-file wdl_pipeline.yaml \
      --location us-central1 \
      --regions us-central1 \
      --network ${NETWORK} \
      --subnetwork ${SUBNETWORK} \
      --inputs-from-file WDL=${GATK_GOOGLE_DIR}/PairedEndSingleSampleWf.wdl,\
      WORKFLOW_INPUTS=${GATK_GOOGLE_DIR}/PairedEndSingleSampleWf.hg38.inputs.json,\
      WORKFLOW_OPTIONS=${GATK_GOOGLE_DIR}/PairedEndSingleSampleWf.options.json \
      --env-vars WORKSPACE=${GATK_OUTPUT_DIR}/work,\
      OUTPUTS=${GATK_OUTPUT_DIR}/output,\
      NETWORK=${NETWORK},\
      SUBNETWORK=${SUBNETWORK} \
      --logging ${GATK_OUTPUT_DIR}/logging/

5. O comando retorna um ID de operação no formato Running [operations/OPERATION_ID]. Use o comando gcloud beta lifesciences describe para rastrear o status do pipeline executando o seguinte comando (verifique se o valor da sinalização --location corresponde ao local especificado na etapa anterior):

   gcloud beta lifesciences operations describe OPERATION_ID \
       --location=us-central1 \
       --format='yaml(done, error, metadata.events)'

6. O comando operations describe retorna done: true quando o pipeline é concluído.

   É possível executar um script incluído com wdl_runner para verificar a cada 300 segundos se o job está em execução, terminou ou retornou um erro:

   ../monitoring_tools/monitor_wdl_pipeline.sh OPERATION_ID us-central1 300

7. Depois que o canal for concluído, execute o seguinte comando para listar as saídas no bucket do Cloud Storage:

   gcloud storage ls gs://BUCKET/FOLDER/output/

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.

Executar o canal de práticas recomendadas do GATK nos dados

Antes de executar o canal nos dados locais, copie-os para um bucket do Cloud Storage.

Copiar arquivos de entrada

O canal pode ser executado com arquivos BAM desalinhados armazenados no Cloud Storage. Se os arquivos estiverem em um formato diferente, como FASTQ ou BAM alinhado, converta-os antes do upload para o Cloud Storage. É possível convertê-los localmente ou usar a API Pipelines (em inglês) para convertê-los na nuvem.

Veja no exemplo a seguir como copiar um único arquivo de um sistema de arquivos local para um bucket do Cloud Storage:

gcloud storage cp FILE gs://BUCKET/FOLDER

Para mais exemplos de como copiar arquivos para um bucket do Cloud Storage, consulte a seção sobre Como copiar dados no Cloud Storage.

A CLI gcloud verifica somas de verificação automaticamente. Desse modo, quando a transferência for bem-sucedida, seus dados serão compatíveis para uso com as práticas recomendadas do GATK.

Executar o canal nos dados

Para executar as práticas recomendadas do GATK nos arquivos BAM desalinhados, faça uma cópia de PairedEndSingleSampleWf.hg38.inputs.json (em inglês) e atualize os caminhos para apontar para os arquivos em um bucket do Cloud Storage. Então, siga as etapas em Executar o pipeline com dados de amostra usando o arquivo PairedEndSingleSampleWf.hg38.inputs.json atualizado.

Se os dados não forem compostos de arquivos BAM desalinhados e contiverem genomas de referência, sequenciamento de exoma, painéis segmentados e dados somáticos, será preciso usar fluxos de trabalho diferentes. Consulte o Fórum de suporte do GATK e o repositório do GitHub do Broad Institute (links em inglês) para mais informações.

Solução de problemas

• O canal está configurado para usar instâncias do Compute Engine em regiões e zonas específicas. Quando você executa a CLI gcloud, ela usa automaticamente uma região e uma zona padrão com base no local em que o projeto do Google Cloud foi criado. Isso poderá resultar na seguinte mensagem de erro quando você executar o canal:

  "ERROR: (gcloud.beta.lifesciences.pipelines.run) INVALID_ARGUMENT: Error: validating pipeline: zones and regions cannot be specified together"

  Para resolver esse problema, remova a região e a zona padrão executando os comandos abaixo. Em seguida, execute o pipeline novamente:

  gcloud config unset compute/zone
  gcloud config unset compute/region
  

  Para mais informações sobre como definir a região e a zona padrão do seu projeto do Google Cloud, consulte Como alterar a região ou a zona padrão.

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

• O GATK tem expectativas rigorosas sobre formatos de arquivo de entrada. Para evitar problemas, verifique se seus arquivos passaram pelo ValidateSamFile.

• Se houver falha na execução do GATK, consulte os registros executando o seguinte comando:

  gcloud storage ls gs://BUCKET/FOLDER/logging

• Se você encontrar erros de permissão, verifique se a conta de serviço tem acesso de leitura para os arquivos de entrada e acesso de gravação para o caminho do bucket de saída. Se você estiver gravando arquivos de saída em um bucket em um projeto do Google Cloud que não é seu, precisará conceder permissão à conta de serviço para acessar o bucket.

Como fazer a limpeza

Como excluir arquivos intermediários do bucket do Cloud Storage

Quando você executa o pipeline, ele armazena arquivos intermediários em gs://BUCKET/FOLDER/work. É 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 usado no diretório work, execute o comando a seguir. A execução do comando pode levar vários minutos devido ao tamanho dos arquivos no diretório.

gcloud storage du gs://BUCKET/FOLDER/work --readable-sizes --summarize

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

gcloud storage rm gs://BUCKET/FOLDER/work/**

Excluir o projeto

A maneira mais fácil de evitar a cobrança é excluir o projeto usado no tutorial.

Para excluir o projeto, faça o seguinte:

Aviso: veja as consequências da exclusão de um projeto:

• Se você usou um projeto atual, exclua também qualquer outro trabalho feito no projeto.
• Não é possível reutilizar o ID de um projeto excluído. Se você criou um ID do projeto personalizado e pretende usá-lo no futuro, exclua os recursos contidos no projeto. Esta etapa garante que os URLs que usam o ID do projeto, como um URL appspot.com, permaneçam disponíveis.

Se você estiver consultando vários tutoriais e guias de início rápido, reutilize projetos em vez de excluí-los para evitar que os limites de cota do projeto sejam excedidos.

1. No console do Google Cloud, acesse a página "Projetos".

   Acessar a página "Projetos"

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

A seguir

• O site do GATK e os fóruns do Broad Institute (links em inglês) incluem informações, documentação e suporte mais completos referentes às ferramentas do GATK e ao WDL.