README.md

libvgio is a library for (de)serializing vg files for use with the vg toolkit (see Sequence variation aware genome references and read mapping with the variation graph toolkit).

This tool is in the development stage, so it may contain bugs and the instructions on how to use it are subject to change.

Compiling

libvgio is implemented in C++11 and is built using CMake.

libvgio's only dependencies are protobuf (Google Protocol Buffers), htslib, and pthreads, all of which can be easily installed on any Unix style system.

libvgio requires htslib 1.10 or greater to avoid a bug in htslib that truncates multi-member GZIP files after the first member. If you build against an older htslib, you will not be able to read all VG and GAM files properly, especially GraphAligner GAMs.

Once protobufs and pthreads are installed, you can build and install libvgio by running the installation script: ./install.sh [INSTALL_LOCATION]. This will install the dynamic library and headers in your home directory unless you provide the script with the optional INSTALL_LOCATION.

On Mac, you may need to explain how to find OpenMP, and you may not be able to use the script. You can install manually instead. For example, if you installed OpenMP via Homebrew, it ought to be in ${HOMEBREW_PREFIX}/opt/libomp, so you can run:

cd build
cmake -DCMAKE_INSTALL_PREFIX=${HOME} -DCMAKE_PREFIX_PATH="${HOMEBREW_PREFIX}/opt/libomp" ..
make
make install

Usage

libvgio exposes two header files vg/vg.pb.h and vg/io/basic_stream.hpp. vg/vg.pb.h is the header generated by the vg protobuf (see the vg toolkit Wiki for details) and vg/io/basic_stream.hpp exposes an input stream and an output stream.

The following C++ example reads a vg graph with the input stream and writes it to the standard output with the output stream.

#include <iostream>
#include "vg/vg.pb.h"
#include "vg/io/basic_stream.hpp"

using std::cout;
using std::endl;
using vg::Graph;
using vg::io::inputStream;
using vg::io::outputStream;

int main(int argc, char* argv[])
{
  if (argc != 2) {
    cout << "Usage: " << argv[0] << " VG_FILE" << endl;
    return -1;
  }
  Graph g = inputStream(argv[1]);
  outputStream(g);
  return 0;
}

This can be compiled by linking against libvgio at compile time

g++ -lvgio <myprogram>.cpp

or with CMake

find_package(VGio REQUIRED)
target_link_libraries(myprogram VGio::VGio)