Utility for clustering phylogenetic trees in Newick format based on Robinson-Foulds distance.
This package provides a libary and executable for dealing with Newick tree files.
It can do simple binning of identical trees or more complex clustering based on an all-to-all Robinson-Foulds distance matrix.
phybin produces output files that characterize the size and contents of each bin or cluster (including generating GraphViz-based visual representations of the tree topologies).
% PhyBin (0.3): Binning/Clustering Newick Trees by Topology
PhyBin is a simple command line tool that classifies a set of Newick tree files by their topology. The purpose of it is to take a large set of tree files and browse through the most common tree topologies.
Change Log
In version 0.2, PhyBin was extended to do clustering as well as binning:
- Computee full all-to-all Robinson-Foulds distance matrices (quickly)
- Hierarchical clustering of all trees into a tree-of-trees dendrogram based on Robinson Foulds symmetric (tree edit) distance.
In version 0.3, PhyBin gained a number of new features
- A
--tolerantmode for computing RF distance matrices even for trees missing taxa. - A
--pruneoption for "zooming in" on a specific set of taxa. - The
--minboostrapoption was added.
Invoking PhyBin
PhyBin is a command-line program that produces output in the form of text files and pdfs, but to produce pdfs (to visualize trees) the GraphViz program, including the dot command, must be installed on the machine.
The following is a simple invocation of PhyBin:
phybin --bin *.tree -o output_dir/
The input trees can be specified directly on the command-line, or, if the name of a directory is provided instead, all contained files are assumed to be trees in Newick format.
PhyBin, at minimum, produces files of the form output_dir/clusterXX_YY.tr, one for each bin. If requested, it will also produce visual representations of each bin in the form output_dir/clusterXX_YY.pdf.
Downloading and Installing PhyBin
The source code to PhyBin can be downloaded here:
PhyBin is written in Haskell and if you have Haskell Platform. installed you can install phybin with this one-liner:
cabal install phybin
Otherwise PhyBin is also available for download as a statically-linked executable for Mac-OS, Linux, and Windows:
Command-line Options
In addition to input files and directories, phybin supports a number of command-line options. Run "phybin --help" to see these options. Here is a snapshot of the current help output (version 0.2.11):
Usage: phybin [OPTION...] files or directories...
PhyBin takes Newick tree files as input. Paths of Newick files can
be passed directly on the command line. Or, if directories are provided,
all files in those directories will be read. Taxa are named based on the files
containing them. If a file contains multiple trees, all are read by phybin, and
the taxa name then includes a suffix indicating the position in the file:
e.g. FILENAME_0, FILENAME_1, etc.
When clustering trees, Phybin computes a complete all-to-all Robinson-Foulds distance matrix.
If a threshold distance (tree edit distance) is given, then a flat set of clusters
will be produced in files clusterXX_YY.tr. Otherwise it produces a full dendogram (UNFINISHED).
Binning mode provides an especially quick-and-dirty form of clustering.
When running with the --bin option, only exactly equal trees are put in the same cluster.
Tree pre-processing still applies, however: for example collapsing short branches.
USAGE NOTES:
* Currently phybin ignores input trees with the wrong number of taxa.
* If given a directory as input phybin will assume all contained files are Newick trees.
Options include:
-v --verbose print WARNINGS and other information (recommended at first)
-V --version show version number
-o DIR --output=DIR set directory to contain all output files (default "./phybin_out/")
--selftest run internal unit tests
----------------------------- Clustering Options ------------------------------
--bin Use simple binning, the cheapest form of 'clustering'
--single Use single-linkage clustering (nearest neighbor)
--complete Use complete-linkage clustering (furthest neighbor)
--UPGMA Use Unweighted Pair Group Method (average linkage) - DEFAULT mode
--editdist=DIST Combine all clusters separated by DIST or less. Report a flat list of clusters.
Irrespective of whether this is activated, a hierarchical clustering (dendogram.pdf) is produced.
Select Robinson-Foulds (symmetric difference) distance algorithm:
--simple use direct all-to-all comparison
--hashrf (default) use a variant of the HashRF algorithm for the distance matrix
----------------------------- Visualization --------------------------------
-g --graphbins use graphviz to produce .dot and .pdf output files
-d --drawbins like -g, but open GUI windows to show each bin's tree
-w --view for convenience, "view mode" simply displays input Newick files without binning
--showtrees Print (textual) tree topology inside the nodes of the dendrogram
--highlight=FILE Highlight nodes in the tree-of-trees (dendrogram) consistent with the.
given tree file. Multiple highlights are permitted and use different colors.
--interior Show the consensus trees for interior nodes in the dendogram, rather than just points.
---------------------------- Tree pre-processing -----------------------------
-n NUM --numtaxa=NUM expect NUM taxa for this dataset
-b LEN --branchcut=LEN collapse branches less than LEN
--------------------------- Extracting taxa names ----------------------------
-p NUM --nameprefix=NUM Leaf names in the input Newick trees can be gene names, not taxa.
Then it is typical to extract taxa names from genes. This option extracts
a prefix of NUM characters to serve as the taxa name.
-s STR --namesep=STR An alternative to --nameprefix, STR provides a set of delimeter characters,
for example '-' or '0123456789'. The taxa name is then a variable-length
prefix of each gene name up to but not including any character in STR.
-m FILE --namemap=FILE Even once prefixes are extracted it may be necessary to use a lookup table
to compute taxa names, e.g. if multiple genes/plasmids map onto one taxa.
This option specifies a text file with find/replace entries of the form
"<string> <taxaname>", which are applied AFTER -s and -p.
--------------------------- Utility Modes ----------------------------
--rfdist print a Robinson Foulds distance matrix for the input trees
--setdiff for convenience, print the set difference between cluster*.txt files
--print simply print out a concise form of each input tree
--printnorms simply print out a concise and NORMALIZED form of each input tree
--consensus print a strict consensus tree for the inputs, then exit
--matching print a list of tree names that match any --highlight argument
Authors: Irene and Ryan Newton
Contact email: irnewton and rrnewton at indiana edu (with "at" and "dot" inserted).