Como armazenar e carregar variantes genômicas

Nesta página você aprende como usar a ferramenta Variant Transforms com o objetivo de transformar e carregar arquivos VCF diretamente no BigQuery para análise em grande escala.

Se você estiver carregando um número grande de arquivos, consulte Como processar entradas grandes para ver recomendações sobre como melhorar o desempenho e reduzir custos.

Como carregar e transformar arquivos VCF no BigQuery

Antes de começar

Para executar a ferramenta, você precisa de:

Um projeto do Google Cloud com faturamento e as APIs Cloud Life Sciences, Compute Engine, Cloud Storage e Dataflow ativados.
um conjunto de dados atual do BigQuery e um bucket do Cloud Storage;
um arquivo VCF existente ou um arquivo GZIP ou BZIP com arquivos VCF em um bucket do Cloud Storage. Se você não tiver um arquivo VCF, poderá encontrar um nos conjuntos de dados públicos disponíveis.

Como executar a ferramenta

É possível executar a ferramenta usando uma imagem do Docker que tenha todos os binários e dependências necessários instalados.

Para executar a ferramenta usando uma imagem do Docker, siga estas etapas:

Use o comando a seguir para acessar a versão mais recente da ferramenta Variant Transforms.
```
docker pull gcr.io/cloud-lifesciences/gcp-variant-transforms
```
Copie o texto a seguir e salve-o em um arquivo chamado script.sh substituindo as variáveis pelos recursos relevantes do seu projeto do Google Cloud.
```
#!/bin/bash
# Parameters to replace:
# The GOOGLE_CLOUD_PROJECT is the project that contains your BigQuery dataset.
GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
INPUT_PATTERN=gs://BUCKET/*.vcf
OUTPUT_TABLE=GOOGLE_CLOUD_PROJECT:BIGQUERY_DATASET.BIGQUERY_TABLE
TEMP_LOCATION=gs://BUCKET/temp

COMMAND="vcf_to_bq \
    --input_pattern ${INPUT_PATTERN} \
    --output_table ${OUTPUT_TABLE} \
    --temp_location ${TEMP_LOCATION} \
    --job_name vcf-to-bigquery \
    --runner DataflowRunner"
docker run -v ~/.config:/root/.config \
    gcr.io/cloud-lifesciences/gcp-variant-transforms \
    --project "${GOOGLE_CLOUD_PROJECT}" \
    --zones us-west1-b \
    "${COMMAND}"
```
Ao especificar o local dos seus arquivos VCF em um bucket do Cloud Storage, especifique um único arquivo ou use um caractere curinga (*) para carregar vários arquivos de uma só vez. Formatos de arquivo aceitáveis incluem GZIP, BZIP e VCF. Para mais informações, consulte Como carregar vários arquivos.

Lembre-se de que a ferramenta é executada mais lentamente para arquivos compactados, porque eles não podem ser fragmentados. Se quiser mesclar amostras entre arquivos, consulte a documentação Mesclagem de variantes.

O diretório TEMP_LOCATION é usado para armazenar arquivos temporários necessários para executar a ferramenta. Ele pode ser qualquer diretório do Cloud Storage em que você tenha acesso de gravação.
Execute o seguinte comando para tornar script.sh executável:
```
chmod +x script.sh
```
Execute script.sh:
```
./script.sh
```
Dependendo de vários fatores, como o tamanho dos dados, o job pode levar de alguns minutos a uma hora ou mais.

Como a ferramenta usa o Dataflow, é possível navegar para o Console do Dataflow para ter uma visão detalhada do job. Por exemplo, é possível ver o número de registros processados, o número de workers e os registros de erro detalhados.
Depois que o job for concluído, execute o seguinte comando para listar todas as tabelas no seu conjunto de dados. Verifique se a nova tabela que contém seus dados do VCF está na lista:
```
bq ls --format=pretty GOOGLE_CLOUD_PROJECT:BIGQUERY_DATASET
```
Você também pode ver detalhes sobre a tabela, como o esquema e a data da última modificação:
```
bq show --format=pretty GOOGLE_CLOUD_PROJECT:BIGQUERY_DATASET.BIGQUERY_TABLE
```

Como definir zonas e regiões

O Google Cloud usa regiões subdivididas em zonas para definir a localização geográfica dos recursos físicos de computação.

