.TH PHYBIN "1" "December 2015" "phybin 0.3" "User Commands"
.SH NAME
phybin \- binning/clustering newick trees by topology
.SH SYNOPSIS
.B phybin
[\fI\,OPTION\/\fR...] \fI\,files or directories\/\fR...
.SH DESCRIPTION
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:
.IP
e.g. FILENAME_0, FILENAME_1, etc.
.PP
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.
.PP
Binning mode provides an especially quick\-and\-dirty form of clustering.
When running with the \fB\-\-bin\fR option, only exactly equal trees are put in the same cluster.
Tree pre\-processing still applies, however: for example collapsing short branches.
.SS "USAGE NOTES:"
.PP
* Currently phybin ignores input trees with the wrong number of taxa.
.PP
* If given a directory as input phybin will assume all contained files are Newick trees.
.SH OPTIONS
.TP
\fB\-v\fR       \fB\-\-verbose\fR
print WARNINGS and other information (recommended at first)
.TP
\fB\-V\fR       \fB\-\-version\fR
show version number
.TP
\fB\-o\fR DIR   \fB\-\-output\fR=\fI\,DIR\/\fR
set directory to contain all output files (default "./phybin_out/")
.TP
\fB\-\-selftest\fR
run internal unit tests
.SS Clustering Options
.TP
\fB\-\-bin\fR
Use simple binning, the cheapest form of 'clustering'
.TP
\fB\-\-single\fR
Use single\-linkage clustering (nearest neighbor)
.TP
\fB\-\-complete\fR
Use complete\-linkage clustering (furthest neighbor)
.TP
\fB\-\-UPGMA\fR
Use Unweighted Pair Group Method (average linkage) \- DEFAULT mode
.TP
\fB\-\-editdist\fR=\fI\,DIST\/\fR
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.
.SS Select Robinson\-Foulds (symmetric difference) distance algorithm:
.TP
\fB\-\-hashrf\fR
(default) use a variant of the HashRF algorithm for the distance matrix
.TP
\fB\-\-tolerant\fR
use a slower, modified RF metric that tolerates missing taxa
.SS Visualization
.TP
\fB\-g\fR       \fB\-\-graphbins\fR
use graphviz to produce .dot and .pdf output files
.TP
\fB\-d\fR       \fB\-\-drawbins\fR
like \fB\-g\fR, but open GUI windows to show each bin's tree
.TP
\fB\-w\fR       \fB\-\-view\fR
for convenience, "view mode" simply displays input Newick files without binning
.TP
\fB\-\-showtrees\fR
Print (textual) tree topology inside the nodes of the dendrogram
.TP
\fB\-\-highlight\fR=\fI\,FILE\/\fR
Highlight nodes in the tree\-of\-trees (dendrogram) consistent with the.
given tree file.  Multiple highlights are permitted and use different colors.
.TP
\fB\-\-interior\fR
Show the consensus trees for interior nodes in the dendogram, rather than just points.
.SS Tree pre\-processing
.TP
\fB\-\-prune\fR=\fI\,TAXA\/\fR
Prune trees to only TAXA before doing anything else.
Space and comma separated lists of taxa are allowed.  Use quotes.
.TP
\fB\-b\fR LEN   \fB\-\-minbranchlen\fR=\fI\,LEN\/\fR
collapse branches less than LEN
.TP
\fB\-\-minbootstrap\fR=\fI\,INT\/\fR
collapse branches with bootstrap values less than INT
.SS Extracting taxa names
.TP
\fB\-p\fR NUM   \fB\-\-nameprefix\fR=\fI\,NUM\/\fR
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.
.TP
\fB\-s\fR STR   \fB\-\-namesep\fR=\fI\,STR\/\fR
An alternative to \fB\-\-nameprefix\fR, 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.
.TP
\fB\-m\fR FILE  \fB\-\-namemap\fR=\fI\,FILE\/\fR
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 \fB\-s\fR and \fB\-p\fR.
.SS Utility Modes
.TP
\fB\-\-rfdist\fR
print a Robinson Foulds distance matrix for the input trees
.TP
\fB\-\-setdiff\fR
for convenience, print the set difference between cluster*.txt files
.TP
\fB\-\-print\fR
simply print out a concise form of each input tree
.TP
\fB\-\-printnorms\fR
simply print out a concise and NORMALIZED form of each input tree
.TP
\fB\-\-consensus\fR
print a strict consensus tree for the inputs, then exit
.TP
\fB\-\-matching\fR
print a list of tree names that match any \fB\-\-highlight\fR argument
.SH AUTHOR
This manpage was written by Andreas Tille for the Debian distribution and can be used for any other usage of the program.