vg
1.61.0
Les graphiques de variation fournissent un codage succinct des séquences de nombreux génomes. Un graphique de variation (en particulier comme implémenté dans VG) est composé de:
Ce modèle est similaire aux graphiques de séquence qui ont été utilisés dans l'assemblage et l'alignement de séquence multiples.
Les chemins fournissent des systèmes de coordonnées par rapport aux génomes codés dans le graphique, ce qui permet de produire des mappages stables même si la structure du graphique est modifiée. Le modèle de graphique de variation rend cette intégration explicite et essentielle. Les outils en VG maintiennent les chemins comme immuables lors des transformations du graphique. Ils utilisent des chemins pour projeter des données relatives aux graphiques dans les espaces de coordonnées relatives à la référence. Les chemins fournissent des coordonnées stables pour les graphiques construits de différentes manières des mêmes séquences d'entrée.
Veuillez citer:
vgvg giraffevg callvg deconstructvg snarlsvg haplotypes et / ou vg giraffe --haplotype-name Nous maintenons un forum de support sur les biostars: https://www.biostars.org/tag/vg/
La façon la plus simple d'obtenir VG est de télécharger l'une de nos versions de version pour Linux. Nous avons une cadence de libération de 6 semaines, donc nos builds ne sont jamais trop loin.
Téléchargez la dernière version VG pour Linux
Pour macOS , voir la construction sur macOS.
Si vous ne voulez pas ou ne pouvez pas utiliser une version prédéfinie de VG, ou si vous souhaitez devenir un développeur VG, vous pouvez le construire à partir de Source à la place.
Premièrement, obtenez le repo et ses sous-modules:
git clone --recursive https://github.com/vgteam/vg.git
cd vg
Ensuite, installez les dépendances de VG. Vous aurez besoin des bibliothèques de développement Protobuf et Jansson installées et pour exécuter les tests dont vous aurez besoin:
jq , bc , rs et parallelhexdump et column de bsdmainutilsnpm pour tester des exemples de documentation).Sur Ubuntu, vous devriez pouvoir faire:
make get-deps
Si vous obtenez des plaintes selon lesquelles sudo n'est pas trouvé, installez-le:
apt update
apt install sudo
Si vous obtenez un tas d'erreurs comme E: Unable to locate package build-essential , assurez-vous que vos fichiers d'index de package sont à jour en exécutant:
sudo apt update
Sur d'autres distros, ou si vous n'avez pas d'accès root, vous devrez effectuer l'équivalent 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
Notez que Ubuntu 16.04 n'en est pas livré un protobuf suffisamment nouveau; VG nécessite Protobuf 3 qui devra être installé manuellement.
À l'heure actuelle, vous aurez besoin de GCC version 4.9 ou plus, avec le support pour C ++ 14, pour compiler VG. (Vérifiez votre version avec gcc --version .) GCC jusqu'à 11.2.0 est pris en charge.
D'autres bibliothèques peuvent être nécessaires. Veuillez signaler toute difficulté de construction.
Notez qu'un système d'exploitation 64 bits est requis. Ubuntu 20.04 devrait fonctionner.
Lorsque vous êtes prêt, construisez avec make . Vous pouvez utiliser make -j16 pour exécuter 16 threads de construction à la fois, ce qui accélère considérablement le processus. Si vous avez plus de cœurs CPU, vous pouvez utiliser des nombres plus élevés.
Notez que VG peut prendre de 10 minutes à plus d'une heure à compiler en fonction de votre machine et du nombre de threads utilisés.
Vous pouvez également produire un binaire statique avec make static , en supposant que vous avez des versions statiques de toutes les dépendances installées sur votre système.
Une fois VG construit, le binaire sera à bin/vg à l'intérieur du répertoire du référentiel VG. Vous pouvez l'exécuter avec:
./bin/vg
Vous pouvez également ajouter son répertoire à votre variable d'environnement PATH , afin que vous puissiez invoquer vg de n'importe quel répertoire. Pour ce faire sur Bash, utilisez cette commande à partir du répertoire du référentiel VG:
echo 'export PATH="${PATH}:'"$(pwd)"'/bin"' >>~/.bashrc
Fermez ensuite votre terminal et ouvrez un nouveau. Exécutez vg pour vous assurer que cela a fonctionné.
Si cela ne fonctionnait pas, assurez-vous d'avoir un fichier .bash_profile dans votre répertoire domestique qui exécutera votre .bashrc :
if [ -f ~/.bashrc ]; then
source ~/.bashrc
fi
La première étape consiste à cloner le référentiel VG:
git clone --recursive https://github.com/vgteam/vg.git
cd vg
VG dépend d'un certain nombre de packages installés sur le système où il est en cours de construction. Les dépendances peuvent être installées à l'aide de Macport ou de Homebrew.
Vous pouvez utiliser Macports pour installer les dépendances 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 fournit une autre solution de gestion des packages pour OSX et peut être préférable à certains utilisateurs de Macports. VG expédie un Brewfile décrivant ses dépendances de homebrew, donc à partir du répertoire Root VG, vous pouvez installer des dépendances et les exposer à VG, comme ceci:
# Install all the dependencies in the Brewfile
brew bundle
Avec les dépendances installées, VG peut maintenant être construit:
make
Comme pour Linux, vous pouvez ajouter -j16 ou d'autres numéros à la fin pour exécuter plusieurs tâches de construction à la fois, si votre ordinateur peut les gérer.
Notez que les binaires statiques ne peuvent pas encore être construits pour Mac.
Le VG Mac Build cible quelle que soit la version actuelle d'Apple Clang, et quelle que soit la version d'Apple Clang fournie par notre système GitHub Actions Mac CI. Si votre clang est à jour et que VG ne construit pas pour vous, veuillez ouvrir un problème.
Une fois VG construit, le binaire sera à bin/vg à l'intérieur du répertoire du référentiel VG. Vous pouvez l'exécuter avec:
./bin/vg
Vous pouvez également ajouter son répertoire à votre variable d'environnement PATH , afin que vous puissiez invoquer vg de n'importe quel répertoire. Pour ce faire sur le shell zsh Mac par défaut, utilisez cette commande à partir du répertoire du référentiel VG:
echo 'export PATH="${PATH}:'"$(pwd)"'/bin"' >>~/.zshrc
Fermez ensuite votre terminal et ouvrez un nouveau. Exécutez vg pour vous assurer que cela a fonctionné.
La plate-forme Mac se déplace vers le bras, avec les conceptions de puces M1, M1 Pro, M1 Max d'Apple et M1. La base de code VG prend en charge le bras sur Mac ainsi que sur Linux. Les instructions d'installation normales fonctionnent sur un Mac de bras frais d'usine .
Cependant, il est facile de rencontrer des problèmes lors de la migration d'un environnement de construction VG fonctionnelle ou de la migration de Macports ou de Homebrew de x86_64 à ARM. La machine ARM peut exécuter avec succès des outils x86_64 installés via Macport ou Homebrew sur l'ancienne machine, mais VG ne peut construire correctement sur ARM si vous utilisez des versions ARM des outils de construction, comme make et Cmake.
Ainsi, après avoir migré vers un Mac ARM en utilisant par exemple les outils de migration d'Apple:
make clean . Cela devrait supprimer tous les artefacts de construction.make . Si vous rencontrez toujours des problèmes de création après cela, supprimez l'ensemble du paiement et vérifiez à nouveau le code; make clean n'est pas sous le test CI et n'est pas toujours à jour avec le reste du système de construction.
Que cela aide ou non, veuillez ouvrir un problème afin que nous puissions aider à corriger la construction ou à corriger make clean .
Remarque Voir les exemples
vg autoindexci-dessous pour utiliser cet outil à la place devg constructpour construire et index des graphiques en une seule étape.
Une façon de créer un graphique avec vg est de la construct à partir d'appels variants à l'aide d'un fichier FastA de référence et d'un fichier VCF. Si vous travaillez dans test/ répertoire de VG:
vg construct -r small/x.fa -v small/x.vcf.gz > x.vg Notez que pour créer un graphique, un index du fichier VCF est requis. Le fichier d'index VCF peut être généré à l'aide de la commande tabix fournie par SAMTools (par exemple, tabix -p vcf x.vcf.gz sur la ligne de commande).
Vous pouvez également construire un graphique (et des index pour la cartographie avec VG) à partir d'un ensemble d'assemblages du génome (FASTA), par opposition aux appels variants comme décrit ci-dessus, en utilisant Minigraph-Cactus.
vg prend en charge de nombreux formats, les trois les plus importants sont:
PackedGraph (.vg) : Il s'agit du format natif vg's . Il prend en charge les modifications de toutes sortes (à la topologie et aux chemins), mais peut être inefficace à grande échelle, en particulier avec de nombreux chemins.GFA (.gfa) : GFA est un format de texte standard et généralement la meilleure façon d'échanger des graphiques entre vg et d'autres outils de Pangenome. vg peut également fonctionner directement sur des fichiers GFA ( non compressés ), en utilisant une représentation PackedGraph en mémoire (et partage donc les préoccupations de mise à l'échelle de ce format et la modification).GBZ (.gbz) : GBZ est un format hautement compressé qui utilise beaucoup moins d'espace pour stocker les chemins que les formats ci-dessus, mais au prix de ne pas autoriser les modifications générales au graphique. Vous pouvez interroger le format de tout graphique à l'aide de vg stats -F .
En général, vous construirez et indexrez des graphiques vg à l'aide de vg autoindex (à partir de GFA ou VCF) ou Minigraph-Cactus (Fastas). Vous pouvez également importer des fichiers GFA à partir d'autres outils tels que ODGI et PGGB à l'aide de vg convert -g .
Vous pouvez convertir n'importe quel graphique en GFA à l'aide de vg convert -f . Par défaut, vg utilise GFA v1.1 où les chemins sont représentés comme W-lines. Pour utiliser les lines P à la place (GFA V1.0), utilisez vg convert -fW .
Le format GBZ fait la distinction entre les chemins REFERENCE et HAPLOTYPE . Les chemins REFERENCE peuvent être utilisés comme systèmes de coordonnées mais sont plus chers à stocker. Les chemins HAPLOTYPE sont très compressés mais ne peuvent pas être utilisés pour les recherches de position. Dans les graphiques HPRC, par exemple, les contigs de GRCh38 et CHM13(T2T) sont des chemins REFERENCE et tous les autres chemins HAPLOTYPE d'échantillons.
La distinction entre les chemins REFERENCE et HAPLOTYPE est reportée dans les autres formats tels que .vg et .gfa pour faciliter la conversion et l'interopération. Dans .gfa , les chemins REFERENCE sont des lines P ou des lines W dont les noms d'échantillons sont signalés dans l'en-tête. Les lignées W dont les noms ne sont pas signalées dans l'en-tête sont des chemins HAPLOTYPE . Dans .vg ils sont désignés par une convention de dénomination.
Voir le wiki des métadonnées PATH pour plus de détails.
AVERTISSEMENT
GBZest le seul format qui prend en charge un chargement efficace de grands nombres de cheminsHAPLOTYPEdansvg. Vous pouvez rencontrer des problèmes en essayant de charger des graphiques du génome entier avec des milliers d'HAPLOTYPEà partir de fichiers.vgou.gfa.vg convert -Hpeut être utilisé pour supprimer les cheminsHAPLOTYPE, permettant au graphique d'être plus facilement chargé dans d'autres formats.
Remarque Il est préférable d'utiliser le plus récent outil
vg convert(décrit ci-dessus) pour la conversion GFA
vg view fournit un moyen de convertir le graphique en différents formats:
# 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 vous avez plus d'une séquence ou si vous travaillez sur un grand graphique, vous voudrez mapper plutôt que de simplement vous aligner.
Il y a plusieurs mappeurs de lecture dans vg :
vg giraffe est conçu pour être rapide pour des lectures courtes très précises, contre des graphiques avec des informations d'haplotype.vg map est un mappeur à lecture générale.vg mpmap fait la cartographie "multi-chemies", pour permettre la décoration de l'incertitude de l'alignement local. Ceci est utile pour la transcriptomique. vg giraffe Pour utiliser vg giraffe pour cartographier les lectures, vous devrez d'abord préparer des index. Il est préférable de le faire à l'aide de vg autoindex . Afin d'amener vg autoindex à utiliser des informations d'haplotype à partir d'un fichier VCF, vous pouvez lui donner directement le VCF et la référence linéaire associée.
# 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 Plus d'informations sur l'utilisation vg girafe peuvent être trouvées sur le Wiki vg .
vg map Si votre graphique est grand, vous souhaitez utiliser vg index pour stocker la vg map pour aligner les lectures. vg map met en œuvre un modèle d'alignement à base de KMER et étendant qui est similaire à celui utilisé dans les aligneurs comme Novoalign ou Mosaik. Tout d'abord, un index sur le disque est construit avec vg index qui inclut le graphique lui-même et les kmers d'une taille particulière. Lors du cartographie, toute taille KMER plus courte que celle utilisée dans l'index peut être utilisée, et par défaut, le mappeur diminuera la taille KMER pour augmenter la sensibilité lorsque l'alignement à un K particulier échoue.
# 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 variation des alignements peut être réintégrée dans le graphique. Ce processus est appelé augmentation et peut être utilisé pour les appels de variants de novo , par exemple (voir ci-dessous).
L'avertissement en utilisant
vg augmentpour les appels de variantes reste très expérimental. Il n'est pas du tout recommandé pour l'appel de variantes structurelles, et même pour les petites variantes, vous obtiendrez souvent des résultats beaucoup plus précis (au moins sur l'homme) en projetant votre alignement surBAMet en exécutant un appelant de variantes linéaires comme 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.vgRemarque Plus d'informations peuvent être trouvées dans le wiki.
Les exemples suivants montrent comment générer un VCF avec VG en utilisant la prise en charge de lecture. Ils dépendent de la sortie des exemples de cartographie et d'augmentation ci-dessus. De petites variantes et SV peuvent être appelés en utilisant la même approche. Actuellement, c'est plus une précision pour les SV .
Appelez uniquement les variantes présentes dans le graphique:
# 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 Par défaut, vg call omet 0/0 variantes et essaie de normaliser les allèles pour rendre le VCF plus compact. Ces deux étapes peuvent rendre difficile de comparer les sorties de différents échantillons car les VCF auront des coordonnées différentes même si elles ont été créées en utilisant le même graphique. L'option -a aborde cela en appelant chaque snarl en utilisant les mêmes coordonnées et en incluant des appels de référence. Les sorties de différents échantillons peuvent être combinées avec bcftools merge -m all .
vg call x.xg -k aln.pack -a > snarl_genotypes.vcf
Afin de considérer également de nouvelles variantes des lectures, utilisez le graphique augmenté et GAM (comme créé dans l'exemple "Augmentation" en utilisant vg augment -A ):
L'avertissement en utilisant
vg augmentpour les appels de variantes reste très expérimental. Il n'est pas du tout recommandé pour l'appel de variantes structurelles, et même pour les petites variantes, vous obtiendrez souvent des résultats beaucoup plus précis (au moins sur l'homme) en projetant votre alignement surBAMet en exécutant un appelant de variantes linéaires comme 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 processus similaire peut être utilisé pour génotype les variantes connues d'un VCF. Pour ce faire, le graphique doit être construit à partir du VCF avec vg construct -a (les graphiques provenant d'autres sources tels que vg autoindex et Minigraph-Cactus ne peuvent pas être utilisés):
# 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.vcfLe pré-filtrage du GAM avant le support informatique peut améliorer la précision des appels 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.vcfPour les graphiques plus grands, il est recommandé de calculer les grondements séparément:
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 Remarque: vg augment , vg pack , vg call et vg snarls peuvent désormais être exécutés directement sur n'importe quel format de graphique (ex '.gbz', '.gfa', .vg , .xg (sauf augment ) ou quoi que ce soit de sortie par vg convert ). Faire fonctionner sur .vg ou «.gfa» utilise le plus de mémoire et n'est pas recommandé pour les gros graphiques. La sortie du vg pack ne peut être lue qu'en conjonction avec le même graphique utilisé pour le créer, donc vg pack x.vg -g aln.gam -o x.pack puis vg call x.xg -k x.pack ne fonctionnera pas .
Inférer des variantes des alignements impliqués par des chemins du graphique. Cela peut être utilisé, par exemple, pour appeler les SV directement à partir d'un graphique de variation qui a été construit à partir d'un alignement multiple de différents assemblages:
# 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 Les chemins d'haplotype à partir des index .gbz ou .gbwt l'entrée peuvent être envisagés en utilisant -z et «-g», respectivement.
Comme avec vg call , il est préférable de calculer les snarls séparément et de les transmettre avec -r lorsque vous travaillez avec de grands graphiques.
vg a un certain nombre d'outils pour prendre en charge les analyses transcriptomiques avec des graphiques épissés (c'est-à-dire des graphiques qui ont des jonctions d'épissage annotées ajoutées sous forme de bords dans le graphique). Ces bords peuvent être ajoutés à un graphique existant à l'aide vg rna . Nous pouvons ensuite effectuer un mappage conscient de Splice à ces graphiques en utilisant vg mpmap . Les développeurs vg ont également fait un outil de quantification des transcrits consacrés à l'haplotype basé sur ces outils dans rpvg . La façon la plus simple de démarrer ce pipeline est d'utiliser la sous-commande vg autoindex pour faire des index pour vg mpmap . vg autoindex crée des index pour la cartographie à partir de formats d'échange commun comme FastA, VCF et GTF.
Plus d'informations sont disponibles dans la page Wiki sur Transcriptomics.
En travaillant à partir du test/ répertoire, l'exemple suivant montre comment créer un graphique de Pangenome épissé et des index à l'aide de vg autoindex avec 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 Les lectures d'ARN-Seq peuvent être mappées sur le graphique de Pangenome épissé en utilisant vg mpmap avec 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 Cela produira des alignements dans le format multiple. Pour plus d'informations sur le format d'alignement multiple et vg mpmap voir la page Wiki sur MPMAP. L'exécution des deux commandes sur les petits exemples de données à l'aide de 4 threads devrait sur la plupart des machines prennent moins d'une minute.
Si vous avez un petit graphique, vous pouvez aligner une séquence sur l'ensemble du graphique, en utilisant un alignement d'ordre partiel complet:
vg align -s CTACTGACAGCAGAAGTTTGCTGTGAAGATTAAATTAGGTGATGCTTG x.vgNotez que vous n'avez pas du tout à stocker le graphique sur le disque, vous pouvez simplement le tuer dans l'aligneur local:
vg construct -r small/x.fa -v small/x.vcf.gz | vg align -s CTACTGACAGCAGAAGTTTGCTGTGAAGATTAAATTAGGTGATGCTTG - La plupart des commandes permettent le streaming des graphiques dans et hors de vg .
Une variété de commandes sont disponibles:
vg est une collection d'outils basés sur un modèle de données commun (le graphique de variation) décrit par un schéma Protobuf (VG.Proto). Les objets de données définis dans vg.proto peuvent être sérialisés via un modèle de flux défini dans Stream.Hpp. Il n'est pas nécessaire d'écrire du code dans VG afin d'interfacer avec les algorithmes définis ici. Il est plutôt parfois plus simple d'écrire un algorithme externe qui lit et écrit les mêmes formats de données.
Mit