É possível executar a ferramenta Variant Transforms em qualquer região ou zona coberta pelo Dataflow.

Para alterar a região em que a ferramenta é executada, atualize a variável de ambiente COMMAND do Docker e o comando gcloud da API do Cloud Life Sciences. Para restringir o processamento de jobs à Europa, o script de imagens do Docker da seção anterior precisará ser semelhante ao exemplo a seguir:

#!/bin/bash
# Parameters to replace:
# The GOOGLE_CLOUD_PROJECT is the project that contains your BigQuery dataset.
GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
INPUT_PATTERN=gs://BUCKET/*.vcf
OUTPUT_TABLE=GOOGLE_CLOUD_PROJECT:BIGQUERY_DATASET.BIGQUERY_TABLE
TEMP_LOCATION=gs://BUCKET/temp

COMMAND="vcf_to_bq \
    --input_pattern ${INPUT_PATTERN} \
    --output_table ${OUTPUT_TABLE} \
    --temp_location ${TEMP_LOCATION} \
    --job_name vcf-to-bigquery \
    --runner DataflowRunner
    --region europe-west1
    --zone europe-west1-b"
docker run -v ~/.config:/root/.config \
    gcr.io/cloud-lifesciences/gcp-variant-transforms \
    --project "${GOOGLE_CLOUD_PROJECT}" \
    --zones europe-west1-b \
    "${COMMAND}"

Para mais informações sobre como definir o local de um conjunto de dados do BigQuery, consulte Como criar um conjunto de dados.

Como carregar vários arquivos

É possível especificar quais arquivos VCF você quer carregar no BigQuery usando a sinalização --input_pattern no script acima. Por exemplo, para carregar todos os arquivos VCF no bucket my-bucket do Cloud Storage, defina a sinalização como o seguinte:

--input_pattern=gs://my-bucket/*.vcf

As seguintes operações ocorrem quando vários arquivos são carregados usando a ferramenta Variant Transforms:

Cria-se um esquema mesclado do BigQuery contendo dados de todos os arquivos VCF correspondentes listados na sinalização --input_pattern. Por exemplo, os campos INFO e FORMAT compartilhados entre os arquivos VCF são mesclados. Nesta etapa, presume-se que os campos definidos em vários arquivos com a mesma chave são compatíveis.
Os registros de todos os arquivos VCF são carregados em uma única tabela. Todos os campos ausentes são definidos como null na coluna associada.

Uma terceira etapa opcional seria mesclar amostras. Para mais informações, consulte Como mesclar variantes.

Ao carregar os arquivos VCF, as definições e valores de campo precisam ser consistentes. Caso contrário, ocorrerá uma falha na ferramenta. A ferramenta pode tentar corrigir essas inconsistências se for configurada para fazer isso. Para informações, consulte Como processar arquivos malformados.

Como anexar dados a tabelas atuais do BigQuery

É possível anexar dados a um tabela atual do BigQuery adicionando a sinalização --append ao executar a ferramenta Variant Transforms.

Para você conseguir os melhores resultados na anexação, o esquema usado para os dados anexados precisa ser o mesmo que aquele da tabela atual. Se o esquema dos dados anexados contiver uma coluna com o mesmo nome de uma coluna da tabela existente, será preciso que as duas colunas tenham o mesmo nome, tipo de dados e modo. Caso contrário, a ferramenta Variant Transforms retornará um erro.

É possível anexar dados que tenham um esquema diferente daquele da tabela atual adicionando as sinalizações --update_schema_on_append e --append. Todas as colunas novas dos dados anexados serão adicionadas ao esquema atual, e os valores das linhas do esquema atual nas colunas novas serão definidos como NULL. Da mesma forma, se o esquema atual tiver colunas que os dados anexados não contêm, os valores das linhas nas colunas dos dados anexados também serão NULL.

Como processar arquivos malformados

Existem várias opções para lidar com arquivos malformados ou incompatíveis. Antes de carregar arquivos VCF, você pode verificar se há arquivos incorretos e incompatíveis usando a ferramenta de pré-processamento de arquivos VCF.

Como processar incompatibilidade de campo

Ao carregar vários arquivos VCF, a ferramenta Variant Transforms mescla todos os campos INFO e HEADER para gerar um "cabeçalho representativo". Em seguida, esse cabeçalho é usado para criar o esquema do BigQuery. Se a mesma chave for definida em vários arquivos, a definição precisa ser compatível em todos os arquivos. As regras de compatibilidade são:

