alt text

Suite of PhylogEnetiC Tools for Reticulate Evolution (SPECTRE)

The aim of this project was to create a single project that contains a number of reusable tools for modelling and visualising reticulate evolution via phylogenetic trees and networks. It contains a number of previous published tools for generating phylogenetic networks for various types from a range of different inputs. SPECTRE also contains a library containing data structures and algorithms that can be leveraged by third party applications.

Installing

SPECTRE can be installed via three main methods either from a platform-specific install, pre-packaged tarball, or directly from github source repository via a git clone. The necessary steps for all methods are described in the following sections.

Some of the tools in SPECTRE use external mathematical optimizers for solving linear and quadratic problems. Should you install from a platform-specific installer or cross-platform tarball then a working version of Apache Maths and JOptimizer is included. However, some users may want to use optimizers from other vendors or sources such as Gurobi. In this case you will need to install another tool called metaopt first, and then install from source. Metaopt can be obtained from https://github.com/maplesond/metaopt. Please follow the instructions in the metaopt README for how to add other optimizers. Then follow the instructions for installing from source below.

Platform-specific installer

SPECTRE currently supports Debian/Ubuntu, MacOS and windows installers. Users of these platforms should find the installation experience self-explanatory. They should only need to download the appropriate file from the github repository releases page: https://github.com/maplesond/spectre/releases and then double click the downloaded file. There are however, some platform-specific considerations for running SPECTRE which are detailed below.

Debian/Ubuntu

Installing the debian file will put a shortcut for the GUI into either your Science or Other menu section depending on how you have your system configured. Links to the command-line versions of your apps will be added to /usr/bin and the program itself is installed to /usr/share/spectre.

MacOS

After double-clicking the DMG image file, drag the SPECTRE app into the Applications folder. You should then be able to access the GUI from the launchpad.

On Mac platforms, the application may be regarded as a software from unidentified developers and hence they may need to open it as following:

  1. Open a new Finder Window
  2. Navigate to the Download or Application you just installed to your Mac
  3. Instead of Double-Clicking on the Icon to open, Right Click on it and choose “Open”
  4. A Pop-Up Window will appear telling you that the Software is from an Unidentified Developer, but it will give you the option to Open it anyway. Click on “Open”, and the software will run as expected.

https://support.novationmusic.com/hc/en-gb/articles/207561205-My-Software-is-from-an-Unidentified-Developer-and-won-t-Install-on-my-Mac

We have not at present installed the command-line tools onto the PATH, but they are present on your system and can be found in /Applications/Spectre.app/Contents/MacOS. You can either run them from here or manually link them into /usr/local/bin in order to have them directly available from the terminal.

Windows

The windows installer will allow you to install SPECTRE to a directory of your choosing. After which it should be available from the start menu.

Please note the command-line versions of the tools are not available on windows via this method.

Pre-packaged Tarball

Before starting the installation please ensure that the Java Runtime Environment (JRE) V1.8+ is installed and configured for your environment. You can check this by typing the following at the command line: java -version. Double check the version number exceeds V1.8.

The installation process from tarball is simple. The first step is acquire the tarball from https://github.com/maplesond/spectre/releases. Then unpacking the compressed tarball to a directory of your choice. The unpack command is: tar -xvf spectre-<version>-<platform>.tar.gz. This will create a sub-directory called spectre-<version> and in there should be the following further sub-directories:

Should you want to run the tools without referring to their paths, you should ensure the bin directory is on your PATH environment variable.

From source

SPECTRE is a java 1.8 / maven project. Before compiling the source code, please make sure the following tools are installed:

You also need to make sure that the system you are compiling on has internet access, as it will try to automatically incorporate any required java dependencies via maven. Because SPECTRE is a maven project, almost all the other dependencies (not mentioned here) will be downloaded automatically as part of the Maven buildcycle. However, the one exception to this is a java library called metaopt (described at the beginning of this section), which provides a common interface to several open source and commercial optimizers. Metaopt can be obtained from: https://github.com/maplesond/metaopt. Please follow the instructions in the metaopt README and make sure the metaopt library has been added to your local maven repository. After this, you can proceed with the SPECTRE installation.

Now type the following::

git clone https://github.com/maplesond/spectre.git cd spectre

Then type::

mvn clean install

or, if you wish to enable gurobi optimizer support::

mvn clean install -P gurobi

Note: If you cannot clone the git repositories using “https”, please try “ssh” instead. Consult github to obtain the specific URLs.

Assuming there were no compilation errors. The build, hopefully the same as that described in the previous section, can now be found in ./build/spectre-. There should also be a dist sub directory which will contain a tarball suitable for installing SPECTRE on other systems.

Core Library

Contains classes that are used by other modules, that contain some kind of general functionality which means they can be used in different situations. These classes were broken down into sub groups based on their specific kind of functionality as follows:

Core is designed to contain most of the core functionality of the tools within SPECTRE. The idea being that other developers can design there own tools whilst leveraging the functionality in this library.

Tools

SPECTRE contains the following tools, which are accessible to the user via graphical and command line interfaces.

The graphical interface is invoked via the spectre script and can visualize the planar split networks output from the tools.

Quick Start:

Assuming the user has access to the compiled executable jars for SPECTRE, then they should only need JRE 1.8+ installed on their system. The tools can be found in the bin subfolder.

Further Documentation and Citing

The full manual can be found in the doc directory, or online at: http://spectre-suite-of-phylogenetic-tools-for-reticulate-evolution.readthedocs.io/en/latest/

We also have a preprint available on BioRxiv: http://www.biorxiv.org/content/early/2017/07/27/169177. Should you use our software please cite this paper.

Issues

Should you discover any issues with SPECTRE, or wish to request a new feature please raise a ticket at https://github.com/maplesond/spectre/issues. Alternatively, contact Sarah Bastkowski at: sarah.bastkowski@earlham.ac.uk, or Daniel Mapleson at: daniel.mapleson@earlham.ac.uk.

Availability:

Open source code available on github: https://github.com/maplesond/spectre.git

License: GPL v3

Contact