search

evolbioinfo / gotree

Gotree is a set of command line tools and an API to manipulate phylogenetic trees. It is implemented in Go language.
GNU General Public License v2.0
120 stars 15 forks source link
gotree itol newick nexus phylogeny tree tree-structure

readme

Gotree

build Anaconda-Server Badge Docker hub downloads DOI:10.1093/nargab/lqab075

Gotree Logo

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

Gotree handles phylogenetic trees in Newick, Nexus, PhyloXML and Nextstrain/Augur v2 formats, 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.

Input files may be local or remote files:

Gzipped input files (.gz extension) are supported.

Note:

To manipulate multiple alignments, See also Goalign.

Examples:

$ echo "(1,(2,(3,4,5,6)polytomy)internal)root;" | gotree draw text --with-node-labels -w 50
+--------------- 1                                          
|                                                           
root            +---------------- 2                         
|               |                                           
+---------------|internal        +--------------- 3         
                |                |                          
                |                |--------------- 4         
                +----------------|polytomy                  
                                 |--------------- 5         
                                 |                          
                                 +--------------- 6         

$ echo "(1,(2,(3,4,5,6)polytomy)internal)root;" | gotree labels --internal --tips
root
1
internal
2
polytomy
3
4
5
6
$ gotree generate uniformtree -l 100 -n 10 | gotree stats

|tree  |  nodes  |  tips  |  edges  |  meanbrlen   |  sumbrlen     |  meansupport  |  mediansupport  |  rooted    |
|------|---------|--------|---------|--------------|---------------|---------------|-----------------|------------|
|0     |  198    |  100   |  197    |  0.09029828  |  17.78876078  |  NaN          |  NaN            |  unrooted  |
|1     |  198    |  100   |  197    |  0.08391711  |  16.53167037  |  NaN          |  NaN            |  unrooted  |
|2     |  198    |  100   |  197    |  0.08369861  |  16.48862662  |  NaN          |  NaN            |  unrooted  |
|3     |  198    |  100   |  197    |  0.08652623  |  17.04566698  |  NaN          |  NaN            |  unrooted  |
|4     |  198    |  100   |  197    |  0.07970206  |  15.70130625  |  NaN          |  NaN            |  unrooted  |
|5     |  198    |  100   |  197    |  0.09145831  |  18.01728772  |  NaN          |  NaN            |  unrooted  |
|6     |  198    |  100   |  197    |  0.08482117  |  16.70977068  |  NaN          |  NaN            |  unrooted  |
|7     |  198    |  100   |  197    |  0.08470308  |  16.68650662  |  NaN          |  NaN            |  unrooted  |
|8     |  198    |  100   |  197    |  0.08646811  |  17.03421732  |  NaN          |  NaN            |  unrooted  |
|9     |  198    |  100   |  197    |  0.07088132  |  13.96362091  |  NaN          |  NaN            |  unrooted  |

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

Reference

If you use Gotree or Goalign, please cite:

Frédéric Lemoine, Olivier Gascuel

Gotree/Goalign: toolkit and Go API to facilitate the development of phylogenetic workflows,

NAR Genomics and Bioinformatics, Volume 3, Issue 3, September 2021, lqab075, doi

Installation

Easy way: Binaries

You can download ready to run 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.

Docker

Gotree Docker image is accessible from docker hub. You may use it as following:

# Display gotree help
docker run -v $PWD:$PWD -w $PWD -i -t evolbioinfo/gotree:v0.2.8b -h

Singularity

Gotree Docker image is usable from singularity . You may use it as following:

# Pull image from docker hub
singularity pull docker://evolbioinfo/gotree:v0.2.8b
# Display gotree help
./gotree-v0.2.8b.simg -h

Conda

Gotree is also available on bioconda. Just type:

conda install -c bioconda gotree

From sources

To build gotree, you must first download and install Go on your system ($1.21.6$).

Then you just have to type :

git clone git@github.com:evolbioinfo/gotree.git
cd gotree
make && make install
# or go get . && go build .
# or go get . && go install .

The gotree executable should be located in the current folder (or the $GOPATH/bin).

To test the executable:

./test.sh

Auto completion

gotree uses cobra, and therefore proposes a command to generate auto completion scripts:

gotree completion -h

Usage

gotree implements several tree manipulation commands.

You may go to the doc for a more detailed documentation of the commands.

List of commands

Gotree commandline examples

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

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

Example:

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

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

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.

$ 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 reference common compared
0 97 0 97 
$ 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

import ( "fmt" "strings"

"github.com/evolbioinfo/gotree/io/newick"
"github.com/evolbioinfo/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
```go
package main

import (
    "fmt"
    "os"

    "github.com/evolbioinfo/gotree/io/newick"
    "github.com/evolbioinfo/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())
}

import ( "bufio" "fmt" "io"

"github.com/evolbioinfo/gotree/io/utils"
"github.com/evolbioinfo/gotree/tree"

)

func main() { var t tree.Trees var err error var ntrees int = 0 var trees <-chan tree.Trees var treefile io.Closer 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()
// format may be FORMAT_NEWICK, FORMAT_NEXUS, FORMAT_PHYLOXML
trees = utils.ReadMultiTrees(treereader, utils.FORMAT_NEWICK)
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
```go
// 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 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()