gotree

README

GoTree

GoTree is a set of command line tools to manipulate phylogenetic trees. It is implemented in Go language.

The goal is to handle phylogenetic trees in Newick format, through several basic commands. Each command may print result (a tree for example) in the standard output, and thus can piped to the standard input of the next gotree command.

Example:

$ gotree generate uniformtree -l 100 -n 10 | gotree stats

This will generate 10 random unrooted uniform binary trees, each having 100 tips, and print statistics about them, for example:

tree	nodes	tips	edges	meanbrlen	meansupport	mediansupport	rooted
0	198	100	197	0.0821	-1.0000	-1.0000	unrooted
1	198	100	197	0.0898	-1.0000	-1.0000	unrooted
2	198	100	197	0.0765	-1.0000	-1.0000	unrooted
3	198	100	197	0.0746	-1.0000	-1.0000	unrooted
4	198	100	197	0.0846	-1.0000	-1.0000	unrooted
5	198	100	197	0.0784	-1.0000	-1.0000	unrooted
6	198	100	197	0.0884	-1.0000	-1.0000	unrooted
7	198	100	197	0.0943	-1.0000	-1.0000	unrooted
8	198	100	197	0.0885	-1.0000	-1.0000	unrooted
9	198	100	197	0.0839	-1.0000	-1.0000	unrooted

Installation

Binaries

You can download already compiled binaries for the latest release in the release section. Binaries are available for MacOS, Linux, and Windows (32 and 64 bits).

Once downloaded, you can just run the executable without any other downloads.

From sources

In order to compile gotree, you must first download and install Go on your system.

Then you just have to type :

go get github.com/fredericlemoine/gotree/

This will download GoTree sources from github, and all its dependencies.

You can then build it with:

cd $GOPATH/src/github.com/fredericlemoine/gotree/
make

The gotree executable should be located in the $GOPATH/bin folder.

Usage

gotree implements several tree manipulation commands.

List of commands

• annotate: Annotate internal nodes of a tree with given data
• clear: Clear lengths or supports from input trees
  • lengths
  • supports
• collapse: Collapse branches of input trees
  • depth
  • length
  • support
• compare: Compare full trees, edges, or tips
  • edges: Individually compare edges of the reference tree to a compared tree
  • tips: Compare the set of tips of the reference tree to a compared tree
  • trees: Compare 2 trees in terms of common and specific branches
• compute: Computations such as consensus and supports
  • consensus: Compute the consensus from a set of input trees
  • edgetrees: Write one output tree per branch of the input tree, with only one branch
  • support: Compute bootstrap supports
    • classical
    • booster
• divide: Divide an input tree file into several tree files
• dlimage: Download a tree image from a server
  • itol: download a tree image from iTOL, with given image options
• generate: Generate random trees, branch lengths are simply drawn from an expontential(1) law
  • balancedtree
  • caterpillartree
  • uniformtree
  • yuletree
• matrix: Print distance matrix associated to the input tree
• minbrlen: Set a minimum branch length to all branches with length < cutoff
• prune: Remove tips of the input tree that are not in the compared tree, or that are given on the command line
• randbrlen: Assign a random length to edges of input trees
• randsupport: Assign a random support to edges of input trees
• rename: Rename tips of the input tree, given a map file
• reroot: Reroot trees using an outgroup or at midpoint
  • midpoint
  • outgroup
• resolve: Resolve multifurcations by adding 0 length branches
• shuffletips: Shuffle tip names of an input tree
• stats: Print statistics about the tree, its edges, its nodes, if it is rooted, and its tips
  • edges
  • nodes
  • rooted
  • tips
  • splits
• unroot: Unroot input tree
• upload: Upload a tree to a given server
  • itol : Upload a tree to itol, with given annotations
• version: Display version of gotree

Examples

• Generate random unrooted uniform binary trees

$ gotree generate uniformtree -l 100 -n 10 | gotree stats

• Unrooting a tree

$ gotree unroot -i tree.tre -o unrooted.tre

• Collapsing short branches

$ gotree collapse length -i tree.tre -l 0.001 -o collapsed.tre

• Collapsing lowly supported branches

$ gotree collapse support -i tree.tre -s 0.8 -o collapsed.tre

• Clearing length information

$ gotree clear lengths -i tree.nw -o nolength.nw

• Clearing support information

$ gotree clear supports -i tree.nw -o nosupport.nw

Note that you can pipe the two previous commands:

$ gotree clear supports -i tree.nw | gotree clear lengths -o nosupport.nw

• Printing tree statistics

$ gotree stats -i tree.tre

• Printing edge statistics

$ gotree stats edges -i tree.tre

Example of result:

tree	brid	length	support	terminal	depth	topodepth	rightname
0	0	0.107614	N/A	false	1	6
0	1	0.149560	N/A	true	0	1	Tip51
0	2	0.051126	N/A	false	1	5
0	3	0.003992	N/A	false	1	4
0	4	0.030974	N/A	false	1	3
0	5	0.270017	N/A	true	0	1	Tip84
0	6	0.029931	N/A	false	1	2
0	7	0.001136	N/A	true	0	1	Tip70
0	8	0.011658	N/A	true	0	1	Tip45
0	9	0.104188	N/A	true	0	1	Tip34
0	10	0.003361	N/A	true	0	1	Tip16
0	11	0.021988	N/A	true	0	1	Node0

• Printing tips

$ gotree stats tips -i tree.tre

Example of result:

tree	id	nneigh	name
0	1	1	Tip8
0	2	1	Node0
0	5	1	Tip4
0	8	1	Tip9
0	9	1	Tip7
0	11	1	Tip6
0	13	1	Tip5
0	14	1	Tip3
0	16	1	Tip2
0	17	1	Tip1

• Comparing tips of two trees

$ gotree compare tips -i tree.tre -c tree2.tre

This will compare the two sets of tips.

Example:

$ gotree compare tips -i <(gotree generate uniformtree -l 10 -n 1) \
                      -c <(gotree generate uniformtree -l 11 -n 1)
> Tip10
= 10

10 tips are equal, and "Tip10" is present only in the second tree.

• Removing tips that are absent from another tree

$ gotree prune -i tree.tre -c other.tre -o pruned.tre

You can test with

$ gotree prune -i <(gotree generate uniformtree -l 1000 -n 1) \
               -c <(gotree generate uniformtree -l 100 -n 1) \
               | gotree stats

It should print 100 tips.

• Comparing bipartitions Count the number of common/specific bipartitions between two trees.

$ gotree compare trees -i tree.tre -c other.tre

You can test with random trees (there should be very few common bipartitions)

$ gotree compare trees -i <(gotree generate uniformtree -l 100 -n 1) \
                       -c <(gotree generate uniformtree -l 100 -n 1)

Tree	specref	common
0	97	0

• Renaming tips of the tree If you have a file containing the mapping between current names and new names of the tips, you can rename the tips:

$ gotree rename -i tree.tre -m mapfile.txt -o newtree.tre

You can try by doing:

$ gotree generate uniformtree -l 100 -n 1 -o tree.tre
$ gotree stats tips -i tree.tre | awk '{if(NR>1){print $4 "\tNEWNAME" $4}}' > mapfile.txt
$ gotree rename -i tree.tre -m mapfile.txt | gotree stats tips