Vg
tools for working with genome variation graphs
Install / Use
/learn @vgteam/VgREADME
vg
variation graph data structures, interchange formats, alignment, genotyping, and variant calling methods
Variation graphs provide a succinct encoding of the sequences of many genomes. A variation graph (in particular as implemented in vg) is composed of:
- nodes, which are labeled by sequences and ids
- edges, which connect two nodes via either of their respective ends
- paths, which describe genomes, sequence alignments, and annotations (such as gene models and transcripts) as walks through nodes connected by edges
This model is similar to sequence graphs that have been used in assembly and multiple sequence alignment.
Paths provide coordinate systems relative to genomes encoded in the graph, allowing stable mappings to be produced even if the structure of the graph is changed. The variation graph model makes this embedding explicit and essential. Tools in vg maintain paths as immutable during transformations of the graph. They use paths to project graph-relative data into reference-relative coordinate spaces. Paths provide stable coordinates for graphs built in different ways from the same input sequences.
Citing VG
Please cite:
- The VG Paper when using
vg - The VG Giraffe Paper when using
vg giraffe - The Long Read Giraffe Paper when using
vg giraffe's chaining modes (hifi,r10,chaining-sr) - The VG Call Paper when SV genotyping with
vg call - The GBZ Paper when using GBZ
- The HPRC Paper when using
vg deconstruct - The Snarls Paper when using
vg snarls - The Personalized Pangenome Paper when using
vg haplotypesand/orvg giraffe --haplotype-name
Support
We maintain a support forum on biostars: https://www.biostars.org/tag/vg/
Installation
Download Releases
The easiest way to get vg is to download one of our release builds for Linux. We have a 6-week release cadence, so our builds are never too far out of date.
Download the latest vg release for Linux
For MacOS, see Building on MacOS.
Building on Linux
If you don't want to or can't use a pre-built release of vg, or if you want to become a vg developer, you can build it from source instead.
Linux: Clone VG
First, obtain the repo and its submodules:
git clone --recursive https://github.com/vgteam/vg.git
cd vg
Linux: Install Dependencies
Then, install VG's dependencies. You'll need the Protobuf and Jansson development libraries installed, and to run the tests you will need:
jq,bc,rs, andparallelhexdumpandcolumnfrombsdmainutilsnpmfor testing documentation examples.
On Ubuntu 22.04, you should be able to do:
make get-deps
If you get complaints that sudo is not found, install it:
apt update
apt install sudo
If you get a bunch of errors like E: Unable to locate package build-essential, make sure your package index files are up to date by running:
sudo apt update
On other distros, or if you do not have root access, you will need to perform the equivalent of:
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 libssl-dev kmc
At present, you will need GCC version 9 or greater, with support for C++17, to compile vg. (Check your version with gcc --version.) GCC up to 11.4.0 is supported.
Other libraries may be required. Please report any build difficulties.
Note that a 64-bit OS is required.
Linux: Build
When you are ready, build with make. You can use make -j16 to run 16 build threads at a time, which greatly accelerates the process. If you have more CPU cores, you can use higher numbers.
Note that vg can take anywhere from 10 minutes to more than an hour to compile depending on your machine and the number of threads used.
You can also produce a static binary with make static, assuming you have static versions of all the dependencies installed on your system.
Linux: Run
Once vg is built, the binary will be at bin/vg inside the vg repository directory. You can run it with:
./bin/vg
You can also add its directory to your PATH enviornment variable, so that you can invoke vg from any directory. To do that on Bash, use this command from the vg repository directory:
echo 'export PATH="${PATH}:'"$(pwd)"'/bin"' >>~/.bashrc
Then close your terminal and open a new one. Run vg to make sure it worked.
If it did not work, make sure that you have a .bash_profile file in your home directory that will run your .bashrc:
if [ -f ~/.bashrc ]; then
source ~/.bashrc
fi
Building on MacOS
Mac: Clone VG
The first step is to clone the vg repository:
git clone --recursive https://github.com/vgteam/vg.git
cd vg
Mac: Install Dependencies
VG depends on a number of packages being installed on the system where it is being built. Dependencies can be installed using either MacPorts or Homebrew.
Using MacPorts
You can use MacPorts to install VG's dependencies:
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 openssl
Using Homebrew
Homebrew provides another package management solution for OSX, and may be preferable to some users over MacPorts. VG ships a Brewfile describing its Homebrew dependencies, so from the root vg directory, you can install dependencies, and expose them to vg, like this:
# Install all the dependencies in the Brewfile
brew bundle
Mac: Build
With dependencies installed, VG can now be built:
make
As with Linux, you can add -j16 or other numbers at the end to run multiple build tasks at once, if your computer can handle them.
Note that static binaries cannot yet be built for Mac.
The vg Mac build targets whatever the current version of Apple Clang is, and whatever version of Apple Clang is provided by our Github Actions Mac CI system. If your Clang is up to date and vg does not build for you, please open an issue.
Mac: Run
Once vg is built, the binary will be at bin/vg inside the vg repository directory. You can run it with:
./bin/vg
You can also add its directory to your PATH enviornment variable, so that you can invoke vg from any directory. To do that on the default zsh Mac shell, use this command from the vg repository directory:
echo 'export PATH="${PATH}:'"$(pwd)"'/bin"' >>~/.zshrc
Then close your terminal and open a new one. Run vg to make sure it worked.
Migrate a VG installation from x86 to ARM
The Mac platform is moving to ARM, with Apple's M1, M1 Pro, M1 Max, and subsequent chip designs. The vg codebase supports ARM on Mac as well as on Linux. The normal installation instructions work on a factory-fresh ARM Mac.
However, it is easy to run into problems when migrating a working vg build environment or migrating MacPorts or Homebrew from x86_64 to ARM. The ARM machine can successfully run x86_64 tools installed via Macports or Homebrew on the old machine, but vg can only build properly on ARM if you are using ARM versions of the build tools, like make and CMake.
So, after migrating to an ARM Mac using e.g. Apple's migration tools:
- Uninstall MacPorts and its packages, if they were migrated from the old machine. Only an ARM MacPorts install can be used to provide dependencies for vg on ARM.
- Uninstall Homebrew and its packages, if they were migrated. Similarly, only an ARM Homebrew install will work.
- Reinstall one of MacPorts or Homebrew. Make sure to use the M1 or ARM version.
- Use the package manager you installed to install system dependencies of vg, such as CMake, as documented above.
- Clean vg with
make clean. This should remove all build artefacts. - Build vg again with
make.
If you still experience build problems after this, delete the whole checkout and check out the code again; make clean is not under CI test and is not always up to date with the rest of the build system.
Whether or not that helps, ple