Os campos serão compatíveis se tiverem os mesmos valores nos campos Number e Type. Os campos de anotação, especificados com a sinalização --annotation_fields, precisam ter o mesmo valor no campo Description.
Os campos que contêm valores Type diferentes são compatíveis nos seguintes casos:
- Se os campos Integer e Float forem compatíveis e ambos usarem o tipo Float.
- Se você executar a ferramenta Variant Transforms com a sinalização --allow_incompatible_records, que resolve automaticamente conflitos entre campos incompatíveis, como String e Integer. Isso garante que tipos incompatíveis não sejam ignorados silenciosamente.
Os campos com valores diferentes no campo Number são compatíveis nos seguintes casos:
- Se os valores tiverem números "repetidos" compatíveis entre si, como:
  - Number=. (número desconhecido)
  - Qualquer Number maior que 1
  - Number=G (um valor por genótipo) e Number=R (um valor para cada alternativa e referência)
  - Number=A (um valor para cada alternativa), somente se a ferramenta for executada com --split_alternate_allele_info_fields definido como False.
- Se você executar a ferramenta Variant Transforms com a sinalização --allow_incompatible_records, que resolve automaticamente conflitos entre campos incompatíveis, como Number=1 e Number=.. Isso garante que tipos incompatíveis não sejam ignorados silenciosamente.

Como especificar um arquivo de cabeçalhos

Ao executar a ferramenta Variant Transforms, é possível transmitir a sinalização --representative_header_file com um arquivo de cabeçalhos usado para gerar o esquema do BigQuery. O arquivo especifica os cabeçalhos mesclados de todos os arquivos que estão sendo carregados.

A ferramenta Variant Transforms lê somente as informações de cabeçalho do arquivo e ignora os registros VCF. Isso significa que o arquivo pode ter apenas os campos de cabeçalho ou ser um arquivo VCF real.

Veja os benefícios de fornecer um arquivo de cabeçalhos:

O canal é executado mais rapidamente, em especial se você estiver carregando um número grande de arquivos. A ferramenta Variant Transforms usa o arquivo de cabeçalhos para gerar o esquema do BigQuery e ignora a etapa de mesclar cabeçalhos de arquivos. Isso é especialmente útil se todos os arquivos tiverem os mesmos cabeçalhos VCF.
Você pode fornecer definições para quaisquer campos de cabeçalho que estejam faltando.
Você pode resolver incompatibilidades de definição de campo nos arquivos.

Como inferir cabeçalhos

Ao executar a ferramenta Variant Transforms, é possível que haja campos sem definição ou talvez você queira que a ferramenta ignore as definições de cabeçalho que forem incompatíveis com os valores de campo. Nesse caso, pode ser útil que a ferramenta infira as definições de cabeçalho corretas para esses campos.

Passe a sinalização --infer_headers, e a ferramenta inferirá os valores TYPE e NUMBER para campos indefinidos. Ela inferirá os valores com base nos valores do campo de todos os arquivos VCF.

Transmitir essa sinalização também gera um cabeçalho representativo com definições inferidas e definições de cabeçalhos.

Como permitir registros incompatíveis

Os dois casos a seguir causam falhas na ferramenta Variant Transforms:

Se houver inconsistência entre uma definição de campo e os valores do campo
Se o campo tiver duas definições inconsistentes em dois arquivos VCF diferentes

Em ambos os casos, é possível transmitir a sinalização --allow_incompatible_records. Isso faz com que a ferramenta resolva automaticamente os conflitos nas definições de cabeçalho. A ferramenta também transmite valores de campo para corresponder ao esquema do BigQuery se houver inconsistência entre a definição e o valor de um campo (por exemplo, o valor de campo Integer será transmitido para String a fim de corresponder a um esquema de campo do tipo String).

Próximas etapas

Aprenda a executar a ferramenta de pré-processamento Variant Transforms para validar arquivos VCF.
Leia Como analisar variantes usando o BigQuery para analisar os dados que você carregou.
Saiba mais sobre o esquema de variantes do BigQuery.
Saiba mais sobre o upload de arquivos locais grandes em paralelo usando um upload composto paralelo.