Home

Awesome

libpll

Build Status License

Introduction

The aim of this project is to implement a versatile high-performance software library for phylogenetic analysis. The library should serve as a lower-level interface of PLL (Flouri et al. 2015) and should have the following properties:

Compilation instructions

Currently, libpll requires that GNU Bison and Flex are installed on the target system. On a Debian-based Linux system, the two packages can be installed using the command

apt-get install flex bison

The library also requires that a GNU system is available as it uses several functions (e.g. asprintf) which are not present in the POSIX standard. This, however will change in the future in order to have a more portable and cross-platform library.

The library can be compiled using either of the following two ways.

Cloning the repo Clone the repo and bild the executable and documentation using the following commands.

git clone https://github.com/xflouris/libpll.git
cd libpll
./autogen.sh
./configure
make
make install    # as root, otherwise run: sudo make install

When using the cloned repository version, you will also need autoconf, automake and libtool installed. On a Debian-based Linux system, the packages can be installed using the command

sudo apt-get install autotools-dev autoconf libtool

The library will be installed on the operating system's standard paths. For some GNU/Linux distributions it might be necessary to add that standard path (typically /usr/local/lib) to /etc/ld.so.conf and run ldconfig.

Microsoft Windows compatibility was tested with a cross-compiler and seems to work out-of-the-box using MingW.

Available functionality

libpll currently implements the General Time Reversible (GTR) model (Tavare 1986) which can be used for nucleotide and amino acid data. It supports models of variable rates among sites, the Inv+Γ (Gu et al. 1995) and has functions for computing the discretized rate categories for the gamma model (Yang 1994). Furthermore, it supports several methods for ascertainment bias correction (Kuhner et al. 2000, McGill et al. 2013, Lewis 2011, Leaché et al. 2015). Additional functionality includes tree visualization, functions for parsimony (minimum mutation cost) calculation and ancestral state reconstruction using Sankoff's method (Sankoff 1975, Sankof and Rousseau 1975). The functions for computing partials, evaluating the log-likelihood and updating transition probability matrices are vectorized using both SSE3, AVX and AVX2 instruction sets.

Documentation

Please refer to the wiki page.

Usage examples

Please refer to the wiki page and/or the examples directory.

libpll license and third party licenses

The libpll code is currently licensed under the GNU Affero General Public License version 3. Please see LICENSE.txt for details.

libpll includes code from several other projects. We would like to thank the authors for making their source code available.

libpll includes code from GNU Compiler Collection distributed under the GNU General Public License.

Code

The code is written in C with some parts written using in-line assembler and intrinsic functions.

FileDescription
compress.cFunctions for compressing alignment into site patterns.
core_derivatives_avx2.cAVX2 vectorized core functions for computing derivatives of the likelihood function.
core_derivatives_avx.cAVX vectorized core functions for computing derivatives of the likelihood function.
core_derivatives.cCore functions for computing derivatives of the likelihood function.
core_derivatives_sse.cSSE vectorized core functions for computing derivatives of the likelihood function.
core_likelihood_avx2.cAVX2 vectorized core functions for computing the log-likelihood.
core_likelihood_avx.cAVX vectorized core functions for computing the log-likelihood.
core_likelihood.cCore functions for computing the log-likelihood, that do not require partition instances.
core_likelihood_sse.cSSE vectorized core functions for computing the log-likelihood.
core_partials_avx2.cAVX2 vectorized core functions for updating vectors of conditional probabilities (partials).
core_partials_avx.cAVX vectorized core functions for updating vectors of conditional probabilities (partials).
core_partials.cCore functions for updating vectors of conditional probabilities (partials).
core_partials_sse.cSSE vectorized core functions for updating vectors of conditional probabilities (partials).
core_pmatrix_avx2.cAVX2 vectorized core functions for updating transition probability matrices.
core_pmatrix_avx.cAVX vectorized core functions for updating transition probability matrices.
core_pmatrix.cCore functions for updating transition probability matrices.
core_pmatrix_sse.cSSE vectorized core functions for updating transition probability matrices.
derivatives.cFunctions for computing derivatives of the likelihood function.
fasta.cFunctions for parsing FASTA files.
fast_parsimony_avx2.cAVX2 fast unweighted parsimony functions.
fast_parsimony_avx.cAVX fast unweighted parsimony functions.
fast_parsimony.cNon-vectorized fast unweighted parsimony functions.
fast_parsimony_sse.cSSE fast unweighted parsimony functions.
gamma.cFunctions related to Gamma (Γ) function and distribution.
hardware.cHardware detection functions.
lex_rtree.lLexical analyzer for parsing newick rooted trees.
lex_utree.lLexical analyzer for parsing newick unrooted trees.
likelihood.cFunctions ofr computing the log-likelihood of a tree given a partition instance.
list.c(Doubly) Linked-list implementations.
maps.cCharacter mapping arrays for converting sequences to the internal representation.
models.cModel parameters related functions.
output.cFunctions for output in terminal (i.e. conditional likelihood arrays, probability matrices).
parse_rtree.yFunctions for parsing rooted trees in newick format.
parse_utree.yFunctions for parsing unrooted trees in newick format.
parsimony.cParsimony functions.
partials.cFunctions for updating vectors of conditional probabilities (partials).
phylip.cFunctions for parsing phylip files.
pll.cFunctions for setting PLL partitions (instances).
random.cRe-entrant multi-platform pseudo-random number generator.
rtree.cRooted tree manipulation functions.
utree.cUnrooted tree manipulation functions.
utree_moves.cFunctions for topological rearrangements on unrooted trees.
utree_svg.cFunctions for SVG visualization of unrooted trees.

Bugs

The source code in the master branch is thoroughly tested before commits. However, mistakes may happen. All bug reports are highly appreciated. You may submit a bug report here on GitHub as an issue, or you could send an email to t.flouris@ucl.ac.uk.

libpll core team

Acknowledgements

Special thanks to the following people for patches and suggestions:

Contributing to libpll

Please read the section Contributing to libpll of the wiki.

References