vg
1.61.0
Os gráficos de variação fornecem uma codificação sucinta das sequências de muitos genomas. Um gráfico de variação (em particular como implementado em VG) é composto de:
Este modelo é semelhante aos gráficos de sequência que foram usados no alinhamento de montagem e sequência múltipla.
Os caminhos fornecem sistemas de coordenadas em relação aos genomas codificados no gráfico, permitindo que os mapeamentos estáveis sejam produzidos, mesmo que a estrutura do gráfico seja alterada. O modelo de gráfico de variação torna esse incorporação explícita e essencial. As ferramentas no VG mantêm os caminhos como imutáveis durante as transformações do gráfico. Eles usam caminhos para projetar dados-gráficos em espaços de coordenadas relativas de referência. Os caminhos fornecem coordenadas estáveis para gráficos construídos de maneira diferente das mesmas seqüências de entrada.
Cite:
vgvg giraffevg callvg deconstructvg snarlsvg haplotypes e/ou vg giraffe --haplotype-name Mantemos um fórum de suporte no BioStars: https://www.biostars.org/tag/vg/
A maneira mais fácil de obter o VG é baixar uma de nossas compilações de lançamento para o Linux. Temos uma cadência de lançamento de 6 semanas, portanto, nossas construções nunca estão muito desatualizadas.
Baixe o lançamento do VG mais recente para Linux
Para MacOS , consulte a construção no macOS.
Se você não deseja ou não pode usar uma liberação pré-construída de VG, ou se deseja se tornar um desenvolvedor de VG, poderá construí-lo a partir da fonte.
Primeiro, obtenha o repo e seus submódulos:
git clone --recursive https://github.com/vgteam/vg.git
cd vg
Em seguida, instale as dependências do VG. Você precisará das bibliotecas de desenvolvimento Protobuf e Jansson instaladas e para executar os testes necessários:
jq , bc , rs e parallelhexdump e column de bsdmainutilsnpm para exemplos de documentação de teste).No Ubuntu, você deve ser capaz de fazer:
make get-deps
Se você receber reclamações de que sudo não é encontrado, instale -o:
apt update
apt install sudo
Se você receber um monte de erros como E: Unable to locate package build-essential , verifique se os arquivos de índice de pacotes estão atualizados executando:
sudo apt update
Em outras distritos, ou se você não tiver acesso raiz, precisará executar o equivalente a:
sudo apt-get install build-essential git cmake pkg-config libncurses-dev libbz2-dev
protobuf-compiler libprotoc-dev libprotobuf-dev libjansson-dev
automake gettext autopoint libtool jq bsdmainutils bc rs parallel
npm curl unzip redland-utils librdf-dev bison flex gawk lzma-dev
liblzma-dev liblz4-dev libffi-dev libcairo-dev libboost-all-dev
libzstd-dev pybind11-dev python3-pybind11
Observe que o Ubuntu 16.04 não envia um protobuf suficientemente novo; O VG requer Protobuf 3 , que terá que ser instalado manualmente.
Atualmente, você precisará de GCC versão 4.9 ou superior, com suporte para C ++ 14, para compilar VG. (Verifique sua versão com gcc --version .) GCC até 11.2.0 é suportado.
Outras bibliotecas podem ser necessárias. Por favor, relate quaisquer dificuldades de construção.
Observe que é necessário um sistema operacional de 64 bits. O Ubuntu 20.04 deve funcionar.
Quando estiver pronto, construa com make . Você pode usar make -j16 para executar 16 threads de construção por vez, o que acelera bastante o processo. Se você possui mais núcleos de CPU, poderá usar números mais altos.
Observe que o VG pode levar de 10 minutos a mais de uma hora para compilar, dependendo da sua máquina e do número de threads usados.
Você também pode produzir um binário estático com make static , supondo que você tenha versões estáticas de todas as dependências instaladas no seu sistema.
Depois que o VG for construído, o binário estará no bin/vg dentro do diretório do repositório VG. Você pode executá -lo com:
./bin/vg
Você também pode adicionar seu diretório à sua variável de ambiente PATH , para que você possa invocar vg de qualquer diretório. Para fazer isso no Bash, use este comando do Diretório do Repositório VG:
echo 'export PATH="${PATH}:'"$(pwd)"'/bin"' >>~/.bashrc
Em seguida, feche seu terminal e abra um novo. Execute vg para garantir que funcionasse.
Se não funcionou, verifique se você tem um arquivo .bash_profile no seu diretório inicial que executará seu .bashrc :
if [ -f ~/.bashrc ]; then
source ~/.bashrc
fi
O primeiro passo é clonar o repositório VG:
git clone --recursive https://github.com/vgteam/vg.git
cd vg
O VG depende de vários pacotes instalados no sistema em que está sendo construído. As dependências podem ser instaladas usando Macports ou Homebrew.
Você pode usar o Macports para instalar as dependências do VG:
sudo port install libtool protobuf3-cpp jansson jq cmake pkgconfig autoconf automake libtool coreutils samtools redland bison gperftools md5sha1sum rasqal gmake autogen cairo libomp boost zstd pybind11
A Homebrew fornece outra solução de gerenciamento de pacotes para o OSX e pode ser preferível a alguns usuários do Macports. O VG envia um Brewfile descrevendo suas dependências de cervejas domésticas; portanto, do diretório raiz do VG, você pode instalar dependências e expô -las ao VG, assim:
# Install all the dependencies in the Brewfile
brew bundle
Com as dependências instaladas, o VG agora pode ser construído:
make
Como no Linux, você pode adicionar -j16 ou outros números no final para executar várias tarefas de construção de uma só vez, se o seu computador puder lidar com eles.
Observe que os binários estáticos ainda não podem ser construídos para Mac.
O VG Mac Build Targets, independentemente da versão atual do Apple Clang, e qualquer versão do Apple Clang é fornecida pelo nosso sistema Mac CI Action Actions. Se o seu clang estiver atualizado e o VG não for construído para você, abra um problema.
Depois que o VG for construído, o binário estará no bin/vg dentro do diretório do repositório VG. Você pode executá -lo com:
./bin/vg
Você também pode adicionar seu diretório à sua variável de ambiente PATH , para que você possa invocar vg de qualquer diretório. Para fazer isso no shell zsh MAC padrão, use este comando do diretório do repositório VG:
echo 'export PATH="${PATH}:'"$(pwd)"'/bin"' >>~/.zshrc
Em seguida, feche seu terminal e abra um novo. Execute vg para garantir que funcionasse.
A plataforma Mac está se movendo para o ARM, com os designs de chip M1, M1 Pro, M1 Max da Apple e Chip subsequentes. A base de código VG suporta o ARM no Mac e também no Linux. As instruções normais de instalação funcionam em um braço fresco de fábrica .
No entanto, é fácil ter problemas ao migrar um ambiente de construção de VG em funcionamento ou migrar Macports ou Homebrew de x86_64 para o ARM. A máquina de braço pode executar com sucesso as ferramentas x86_64 instaladas via Macports ou Homebrew na máquina antiga, mas o VG só pode ser construído corretamente no braço se você estiver usando versões do ARM das ferramentas de construção, como make e CMake.
Então, depois de migrar para um Mac do braço usando as ferramentas de migração da Apple:
make clean . Isso deve remover todos os artefatos de construção.make . Se você ainda tiver problemas de criação de problemas depois disso, exclua toda a finalização da compra e confira o código novamente; make clean não está no teste de IC e nem sempre está atualizado com o restante do sistema de construção.
Se isso ajuda ou não, abra um problema para que possamos ajudar a corrigir a construção ou consertar make clean .
Nota Consulte os exemplos
vg autoindexabaixo para usar essa ferramenta no lugar dovg constructpara criar e indexar gráficos em uma única etapa.
Uma maneira de criar um gráfico com vg é construct -lo a partir de chamadas variantes usando um arquivo fasta de referência e um arquivo vcf. Se você está trabalhando no test/ diretório da VG:
vg construct -r small/x.fa -v small/x.vcf.gz > x.vg Observe que, para criar um gráfico, é necessário um índice do arquivo VCF. O arquivo de índice VCF pode ser gerado usando o comando tabix fornecido pelo SAMTOOLS (por exemplo, tabix -p vcf x.vcf.gz na linha de comando).
Você também pode construir um gráfico (e índices para mapeamento com VG) a partir de um conjunto de montagens de genoma (fasta), em oposição às chamadas variantes, conforme descrito acima, usando o minigraff-cactus.
vg suporta muitos formatos, os três mais importantes são:
PackedGraph (.vg) : Este é o formato nativo vg's . Ele suporta edições de todos os tipos (para topologia e caminhos), mas pode ser ineficiente em grandes escalas, especialmente com muitos caminhos.GFA (.gfa) : GFA é um formato baseado em texto padrão e geralmente a melhor maneira de trocar gráficos entre vg e outras ferramentas do Pangenome. vg também pode operar diretamente em arquivos GFA ( não compactados ), por meio de usar uma representação PackedGraph na memória (e, portanto, compartilha as preocupações de escala e a capacidade de edição do formato).GBZ (.gbz) : GBZ é um formato altamente compactado que usa muito menos espaço para armazenar caminhos do que os formatos acima, mas com o custo de não permitir edições gerais ao gráfico. Você pode consultar o formato de qualquer gráfico usando vg stats -F .
Em geral, você construirá e indexará gráficos vg usando vg autoindex (de GFA ou VCF) ou Minigraph-Cactus (fastas). Você também pode importar arquivos GFA de outras ferramentas, como ODGI e PGGB usando vg convert -g .
Você pode converter qualquer gráfico em GFA usando vg convert -f . Por padrão, vg usa o GFA v1.1 onde os caminhos são representados como linhas W. Para usar as linhas P (GFA v1.0), use vg convert -fW .
O formato GBZ faz a distinção entre os caminhos REFERENCE e HAPLOTYPE . Os caminhos REFERENCE podem ser usados como sistemas de coordenadas, mas são mais caros para armazenar. Os caminhos HAPLOTYPE são altamente compactados, mas não podem ser usados para pesquisas de posição. Nos gráficos HPRC, por exemplo, os contigs de GRCh38 e CHM13(T2T) são caminhos REFERENCE e todos os outros caminhos de HAPLOTYPE de amostras.
A distinção entre os caminhos REFERENCE e HAPLOTYPE é transportada para os outros formatos, como .vg e .gfa para facilitar a conversão e a inter-operação. No .gfa , os caminhos REFERENCE são linhas P ou linhas W cujos nomes de amostra são sinalizados no cabeçalho. As linhas W cujos nomes não são sinalizados no cabeçalho são caminhos HAPLOTYPE . Em .vg eles são denotados usando uma convenção de nomenclatura.
Veja o Wiki de metadados do caminho para obter mais detalhes.
Aviso
GBZé o único formato que suporta carregamento eficiente de grandes números de caminhosHAPLOTYPEnovg. Você pode ter problemas tentando carregar gráficos de genoma inteiro com milhares deHAPLOTYPEde arquivos.vgou.gfa.vg convert -Hpode ser usado para soltar os caminhosHAPLOTYPE, permitindo que o gráfico seja mais facilmente carregado em outros formatos.
Observe que é melhor usar a ferramenta
vg convertmais recente (descrita acima) para conversão de GFA
vg view fornece uma maneira de converter o gráfico em vários formatos:
# GFA output
vg view x.vg > x.gfa
# dot output suitable for graphviz
vg view -d x.vg > x.dot
# And if you have a GAM file
cp small/x-s1337-n1.gam x.gam
# json version of binary alignments
vg view -a x.gam > x.jsonSe você tiver mais de uma sequência ou estiver trabalhando em um gráfico grande, desejará mapear em vez de apenas se alinhar.
Existem vários mapeadores de leitura em vg :
vg giraffe foi projetado para ser rápido para leituras curtas altamente precisas, contra gráficos com informações de haplótipo.vg map é um mapeador de leitura de uso geral.vg mpmap faz mapeamento "multi-path", para permitir a descrição da incerteza de alinhamento local. Isso é útil para transcriptômica. vg giraffe Para usar vg giraffe para mapear leituras, você precisará primeiro preparar índices. É melhor fazer isso usando vg autoindex . Para obter vg autoindex usar informações de haplótipo de um arquivo VCF, você pode fornecer o VCF e a referência linear associada diretamente.
# construct the graph and indexes (paths below assume running from `vg/test` directory)
vg autoindex --workflow giraffe -r small/x.fa -v small/x.vcf.gz -p x
# simulate a bunch of 150bp reads from the graph, into a GAM file of reads aligned to a graph
vg sim -n 1000 -l 150 -x x.giraffe.gbz -a > x.sim.gam
# now re-map these reads against the graph, and get BAM output in linear space
# FASTQ input uses -f instead of -G.
vg giraffe -Z x.giraffe.gbz -G x.sim.gam -o BAM > aln.bam Mais informações sobre o uso vg girafe podem ser encontradas no Wiki vg .
vg map Se o seu gráfico for grande, você deseja usar vg index para armazenar o gráfico e vg map para alinhar as leituras. vg map implementa um modelo de semente baseado em KMER e estenda de alinhamento semelhante ao usado em alinhadores como Novoalign ou Mosaik. Primeiro, um índice no disco é construído com vg index , que inclui o próprio gráfico e o KMERS de um tamanho específico. Ao mapear, qualquer tamanho de KMER mais curto do que o usado no índice pode ser empregado e, por padrão, o mapeador diminuirá o tamanho do KMER para aumentar a sensibilidade quando o alinhamento em um K específico falha.
# construct the graph (paths below assume running from `vg/test` directory)
vg construct -r small/x.fa -v small/x.vcf.gz > x.vg
# store the graph in the xg/gcsa index pair
vg index -x x.xg -g x.gcsa -k 16 x.vg
# align a read to the indexed version of the graph
# note that the graph file is not opened, but x.vg.index is assumed
vg map -s CTACTGACAGCAGAAGTTTGCTGTGAAGATTAAATTAGGTGATGCTTG -x x.xg -g x.gcsa > read.gam
# simulate a bunch of 150bp reads from the graph, one per line
vg sim -n 1000 -l 150 -x x.xg > x.sim.txt
# now map these reads against the graph to get a GAM
vg map -T x.sim.txt -x x.xg -g x.gcsa > aln.gam
# surject the alignments back into the reference space of sequence "x", yielding a BAM file
vg surject -x x.xg -b aln.gam > aln.bam
# or alternatively, surject them to BAM in the call to map
vg sim -n 1000 -l 150 -x x.xg > x.sim.txt
vg map -T x.sim.txt -x x.xg -g x.gcsa --surject-to bam > aln.bamA variação dos alinhamentos pode ser incorporada de volta ao gráfico. Esse processo é chamado de aumento e pode ser usado para chamadas de variantes de novo , por exemplo (veja abaixo).
O aviso usando
vg augmentpara chamadas variantes permanece muito experimental. Não é de todo recomendado para chamadas de variantes estruturais e, mesmo para pequenas variantes, você geralmente obtém resultados muito mais precisos (pelo menos no ser humano) projetando seu alinhamento aoBAMe executando um chamador de variante linear como o DeepVariant.
# augment the graph with all variation from the GAM except that implied by soft clips, saving to aug.vg. aug.gam contains the same reads as aln.gam but mapped to aug.vg
vg augment x.vg aln.gam -A aug.gam > aug.vg
# augment the graph with all variation from the GAM, saving each mapping as a path in the graph.
# softclips of alignment paths are preserved (`-S`).
# Note, this can be much less efficient than the above example if there are many alignments in the GAM
vg augment x.vg aln.gam -i -S > aug_with_paths.vgObserve mais informações podem ser encontradas no wiki.
Os exemplos a seguir mostram como gerar um VCF com VG usando o suporte de leitura. Eles dependem da saída dos exemplos de mapeamento e aumento acima. Pequenas variantes e SVs podem ser chamados usando a mesma abordagem. Atualmente, é mais precisão para SVS .
Ligue apenas variantes que estão presentes no gráfico:
# Compute the read support from the gam
# -Q 5: ignore mapping and base qualitiy < 5
vg pack -x x.xg -g aln.gam -Q 5 -o aln.pack
# Generate a VCF from the support.
vg call x.xg -k aln.pack > graph_calls.vcf Por padrão, vg call omite variantes 0/0 e tenta normalizar os alelos para tornar o VCF mais compacto. Ambas as etapas podem dificultar a comparação das saídas de diferentes amostras, pois os VCFs terão coordenadas diferentes, embora tenham sido criadas usando o mesmo gráfico. A opção -a aborda isso chamando todos os rosnados usando as mesmas coordenadas e incluindo chamadas de referência. As saídas para diferentes amostras podem ser combinadas com bcftools merge -m all .
vg call x.xg -k aln.pack -a > snarl_genotypes.vcf
Para considerar também novas variantes das leituras, use o gráfico aumentado e o GAM (como criado no exemplo de "aumento" usando vg augment -A ):
O aviso usando
vg augmentpara chamadas variantes permanece muito experimental. Não é de todo recomendado para chamadas de variantes estruturais e, mesmo para pequenas variantes, você geralmente obtém resultados muito mais precisos (pelo menos no ser humano) projetando seu alinhamento aoBAMe executando um chamador de variante linear como o DeepVariant.
# Index our augmented graph
vg index aug.vg -x aug.xg
# Compute the read support from the augmented gam (ignoring qualitiy < 5, and 1st and last 5bp of each read)
vg pack -x aug.xg -g aug.gam -Q 5 -s 5 -o aln_aug.pack
# Generate a VCF from the support
vg call aug.xg -k aln_aug.pack > calls.vcf Um processo semelhante pode por genotipar variantes conhecidas de um VCF. Para fazer isso, o gráfico deve ser construído a partir do VCF com vg construct -a (gráficos de outras fontes, como vg autoindex e Minigraph-Cactus não podem ser usados):
# Re-construct the same graph as before but with `-a`
vg construct -r small/x.fa -v small/x.vcf.gz -a > xa.vg
# Index the graph with `-L' to preserve alt paths in the xg
vg index xa.vg -x xa.xg -L
# Compute the support (we could also reuse aln.pack from above)
vg pack -x xa.xg -g aln.gam -o aln.pack
# Genotype the VCF (use -v)
vg call xa.xg -k aln.pack -v small/x.vcf.gz > genotypes.vcfA pré-filtragem do GAM antes do suporte à computação pode melhorar a precisão da chamada SNP:
# filter secondary and ambiguous read mappings out of the gam
vg filter aln.gam -r 0.90 -fu -m 1 -q 15 -D 999 -x x.xg > aln.filtered.gam
# then compute the support from aln.filtered.gam instead of aln.gam in above etc.
vg pack -x xa.xg -g aln.filtered.gam -o aln.pack
vg call xa.xg -k aln.pack -v small/x.vcf.gz > genotypes.vcfPara gráficos maiores, é recomendável calcular roscas separadamente:
vg snarls x.xg > x.snarls
# load snarls from a file instead of computing on the fly
vg call x.xg -k aln.pack -r x.snarls > calls.vcf NOTA: vg augment , vg pack , vg call e vg snarls agora podem ser executados diretamente em qualquer formato gráfico (ex '.gbz', '.gfa', .vg , .xg (exceto augment ) ou qualquer coisa em que vg convert ). Operar em .vg ou '.gfa' usa mais memória e não é recomendado para gráficos grandes. A saída do vg pack só pode ser lida em conjunto com o mesmo gráfico usado para criá -lo; portanto, vg pack x.vg -g aln.gam -o x.pack então vg call x.xg -k x.pack não funcionará .
Inferir variantes de alinhamentos implícitos por caminhos no gráfico. Isso pode ser usado, por exemplo, para chamar SVS diretamente de um gráfico de variação que foi construído a partir de um alinhamento múltiplo de diferentes montagens:
# create a graph from a multiple alignment of HLA haplotypes (from vg/test directory)
vg msga -f GRCh38_alts/FASTA/HLA/V-352962.fa -t 1 -k 16 | vg mod -U 10 - | vg mod -c - > hla.vg
# index it
vg index hla.vg -x hla.xg
# generate a VCF using gi|568815592:29791752-29792749 as the reference contig. The other paths will be considered as haploid samples
vg deconstruct hla.xg -e -p " gi|568815592:29791752-29792749 " > hla_variants.vcf Os caminhos de haplótipo da entrada de índices .gbz ou .gbwt podem ser considerados usando -z e `-g ', respectivamente.
Como na vg call , é melhor calcular os rosnados separadamente e passar com -r ao trabalhar com gráficos grandes.
vg possui várias ferramentas para suportar análises transcriptômicas com gráficos emendados (isto é, gráficos que anotaram junções de emenda adicionadas como bordas no gráfico). Essas bordas podem ser adicionadas em um gráfico existente usando vg rna . Em seguida, podemos executar o mapeamento com reconhecimento de emenda nesses gráficos usando vg mpmap . Os desenvolvedores vg também fizeram uma ferramenta para quantificação de transcrição com reconhecimento de haplótipo com base nessas ferramentas no rpvg . A maneira mais fácil de iniciar esse pipeline é usar o subcomando vg autoindex para criar índices para vg mpmap . vg autoindex cria índices para o mapeamento de formatos de intercâmbio comuns como FASTA, VCF e GTF.
Mais informações estão disponíveis na página wiki sobre transcriptômica.
Trabalhando no test/ diretório O exemplo a seguir mostra como criar um gráfico e índices de pangenoma emendados usando vg autoindex com 4 threads:
# Create spliced pangenome graph and indexes for vg mpmap
vg autoindex --workflow mpmap -t 4 --prefix vg_rna --ref-fasta small/x.fa --vcf small/x.vcf.gz --tx-gff small/x.gtf As leituras de RNA-seq podem ser mapeadas para o gráfico de pangenoma emendado usando vg mpmap com 4 threads:
# Map simulated RNA-seq reads using vg mpmap
vg mpmap -n rna -t 4 -x vg_rna.spliced.xg -g vg_rna.spliced.gcsa -d vg_rna.spliced.dist -f small/x_rna_1.fq -f small/x_rna_2.fq > mpmap.gamp Isso produzirá alinhamentos no formato de múltipla. Para obter mais informações sobre o formato de alinhamento de múltiplas e vg mpmap consulte a página wiki no MPMAP. A execução dos dois comandos nos pequenos dados de exemplo usando 4 threads deve na maioria das máquinas levar menos de um minuto.
Se você tiver um gráfico pequeno, pode alinhar uma sequência a todo o gráfico, usando um alinhamento de pedidos parciais de comprimento completo:
vg align -s CTACTGACAGCAGAAGTTTGCTGTGAAGATTAAATTAGGTGATGCTTG x.vgObserve que você não precisa armazenar o gráfico no disco, você pode simplesmente colocá -lo no alinhador local:
vg construct -r small/x.fa -v small/x.vcf.gz | vg align -s CTACTGACAGCAGAAGTTTGCTGTGAAGATTAAATTAGGTGATGCTTG - A maioria dos comandos permite que o streaming de gráficos dentro e fora do vg .
Uma variedade de comandos está disponível:
vg é uma coleção de ferramentas baseadas em um modelo de dados comum (o gráfico de variação) descrito por um esquema Protobuf (vg.proto). Os objetos de dados definidos no VG.proto podem ser serializados por meio de um padrão de fluxo definido no stream.hpp. Não é necessário escrever código no VG para interagir com os algoritmos definidos aqui. Em vez disso, às vezes é mais simples escrever um algoritmo externo que lê e grava os mesmos formatos de dados.
Mit
