gotree

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 be piped to the standard input of the next gotree command.

See also Goalign for handling multiple alignments.

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:

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.

You may go to the doc for a more detailed documentation of the 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
  • bipartitiontree: Builds one tree with only one given bipartition
  • 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
• draw: Draw tree(s) with different layouts
  • text: Display tree(s) in ASCII text format
  • png : Draw tree(s) in png format, with normal, radial/unrooted or circular layout
  • svg : Draw tree(s) in svg format, with normal, radial/unrooted or circular layout
• 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
• subtree: extract a subtree
• 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

Gotree commandline examples

• Generate 10 random unrooted uniform binary trees

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

• Generate 1 Yule-Harding tree with 50 tips, and display it on the terminal (width 100)

$ gotree generate yuletree -l 50 | gotree draw text -w 100

• Generate 1 tree with 50 tips, and draw it on a SVG image

$ gotree generate yuletree -l 50 | gotree draw svg -w 1000 -H 1000 -o tree.svg
$ gotree generate yuletree -l 50 | gotree draw svg -w 1000 -H 1000 -r -o tree_radial.svg

• 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

• Removing length information

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

• Removing 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:

• Printing tips

$ gotree stats tips -i tree.tre

Example of result:

• 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)

• 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

Gotree api usage examples

• Parsing a newick string

package main

import (
	"fmt"
	"strings"

	"github.com/fredericlemoine/gotree/io/newick"
	"github.com/fredericlemoine/gotree/tree"
)

func main() {
	var treeString string
	var t *tree.Tree
	var err error
	treeString = "(Tip2,Tip0,(Tip3,(Tip4,Tip1)));"
	t, err = newick.NewParser(strings.NewReader(treeString)).Parse()
	if err != nil {
		panic(err)
	}
	fmt.Println(t.Newick())
}

• Parsing a newick file

package main

import (
	"fmt"
	"os"

	"github.com/fredericlemoine/gotree/io/newick"
	"github.com/fredericlemoine/gotree/tree"
)

func main() {

	var t *tree.Tree
	var err error
	var f *os.File
	if f, err = os.Open("t.nw"); err != nil {
		panic(err)
	}
	t, err = newick.NewParser(f).Parse()
	if err != nil {
		panic(err)
	}
	fmt.Println(t.Newick())
}

• Helper functions to parse multi tree newick file

package main

import (
	"bufio"
	"fmt"
	"os"

	"github.com/fredericlemoine/gotree/io/utils"
	"github.com/fredericlemoine/gotree/tree"
)

func main() {
	var t tree.Trees
	var err error
	var ntrees int = 0
	var trees <-chan tree.Trees
	var treefile *os.File
	var treereader *bufio.Reader

	/* File reader (plain text or gzip) */
	if treefile, treereader, err = utils.GetReader("trees.nw"); err != nil {
		panic(err)
	}
	defer treefile.Close()
	trees = utils.ReadMultiTrees(treereader)

	for t = range trees {
		if t.Err != nil {
			panic(t.Err)
		}
		ntrees++
		fmt.Println(t.Tree.Newick())
	}
	fmt.Printf("Number of trees: %d\n", ntrees)
}

• Tree functions

// Getting edges
var edges []*tree.Edge = t.Edges()
// Internal edges only
var iedges []*tree.Edge = t.InternalEdges()
// Tip edges only
var tedges []*tree.Edge = t.TipEdges()
// Getting Nodes
var nodes []*tree.Node = t.Nodes()
// Tips only
var tips []*tree.Node = t.Tips()
// Getting tips
var tips []*tree.Node = t.Tips()
// Getting tip names
var tipnames []string = t.AllTipNames()
// Root/Pseudoroot node
var root *tree.Node = t.Root()
// If the tree is rooted or not
var rooted bool = t.Rooted()

• Branch functions

// Branch length
var l float64 = e.Length()
// Branch support
var s float64 = e.Support()
// Node on the "right"
var n1 *tree.Node = e.Right()
// Node on the "left"
var n2 *tree.Node = e.Left()
// Number of leaves under this edge
var nt uint = e.NumTips()

• Node functions

// Node name
var n string = n.Name()
// Number of neighbors
var nn int = n.Nneigh()
// List of neighbors (including "parent")
var neighb []*tree.Node = n.Neigh()
// If a node is a tip or not
var tip bool = n.Tip()
// List of branches going from this node (including "parent")
var edges []*tree.Edge = n.Edges()

• Removing tips

if err = t.RemoveTips(false, "Tip0"); err != nil {
	panic(err)
}
fmt.Println(t.Newick())

• Knowning if a tip exists in the tree

var exists bool
var err error
exists,err = t.ExistsTip("Tip0")

• Shuffling tip names of the tree

t.ShuffleTips()

• Removing branches

// Short branches
t.CollapseShortBranches(0.01)
// Lowly supported branches
t.CollapseLowSupport(0.7)
// Branches with "depth" <=10 && >= 1
t.CollapseTopoDepth(1,10)

• Randomly resolving multifurcations

t.Resolve()

• Removing branch informations

// Branch lengths
t.ClearLengths()
// Branch supports
t.ClearSupports()

• Unrooting the tree

t.Unroot()

• Cloning the tree

t.Clone()

• Rerooting at midpoint

t.RerootMidPoint()

• Generating random trees

var ntips int = 100
var rooted bool = true
// Uniform tree
t,err = tree.RandomUniformBinaryTree(ntips, rooted)
// Balanced tree
t,err = tree.RandomBalancedBinaryTree(ntips, rooted)
// Yule-Harding tree
t,err = tree.RandomYuleBinaryTree(ntips, rooted)

• Computing bootstrap supports from tree files

import "github.com/fredericlemoine/gotree/support"
...
var cpus int = 1
boottree,err := support.ClassicalFile("referencetreefile", "bootstraptreesfile", cpus)

• SVG Tree drawing

import "github.com/fredericlemoine/gotree/draw"
...
f, err := os.Create("image.svg")
d = draw.NewSvgTreeDrawer(f, 800, 800, 30, 30, 30, 30)
l = draw.NewRadialLayout(d, false, false, false, false)
// or l = draw.NewCircularLayout(d, false, false, false, false)
// or l = draw.NewNormalLayout(d, false, false, false, false)
l.DrawTree(t)
f.Close()

• PNG Tree drawing

import "github.com/fredericlemoine/gotree/draw"
...
f, err := os.Create("image.svg")
d = draw.NewPngTreeDrawer(f, 800, 800, 30, 30, 30, 30)
l = draw.NewRadialLayout(d, false, false, false, false)
// or l = draw.NewCircularLayout(d, false, false, false, false)
// or l = draw.NewNormalLayout(d, false, false, false, false)
l.DrawTree(t)
f.Close()