phyluce uses a number of tools that allow it to assemble data, search for UCE
loci, align results reads, manipulate alignments, prepare alignments for
analysis, etc. To accomplish these goals, phyluce uses wrappers around a
number of programs that do each of these tasks (sometimes phyluce can use
several different programs that accomplish the same task in different ways).
As a result, the
dependency chain , or the
programs that phyluce requires to run, is reasonably complex.

In previous versions (< 1.4.x), we required users to install a number of
different software packages, get those into the user’s $PATH, cross their
fingers, and hope that everything ran smoothly (it usually did not).

In the current versions (> 1.4.x), we have removed a number of dependencies,
and we very strongly suggest that users install phyluce using either the
anaconda or miniconda Python distributions.

Attention

We do not support installing phyluce through means other than the
conda installer. This means that we do not test phyluce against any
binaries, other than those we build and distribute through conda.
You will eventually be able to configure phyluce to use binaries
of different provenance, although this will not be officically supported,
other than providing a mechanism to do so.

Note

We build and test the binaries available through conda using
64-bit operating systems that include:

It may seem odd to impose a particular disitribution on users, and we largely
agree. However, conda makes it very easy for us to distribute both Python and
non-Python packages (e.g. velvet, ABySS, etc.), setup identical environments
across very heterogenous platforms (linux, osx), make sure all the $PATHs are
correct, and have things run largely as expected. Using conda has several other
benefits, including environment separation similar to virtualenv. In short,
using conda gets us as close to a “one-click” install that we will probably
ever get.

Although we’re using conda, you need to install a JAVA distribution for your
platform. You should install JAVA7, as that will ensure a number of future
tools in phyluce will work on your platform. Installing JAVA is a little
tricky across different platforms (and somewhat beyond the scope of this
document), but we describe, below, how we usually do it.

The major difference between the two python distributions is that anaconda
comes with many, many packages pre-installed, while miniconda comes with
almost zero packages pre-installed. As such, the beginning anaconda
distribution is roughly 200-500 MB in size while the beginning miniconda
distribution is 15-30 MB in size.

Find the correct miniconda-x.x.x file for your platform from
http://repo.continuum.io/miniconda/ and download that file. Be sure you do
not get one of the packages that has a name starting with miniconda3-. When
that has completed, run one of the following:

Regardless of whether you install anaconda or miniconda, you need to check
that you’ve installed the package correctly. To ensure that the correct
location for anaconda or miniconda are added to your $PATH (this occurs
automatically on the $BASH shell), run the following:

$ python -V

The output should look similar to (x will be replaced by a version):

Python2.7.x::Anacondax.x.x(x86_64)

Notice that the output shows we’re using the Anaconda x.x.x version of
Python. If you do not see the expected output (or something similar), then you
likely need to edit your $PATH variable to add anaconda or miniconda.

The easiest way to edit your path, if needed is to open ~/.bashrc with a
text editor (if you are using ZSH, this will be ~/.zshrc) and add, as the
last line:

export PATH=$HOME/path/to/conda/bin:$PATH

where $HOME/path/to/conda/bin is the location of anaconda/miniconda on your
system (usually $HOME/anaconda/bin or $HOME/miniconda/bin).

Warning

If you have previously set your $PYTHONPATH elsewhere in your
configuration, it may cause problems with your anaconda or miniconda
installation of phyluce. The solution is to remove the offending library
(-ies) from your $PYTHONPATH.

You need to add the location of the packages we need to your conda
distributions. to do taht, you have to add the
faircloth-lab conda repository
to conda. You can do that with the following command, which automatically edits
your ~/.condarc file):

When you install phyluce, it specifies a number of dependencies that it needs
to run. conda is great because it will pull specific versions of the
required programs from the
faircloth-lab conda repository and
install those on your machine, setup the paths, etc.

Below is a list of what phyluce currently (v1.4.x) requires for installation.

An added benefit of using conda and installing packages in this way is that you
can also run all of the 3rd-party binaries without worrying about setting the
correct $PATH, etc.

For example, phyluce required MUSCLE for installation, and MUSCLE was installed
by conda as a dependency of phyluce. Because $HOME/anaconda/bin (which we
will now call $CONDA) is part of our path now, and because phyluce installed
MUSCLE, we can also just run MUSCLE on the command-line, with:

This is true for other binaries you install from our repository (e.g. velveth,
velvetg, abyss-pe, mafft) or any other conda repository - those binaries are
all stored in $CONDA/bin.

We have setup conda to install other files in a standard location as well. So
JAR files are stored in $CONDA/jar; libraries that you install from our repo
are stored in $CONDA/lib, etc. The locations and versions are standardized
within our conda distribution so that we always know where things are
installed, hopefully avoiding lots of the problems with dependency hell and making our lives easier.

The structure of the conda repository that we use looks like the following:

As of v1.5, phyluce uses a configuration file to keep track of paths to relvant
binaries, as well as some configuration information. This file is located at
$CONDA/config/phyluce.conf. Although you can edit this file directly, you can
also create a user-specific configuration file at ~/.phyluce.conf (note the
preceding dot), which will override the default values for different paths.
So, if you need to use a slightly different binary or you want to experiment
with new binaries (e.g. for assembly), then you can change the paths in this
file rather than deal with hard-coded paths.

Attention

You do NOT need to to anything with this file - $PATHs should
automatically resolve.

Warning

Changing the $PATHs in the config file can break things pretty
substantially, so please use with caution (and edit the copy at
~/.phyluce.conf) rather than the default copy.