Rapid competitive read demulitplexer. Made with tries.
Clone or download
kdmurray91 Minor usage clarification
Closes github issue #9
Latest commit e23af27 Apr 17, 2018

README.md

AXE

De-multiplex NGS reads using trie data structures. It's fast, and made of tries!

DOI Documentation Status Join the chat at https://gitter.im/axe-demultipexer/Lobby

AXE very rapidly selects the optimal index present in a sequence read, even in the presence of sequencing errors. The algorithm is able to handle combinatorial indexing, indexes of differing length, and several mismatches per index. Early results indicate far improved accuracy and speed over existing de-multiplexers. Unscientific trials show AXE processes more than 500,000 reads per second.

Quick Start

To install on UNIX-like systems (Mac, Linux), get the dependencies (zlib and cmake, see below), and:

git clone --recursive https://github.com/kdmurray91/axe.git axe
cd axe
cmake .
sudo make install

A tutorial on the usage of Axe is available at https://axe-demultiplexer.readthedocs.org/en/latest/, along with full documentation and a basic description of the algorithm.

Important Note

For arcane reasons, the name of the axe binary changed to axe-demux with version 0.3.0. Apologies for the inconvenience, this was required to make axe installable in Debian and its derivatives. Command-line usage did not change.

Installation:

Currently, only recent GNU/Linux systems are officially supported. All code and the build system is portable, so compilation and use on other systems should be possible, I just don't have machines available to test. Please report any installation issues on any system as GitHub bugs and I'll do my best to sort them out.

To install to a prefix, as you would with ./configure --prefix with the autotools build system, please use the following cmake command in place of the one above:

cmake -DCMAKE_INSTALL_PREFIX=/path/to/your/prefix ..

e.g.:

cmake -DCMAKE_INSTALL_PREFIX=$HOME ..

For me, using ~/ as the prefix will install axe under /home/kevin/bin on GNU/Linux, and (if I had one) /Users/kevin/bin on Mac OSX.It's also wise to use make install not sudo make install when installing to a home directory.

Dependencies:

  • cmake. This is installable via sudo apt-get install cmake on Debian based systems, or brew install cmake using homebrew on OS X.
  • zlib version >= 1.2.5. On Debian, use the package zlib1g-dev.
  • libqes, tinytest, libgsl and libdatrie (bundled in source, if you used git clone --recursive or an installation tarball. Otherwise, run git submodule update --init).

You'll possibly need to install zlib to your chosen prefix (e.g. ~/) on supercomputers, which often have very old versions of zlib. To do so:

wget http://zlib.net/zlib-1.2.8.tar.gz
tar xvf zlib-1.2.8.tar.gz
cd zlib-1.2.8
./configure --prefix=<your_prefix> # e.g. --prefix=$HOME
make && make install

And then, use the following cmake command, assuming your prefix is ~/:

cmake -DCMAKE_INSTALL_PREFIX=$HOME -DZLIB_ROOT=$HOME ..

Publication

We have a preprint describing AXE up at http://www.biorxiv.org/content/early/2017/07/07/160606

Versioning

We use Semantic Versioning. See semver.org

LICENSE

The source of axe itself, namely src/axe*.[ch] and tests/*.[ch], is Copyright 2014-2015 Kevin Murray. All axe source code is licensed under the GNU GPL version 3 or greater, a copy of which is included with this source as LICENCE.txt

The source of tinytest, located in tests/tinytest, is Copyright 2009-2012 Nick Matthewson; tinytest is distributed under the 3-clause BSD license. tinytest is hosted at Nick's github page.

The source of libgsl, located in src/gsl, is Copyright (C) 1996, 1997, 1998, 1999, 2000, 2007 Gerard Jungman and Brian Gough. It is licensed under the GNU General Public License, vesion 3 or greater.

The source of libdatrie, located in src/datrie, is Copyright 2006 Theppitak Karoonboonyanan, and is licensed under the GNU LGPL version 2.1 per src/datrie/COPYING. libdatrie is hosted at Theppitak Karoonboonyanan's website, here.