vg
1.61.0
Los gráficos de variación proporcionan una codificación sucinta de las secuencias de muchos genomas. Se compone un gráfico de variación (en particular como se implementa en VG) de:
Este modelo es similar a los gráficos de secuencia que se han utilizado en el ensamblaje y la alineación de secuencias múltiples.
Las rutas proporcionan sistemas de coordenadas en relación con los genomas codificados en el gráfico, lo que permite que se produzcan mapeos estables incluso si se cambia la estructura del gráfico. El modelo de gráfico de variación hace que esta incrustación sea explícita y esencial. Las herramientas en VG mantienen las rutas como inmutables durante las transformaciones del gráfico. Utilizan rutas para proyectar datos relativos de gráficos en espacios de coordenadas relacionadas con la referencia. Las rutas proporcionan coordenadas estables para gráficos construidos de diferentes maneras desde las mismas secuencias de entrada.
Por favor cita:
vgvg giraffevg callvg deconstructvg snarlsvg haplotypes y/o vg giraffe --haplotype-name Mantenemos un foro de apoyo sobre Biostars: https://www.biostars.org/tag/vg/
La forma más fácil de obtener VG es descargar una de nuestras compilaciones de lanzamiento para Linux. Tenemos una cadencia de lanzamiento de 6 semanas, por lo que nuestras construcciones nunca están demasiado desactualizadas.
Descargue la última versión de VG para Linux
Para MacOS , ver edificio sobre macOS.
Si no desea o no puede usar una versión preconstruida de VG, o si desea convertirse en un desarrollador de VG, puede construirla desde la fuente.
Primero, obtenga el repositorio y sus submódulos:
git clone --recursive https://github.com/vgteam/vg.git
cd vg
Luego, instale las dependencias de VG. Necesitará las bibliotecas de desarrollo ProtoBuf y Jansson instaladas, y para ejecutar las pruebas que necesitará:
jq , bc , rs y parallelhexdump y column de bsdmainutilsnpm para probar ejemplos de documentación).En Ubuntu, deberías poder hacer:
make get-deps
Si recibe quejas de que no se encuentra sudo , instálelo:
apt update
apt install sudo
Si obtiene un montón de errores como E: Unable to locate package build-essential , asegúrese de que los archivos de índice de paquetes estén actualizados ejecutándose:
sudo apt update
En otras distribuciones, o si no tiene acceso a la raíz, deberá realizar el equivalente de:
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
Tenga en cuenta que Ubuntu 16.04 no envía un protobuf suficientemente nuevo; VG requiere ProtoBuf 3 que tendrá que instalarse manualmente.
En la actualidad, necesitará GCC versión 4.9 o más, con soporte para C ++ 14, para compilar VG. (Consulte su versión con gcc --version ). Se admite GCC hasta 11.2.0.
Se pueden requerir otras bibliotecas. Informe cualquier dificultad de compilación.
Tenga en cuenta que se requiere un sistema operativo de 64 bits. Ubuntu 20.04 debería funcionar.
Cuando estés listo, construya con make . Puede usar make -j16 para ejecutar 16 hilos de compilación a la vez, lo que acelera en gran medida el proceso. Si tiene más núcleos de CPU, puede usar números más altos.
Tenga en cuenta que VG puede tomar de 10 minutos a más de una hora para compilar dependiendo de su máquina y la cantidad de hilos utilizados.
También puede producir un binario estático con make static , suponiendo que tenga versiones estáticas de todas las dependencias instaladas en su sistema.
Una vez que se construye VG, el binario estará en bin/vg dentro del directorio de repositorio de VG. Puedes ejecutarlo con:
./bin/vg
También puede agregar su directorio a su variable de envío PATH , para que pueda invocar vg desde cualquier directorio. Para hacer eso en Bash, use este comando del directorio de repositorio de VG:
echo 'export PATH="${PATH}:'"$(pwd)"'/bin"' >>~/.bashrc
Luego cierre su terminal y abra una nueva. Ejecute vg para asegurarse de que funcionara.
Si no funcionó, asegúrese de tener un archivo .bash_profile en su directorio de inicio que ejecutará su .bashrc :
if [ -f ~/.bashrc ]; then
source ~/.bashrc
fi
El primer paso es clonar el repositorio de VG:
git clone --recursive https://github.com/vgteam/vg.git
cd vg
VG depende de una serie de paquetes que se están instalando en el sistema donde se está construyendo. Las dependencias se pueden instalar utilizando MacPorts o Homebrew.
Puede usar MacPorts para instalar las dependencias de 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
HomeBrew proporciona otra solución de gestión de paquetes para OSX, y puede ser preferible para algunos usuarios a través de MacPorts. VG envía un Brewfile que describe sus dependencias caseras, por lo que desde el directorio root VG, puede instalar dependencias y exponerlas a VG, así: así:
# Install all the dependencies in the Brewfile
brew bundle
Con las dependencias instaladas, ahora se puede construir VG:
make
Al igual que con Linux, puede agregar -j16 u otros números al final para ejecutar múltiples tareas de compilación a la vez, si su computadora puede manejarlos.
Tenga en cuenta que los binarios estáticos aún no se pueden construir para Mac.
La construcción de VG Mac se dirige a cualquier versión actual de Apple Clang, y cualquier versión de Apple Clang proporciona nuestro sistema GitHub Actions Mac CI. Si su rango está actualizado y VG no se construye para usted, abra un problema.
Una vez que se construye VG, el binario estará en bin/vg dentro del directorio de repositorio de VG. Puedes ejecutarlo con:
./bin/vg
También puede agregar su directorio a su variable de envío PATH , para que pueda invocar vg desde cualquier directorio. Para hacer eso en el shell zsh Mac predeterminado, use este comando en el directorio de repositorio de VG:
echo 'export PATH="${PATH}:'"$(pwd)"'/bin"' >>~/.zshrc
Luego cierre su terminal y abra una nueva. Ejecute vg para asegurarse de que funcionara.
La plataforma Mac se está moviendo al brazo, con los diseños de chips M1, M1 Pro, M1 Max y posteriores de Apple M1, M1 Pro, M1 y posteriores. El VG CodeBase admite ARM en Mac y en Linux. Las instrucciones de instalación normales funcionan en un brazo de fábrica Mac .
Sin embargo, es fácil tener problemas al migrar un entorno de construcción de VG en funcionamiento o migrar MacPorts o Homebrew desde X86_64 hasta ARM. La máquina del brazo puede ejecutar con éxito las herramientas X86_64 instaladas a través de MacPorts o Homebrew en la máquina anterior, pero VG solo puede construir correctamente en el brazo si está utilizando versiones de ARM de las herramientas de compilación, como make y CMake.
Entonces, después de migrar a un Mac de brazo usando las herramientas de migración de por ejemplo, Apple:
make clean . Esto debería eliminar todos los artefactos de construcción.make . Si aún experimenta problemas de compilación después de esto, elimine el pago completo y consulte el código nuevamente; make clean no está bajo la prueba de CI y no siempre está actualizado con el resto del sistema de compilación.
Ya sea que eso ayude o no, por favor, abra un problema para que podamos ayudar a arreglar la compilación o la make clean .
Nota Consulte los ejemplos
vg autoindexa continuación sobre cómo usar esa herramienta en lugar devg constructpara construir e indexar gráficos en un solo paso.
Una forma de crear un gráfico con vg es construct a partir de llamadas de variantes utilizando un archivo FASTA de referencia y un archivo VCF. Si está trabajando en test/ directorio de VG:
vg construct -r small/x.fa -v small/x.vcf.gz > x.vg Tenga en cuenta que para crear un gráfico, se requiere un índice del archivo VCF. El archivo de índice VCF se puede generar utilizando el comando tabix proporcionado por SamTools ( tabix -p vcf x.vcf.gz . Ej.
También puede construir un gráfico (e índices para mapear con VG) a partir de un conjunto de conjuntos de genoma (FASTA), en lugar de las llamadas variantes como se describió anteriormente, utilizando Minigraph-Cactus.
vg admite muchos formatos, los tres más importantes son:
PackedGraph (.vg) : este es el formato nativo vg's . Admite ediciones de todo tipo (a la topología y las rutas), pero puede ser ineficiente a grandes escalas, especialmente con muchos caminos.GFA (.gfa) : GFA es un formato estándar basado en texto y, por lo general, la mejor manera de intercambiar gráficos entre vg y otras herramientas Pangenome. vg también puede operar en archivos GFA ( sin comprimir ) directamente, mediante el uso de una representación PackedGraph en la memoria (y por lo tanto comparte las preocupaciones de escala y la capacidad de edición del formato).GBZ (.gbz) : GBZ es un formato altamente comprimido que utiliza mucho menos espacio para almacenar rutas que los formatos anteriores, pero a costa de no permitir ediciones generales al gráfico. Puede consultar el formato de cualquier gráfico utilizando vg stats -F .
En general, construirá e indexará gráficos vg usando vg autoindex (de GFA o VCF) o Minigraph-Cactus (FASTAS). También puede importar archivos GFA de otras herramientas como ODGI y PGGB usando vg convert -g .
Puede convertir cualquier gráfico a GFA usando vg convert -f . Por defecto, vg usa GFA V1.1 donde las rutas se representan como W-Lines. Para usar las líneas P (GFA V1.0), use vg convert -fW .
El formato GBZ hace la distinción entre rutas REFERENCE y HAPLOTYPE . Las rutas REFERENCE se pueden usar como sistemas de coordenadas, pero son más caras de almacenar. Las rutas HAPLOTYPE están altamente comprimidas pero no se pueden usar para las búsquedas de posición. En los gráficos HPRC, por ejemplo, los contigs de GRCh38 y CHM13(T2T) son rutas REFERENCE y todas las demás rutas HAPLOTYPE de muestras.
La distinción entre rutas REFERENCE y HAPLOTYPE se transfiere a los otros formatos como .vg y .gfa para facilitar la conversión e interoperación. En .gfa , las rutas REFERENCE son líneas P o líneas W cuyos nombres de muestra se marcan en el encabezado. Las líneas W cuyos nombres no están marcados en el encabezado son rutas HAPLOTYPE . En .vg se denotan usando una convención de nombres.
Vea la wiki de metadatos de ruta para obtener más detalles.
Advertencia
GBZes el único formato que admite una carga eficiente de grandes cantidades de rutasHAPLOTYPEenvg. Puede encontrar problemas que intentan cargar gráficos de genoma completo con miles deHAPLOTYPEde archivos.vgo.gfa.vg convert -Hse puede usar para soltar rutasHAPLOTYPE, lo que permite que el gráfico se cargue más fácilmente en otros formatos.
Tenga en cuenta que es mejor usar la herramienta
vg convertmás nueva (descrita anteriormente) para la conversión de GFA
vg view proporciona una forma de convertir el gráfico en varios 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.jsonSi tiene más de una secuencia, o está trabajando en un gráfico grande, querrá mapear en lugar de simplemente alinearse.
Hay múltiples mapeadores de lectura en vg :
vg giraffe está diseñada para ser rápida para lecturas cortas altamente precisas, contra gráficos con información de haplotipo.vg map es un mapeador de lectura de uso general.vg mpmap realiza mapeo "múltiple", para permitir la descripción de la incertidumbre de alineación local. Esto es útil para la transcriptómica. vg giraffe Para usar vg giraffe para mapear las lecturas, primero deberá preparar índices. Esto se hace mejor utilizando vg autoindex . Para que vg autoindex use información de haplotipo de un archivo VCF, puede darle el VCF y la referencia lineal asociada directamente.
# 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 Puede encontrar más información sobre el uso de vg girafe en el vg Wiki.
vg map Si su gráfico es grande, desea usar vg index para almacenar el gráfico y vg map para alinear las lecturas. vg map implementa una semilla basada en KMER y extender el modelo de alineación que es similar al utilizado en alineadores como novoalign o mosaik. Primero, se construye un índice en disco con vg index que incluye el gráfico en sí y los kmers de un tamaño particular. Al mapear, se puede emplear cualquier tamaño de kmer más corto que el utilizado en el índice, y por defecto el mapeador disminuirá el tamaño de KMER para aumentar la sensibilidad cuando la alineación en una K en particular falla.
# 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.bamLa variación de las alineaciones se puede incrustar nuevamente en el gráfico. Este proceso se llama aumento y puede usarse para la llamada de variante de novo , por ejemplo (ver más abajo).
La advertencia que usa
vg augmentpara llamadas de variante sigue siendo muy experimental. No se recomienda en absoluto para las llamadas de variantes estructurales, e incluso para pequeñas variantes, a menudo obtendrá resultados mucho más precisos (al menos en humanos) proyectando su alineación conBAMy ejecutando una persona que llama lineal como 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.vgNota Se puede encontrar más información en el wiki.
Los siguientes ejemplos muestran cómo generar un VCF con VG usando el soporte de lectura. Dependen de la salida de los ejemplos de mapeo y aumento anteriores. Se pueden llamar pequeñas variantes y SVS utilizando el mismo enfoque. Actualmente, es más preculso para SVS .
Llame solo a las variantes que están presentes en el 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 defecto, vg call omite las variantes 0/0 e intenta normalizar los alelos para que el VCF sea más compacto. Ambos pasos pueden dificultar la comparación de las salidas de diferentes muestras, ya que el VCFS tendrá diferentes coordenadas a pesar de que se crearon utilizando el mismo gráfico. La opción -a aborda esto llamando a cada SNARL usando las mismas coordenadas e incluyendo llamadas de referencia. Las salidas para diferentes muestras se pueden combinar con bcftools merge -m all .
vg call x.xg -k aln.pack -a > snarl_genotypes.vcf
Para considerar también nuevas variantes de las lecturas, use el gráfico aumentado y el GAM (como se creó en el ejemplo "Aumento" usando vg augment -A ):
La advertencia que usa
vg augmentpara llamadas de variante sigue siendo muy experimental. No se recomienda en absoluto para las llamadas de variantes estructurales, e incluso para pequeñas variantes, a menudo obtendrá resultados mucho más precisos (al menos en humanos) proyectando su alineación conBAMy ejecutando una persona que llama lineal como 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 Un proceso similar puede usarse al genotipo de variantes conocidas de un VCF. Para hacer esto, el gráfico debe construirse a partir del VCF con vg construct -a (no se pueden usar gráficos de otras fuentes como vg autoindex y Minigraph-Cactus )::
# 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.vcfPre-filtrado el GAM antes del soporte informático puede mejorar la precisión de las llamadas 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 más grandes, se recomienda calcular los gruñidos por separado:
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 y vg snarls ahora se pueden ejecutar directamente en cualquier formato de gráfico (ex '.Gbz', '.Gfa', .vg , .xg (excepto augment ) o cualquier cosa que salga por vg convert ). Operar en .vg o '.GFA' utiliza la mayor cantidad de memoria y no se recomienda para gráficos grandes. La salida del vg pack solo se puede leer junto con el mismo gráfico utilizado para crearlo, por lo que vg pack x.vg -g aln.gam -o x.pack luego vg call x.xg -k x.pack no funcionará .
Inferir variantes de las alineaciones implicadas por rutas en el gráfico. Esto se puede usar, por ejemplo, para llamar a SVS directamente desde un gráfico de variación que se construyó a partir de una alineación múltiple de diferentes ensamblados:
# 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 Las rutas de haplotipo de la entrada de índices .gbz o .gbwt se pueden considerar usando -z y `-g ', respectivamente.
Al igual que con vg call , es mejor calcular los gruñidos por separado y pasarlos con -r cuando se trabaja con gráficos grandes.
vg tiene una serie de herramientas para admitir análisis transcriptómicos con gráficos empalmados (es decir, gráficos que han anotado las uniones de empalme agregadas como bordes en el gráfico). Estos bordes se pueden agregar a un gráfico existente usando vg rna . Luego podemos realizar la asignación de empalme a estos gráficos usando vg mpmap . Los desarrolladores vg también han hecho una herramienta para la cuantificación de la transcripción de haplotipo basada en estas herramientas en rpvg . La forma más fácil de iniciar esta tubería es usar el subcomando vg autoindex para hacer índices para vg mpmap . vg autoindex crea índices para el mapeo de formatos de intercambio comunes como FASTA, VCF y GTF.
Hay más información disponible en la página Wiki sobre Transcriptomics.
Trabajar desde la test/ directorio El siguiente ejemplo muestra cómo crear un gráfico de pangenoma empalmado e índices utilizando vg autoindex con 4 subprocesos:
# 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 Las lecturas de RNA-seq se pueden asignar al gráfico de pangenoma empalmado usando vg mpmap con 4 hilos:
# 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 Esto producirá alineaciones en el formato multipath. Para obtener más información sobre el formato de alineación de múltiples horas y vg mpmap consulte la página Wiki en MPMAP. Ejecutar los dos comandos en los datos de ejemplo pequeños que usan 4 hilos en la mayoría de las máquinas deben tomar menos de un minuto.
Si tiene un gráfico pequeño, puede alinear una secuencia con todo el gráfico, utilizando una alineación de orden parcial de longitud completa:
vg align -s CTACTGACAGCAGAAGTTTGCTGTGAAGATTAAATTAGGTGATGCTTG x.vgTenga en cuenta que no tiene que almacenar el gráfico en el disco, simplemente puede meterlo en el alineador local:
vg construct -r small/x.fa -v small/x.vcf.gz | vg align -s CTACTGACAGCAGAAGTTTGCTGTGAAGATTAAATTAGGTGATGCTTG - La mayoría de los comandos permiten la transmisión de gráficos dentro y fuera de vg .
Hay una variedad de comandos disponibles:
vg es una colección de herramientas basada en un modelo de datos común (el gráfico de variación) que se describe por un esquema de ProtoBuf (vg.proto). Los objetos de datos definidos en VG.Proto pueden ser serializados a través de un patrón de secuencia definido en Stream.hpp. No es necesario escribir código en VG para interactuar con los algoritmos definidos aquí. Más bien, a veces es más simple escribir un algoritmo externo que lea y escriba los mismos formatos de datos.
MIT
