search

SimonGreenhill / treemaker

A Python library for creating a Newick formatted tree from a set of classification strings
BSD 3-Clause "New" or "Revised" License
8 stars 2 forks source link
classification newick newick-format phylogenetics python taxonomy

readme

treemaker

A Python library for creating a Newick formatted tree from a set of classification strings (e.g. a taxonomy)

Build Status Coverage Status DOI status

treemaker is a Python library to convert a text-based classification schema into a Newick file for use in phylogenetic and bioinformatic programs.

Research in linguistics or cultural evolution often produces or uses tree taxonomies or classifications. However, these are usually not in a format readily available for use in programs that can understand and manipulate trees. For example, the global taxonomy of languages published by the Ethnologue classifies languages into families and subgroups using a taxonomy string e.g. the language Kalam is classified as "Trans-New Guinea, Madang, Kalam-Kobon", while Mauwake is classified as "Trans-New Guinea, Madang, Croisilles, Pihom", and Kare is "Trans-New Guinea, Madang, Croisilles, Kare". This classification indicates that while all these languages are part of the Madang subgroup of the Trans-New Guinea language family, Kare and Mauwake are more closely related (as they belong to the Croisilles subgroup).

Other publications use a tabular indented format to demarcate relationships, such as the example in Figure 1 from Stephen Wurm's classification of his proposed Yele-Solomons language phylum (Wurm 1975).

Both the taxonomy string and tabular format however are hard to load into software packages that can analyse, compare, visualise and manipulate trees. treemaker aims to make this easy by converting taxonomic data into Newick and Nexus (Maddison 1997) formats commonly used by phylogenetic manipulation programs.

Converting a Taxonomy to a Tree:

treemaker can convert a text file with a taxonomy to a tree. These taxonomies can easily be obtained from Ethnologue or manually entered, such as this example from Wurm's (outdated) classification of Yele-Solomons in Figure 1:

Bilua       Yele-Solomons, Central Solomon
Baniata     Yele-Solomons, Central Solomon
Lavukaleve  Yele-Solomons, Central Solomon
Savosavo    Yele-Solomons, Central Solomon
Kazukuru    Yele-Solomons, Kazukuru
Guliguli    Yele-Solomons, Kazukuru
Dororo      Yele-Solomons, Kazukuru
Yele        Yele-Solomons

treemaker can then generate a Newick representation:

((Baniata,Bilua,Lavukaleve,Savosavo),(Dororo,Guliguli,Kazukuru),Yele);

...which can then be loaded into phylogenetic programs to visualise or manipulate as in Figure 2.

treemaker has been used to enable the analyses in (Bromham et al. 2018), and a number of forthcoming articles.

Example of a language taxonomy in indented format from Wurm (1975).

Tree visualisation of the relationships between the putative Yele-Solomons languages.

Installation:

Installation is only a pip install away:

pip install treemaker

Or from git:

git clone https://github.com/SimonGreenhill/treemaker/ treemaker
cd treemaker
python setup.py install

Usage: Command line:

Basic usage: 

> treemaker

usage: treemaker [-h] [-o OUTPUT] [-m {nexus,newick}] [--labels] input

e.g. Given a text file:

LangA   Indo-European, Germanic
LangB   Indo-European, Germanic
LangC   Indo-European, Romance
LangD   Indo-European, Anatolian

... then you can build a taxonomy/classification tree from that as follows:

> treemaker classification.txt
(LangD,(LangA,LangB),LangC);

# with nodelabels:
> treemaker --labels classification.txt
(LangD,(LangA,LangB)Germanic,LangC)Indo-European;

> treemaker -m nexus classification.txt

#NEXUS

begin trees;
   tree root = (LangD,(LangA,LangB),LangC);
end;

To write to file:

> treemaker classification.txt
(LangD,(LangA,LangB),LangC);

> treemaker classification.txt -o classification.nex

Usage: Library:

from treemaker import TreeMaker

generate a tree manually:

from treemaker import TreeMaker

t = TreeMaker()
t.add('A1', 'family a, subgroup 1')
t.add('A2', 'family a, subgroup 2')
t.add('B1a', 'family b, subgroup 1')
t.add('B1b', 'family b, subgroup 1')
t.add('B2', 'family b, subgroup 2')

print(t.write())

Add from a list:

from treemaker import TreeMaker

taxa = [
    ('A1', 'family a, subgroup 1'),
    ('A2', 'family a, subgroup 2'),
    ('B1a', 'family b, subgroup 1'),
    ('B1b', 'family b, subgroup 1'),
    ('B2', 'family b, subgroup 2'),
]

t = TreeMaker()
t.add_from(taxa)

print(t.write())

API Documentation:

The API is documented here.

Running treemaker's tests:

To run treemaker's tests simply run:

> make test
# or
> python setup.py test
# or
> python treemaker/test_treemaker.py

Version History:

Support:

For questions on how to use or update this, feel free to open an issue. I'll get to it as soon as I can.

Acknowledgements:

Thank you to Richard Littauer, Mitsuhiro Nakamura, and Dillon Niederhut.

References: