The GSCM Project is a java library and command line tool providing the greedy strict consensus merger supertree algorithm for rooted input trees. It provides several scoring functions to determine in which oder the input trees get merged. Combining different scorings is also implemented as well as a randomized version of the algorithm. For more detailed information about the algorithm see the Literature.
Literature
[1] Markus Fleischauer and Sebastian Böcker, Collecting reliable clades using the Greedy Strict Consensus Merger. PeerJ (2016) 4:e2172 https://doi.org/10.7717/peerj.2172
[2] Markus Fleischauer and Sebastian Böcker, Collecting reliable clades using Greedy Strict Consensus Merger. Proc. of German Conference on Bioinformatics (GCB 2015), volume 3 of PeerJ PrePrints, pages e1595. PeerJ Inc. San Francisco, USA, 2015.
Download Links
GSCM commandline tool v1.0.1
- for Windows
- for Linux/Unix
- as jar file
GSCM commandline tool v1.0
- for Windows
- for Linux/Unix
- as jar file
The Source Code can be found on GitHub
Installation
Windows
The gscm.exe should hopefully work out of
the box. To execute GSCM from every location you have to add the
location of the gscm.exe
to your PATH environment variable.
Linux and MacOSX
To execute GSCM from every location you have to add the location of
the gscm executable to your PATH variable. Open the file ~/.bashrc
in an editor and add the following line (replacing the placeholder path):
export PATH-$PATH:/path/to/gscm
Jar (any OS)
Alternatively, you can run the gscm.jar jar file using java with the command:
java -jar /path/to/gscm.jar
Using GSCM command line tool
You can always use the --help
option to get a documentation about
the available commands and options.
Generally you only need to specify the input trees as input.
Other options are listet below or be see via --help
option
Supported Filtypes
The GSCM command line tool handles trees in NEWICK and NEXUS format.
For an automatic file format detection use the common file extension
for NEWICK (tree|TREE|tre|TRE|phy|PHY|nwk|NWK)
and NEXUS (nex|NEX|ne|NE|nexus|NEXUS)
.
Per default the output tree format equals the input format. To specify a different
output format you can use the option --outFileType
or the short form -d
.
Supported Commands
Usage:
gscm [options...] INPUT_TREES_FILE
INPUT_TREES_FILE : Path of the file containing the input data
General options:
-H (--HELP) : Full usage message including
nonofficial Options (default: false)
-O (--fullOutput) PATH : Appends the unmerged trees of all
scorers and random iterations to the
output file
-R (--randomIterations) N : Enables randomization and specifies
the number of iterations per scoring
-V (--VERBOSE) : many console output
-d (--outFileType) [NEXUS | NEWICK | AUTO] : Output file type (default: AUTO)
-f (--fileType) [NEXUS | NEWICK | AUTO] : Type of input files and if not
specified otherwise also of the
output file (default: AUTO)
-h (--help) : usage message (default: false)
-o (--outputPath) PATH : Output file
-p (--workingDir) PATH : Path of the working directory. All
relative paths will be rooted here.
Absolute paths are not effected
-r (--randomized) : Enables randomization (standard
iterations are numberOfTrees^2 per scoring)
-s (--scorer) [UNIQUE_TAXA | : set of scores that should be used.
UNIQUE_TAXA_ORIG | OVERLAP | standard scm can use only one
OVERLAP_ORIG | CLADE_NUMBER | (default: UNIQUE_CLADES_LOST)
RESOLUTION | COLLISION_SUBTREES
| COLLISION_POINT | UNIQUE_CLADE_NUMBER
| UNIQUE_CLADE_RATE | UNIQUE_CLADES_LOST
| UNIQUE_CLADES_REMAINING]
-v (--verbose) : some more console output
-t (--threads) N : Set a positive number of Threads that should be used
-T (--singleThreaded) : starts in single threaded mode, equal to "-t 1"
-B (--disableProgressbar) : Disables progress bar (cluster/background mode)
GSCM Java Library
You can integrate the GSCM library in your java project, either by using Maven [1] or by including the jar file directly. The latter is not recommended, as the GSCM jar contains also dependencies to other external libraries.
Maven Integration
Add the following repository to your pom file:
<distributionManagement>
<repository>
<id>bioinf-jena</id>
<name>bioinf-jena-releases</name>
<url>https://bio.informatik.uni-jena.de/repository/libs-releases-local</url>
</repository>
</distributionManagement>
Now you can integrate GSCM in your project by adding the following dependency:
Library containing all algorithms
<dependency>
<groupId>de.unijena.bioinf</groupId>
<artifactId>gscm-lib</artifactId>
<version>1.0.1</version>
</dependency>
Whole project containing the algorithm (gscm-lib) and the command line interface (gscm-cli)
<dependency>
<groupId>de.unijena.bioinf</groupId>
<artifactId>gscm</artifactId>
<version>1.0.1</version>
</dependency>
Main API
The main class in the GSCM library is de.unijena.bioinf.SCMAlgorithm
.
It specifies the main API of all provided algorithm implementation. To run a algorithm
just have to specify scorer(s) and input trees.
There are currently 3 implemetations of de.unijena.bioinf.gscm.algorithm.GSCMAlgorithm
:
Algorithm Implemetation(s):
public class GreedySCMAlgorithm
This class provides the basic greedy strict consensus merger algorithm. Parameters:
- input -- List of rooted input trees.
- scorer -- scoring function that should be used
Returns: The greedy strict consensus merger supertree
public class MultiGreedySCMAlgorithm
This class provides a greedy strict consensus merger algorithm that combines the results of different scoring functions into one supertree.
Parameters:
- input -- List of rooted input trees.
- scorer -- List of scoring functions that should be used
Returns: List of all generaated gscm supertrees The combined supertree
public class RandomizedSCMAlgorithm
This class provides a randomized greedy strict consensus merger algorithm that combines the results of multiple radmomized runs. It handles also multiple scoring functions.
Parameters:
- input -- List of rooted input trees.
- scorer -- List of scoring functions that should be used
- numberOfIterations -- number of random iterations
Returns: List of all generaated gscm supertrees The combined supertree
Scorer Implemetations:
The class TreeScorers is a factory class that provides recommended scorers and scorer combinations:
UNIQUE_TAXA,
UNIQUE_TAXA_ORIG,
OVERLAP,
OVERLAP_ORIG,
CLADE_NUMBER,
RESOLUTION,
COLLISION_SUBTREES,
COLLISION_POINT,
UNIQUE_CLADE_NUMBER,
UNIQUE_CLADE_RATE,
UNIQUE_CLADES_LOST,
UNIQUE_CLADES_REMAINING
The in Fleischauer et al. presented scorings are:
UNIQUE_TAXA_ORIG,
OVERLAP_ORIG,
RESOLUTION,
COLLISION_SUBTREES,
UNIQUE_CLADE_NUMBER,
UNIQUE_CLADES_LOST,
Changelog
1.0.1
- less memory consumption
- bug fix for simple/fast scorings such as Overlap -> large speed up
1.0
- release version