The Bio.Phylo module was introduced in Biopython 1.54. Following thelead of SeqIO and AlignIO, it aims to provide a common way to work withphylogenetic trees independently of the source data format, as well as aconsistent API for I/O operations.
Bio.Phylo is described in an open-access journal articleTalevich et al. 2012 [Talevich2012], which you might also findhelpful.
Demo: What’s in a Tree?
To get acquainted with the module, let’s start with a tree that we’vealready constructed, and inspect it a few different ways. Then we’llcolorize the branches, to use a special phyloXML feature, and finallysave it.
Create a simple Newick file named simple.dnd
using your favoritetext editor, or usesimple.dndprovided with the Biopython source code:
(((A,B),(C,D)),(E,F,G));
This tree has no branch lengths, only a topology and labeled terminals.(If you have a real tree file available, you can follow this demo usingthat instead.)
Launch the Python interpreter of your choice:
$ ipython -pylab
For interactive work, launching the IPython interpreter with the-pylab
flag enables matplotlib integration, so graphics will popup automatically. We’ll use that during this demo.
Now, within Python, read the tree file, giving the file name and thename of the format.
>>> from Bio import Phylo>>> tree = Phylo.read("simple.dnd", "newick")
Printing the tree object as a string gives us a look at the entireobject hierarchy.
>>> print(tree)Tree(rooted=False, weight=1.0) Clade() Clade() Clade() Clade(name='A') Clade(name='B') Clade() Clade(name='C') Clade(name='D') Clade() Clade(name='E') Clade(name='F') Clade(name='G')
The Tree
object contains global information about the tree, such aswhether it’s rooted or unrooted. It has one root clade, and under that,it’s nested lists of clades all the way down to the tips.
The function draw_ascii
creates a simple ASCII-art (plain text)dendrogram. This is a convenient visualization for interactiveexploration, in case better graphical tools aren’t available.
>>> from Bio import Phylo>>> tree = Phylo.read("simple.dnd", "newick")>>> Phylo.draw_ascii(tree) ________________________ A ________________________| | |________________________ B ________________________| | | ________________________ C | |________________________|_| |________________________ D | | ________________________ E | | |________________________|________________________ F | |________________________ G
If you have matplotlib or pylab installed, you can create agraphical tree using the draw
function.
>>> tree.rooted = True
>>> Phylo.draw(tree)
See Fig. 6.
Coloring branches within a tree
The function draw
supports the display of different colors andbranch widths in a tree. As of Biopython 1.59, the color
andwidth
attributes are available on the basic Clade object and there’snothing extra required to use them. Both attributes refer to the branchleading the given clade, and apply recursively, so all descendentbranches will also inherit the assigned width and color values duringdisplay.
In earlier versions of Biopython, these were special features ofPhyloXML trees, and using the attributes required first converting thetree to a subclass of the basic tree object called Phylogeny, from theBio.Phylo.PhyloXML module.
In Biopython 1.55 and later, this is a convenient tree method:
>>> tree = tree.as_phyloxml()
In Biopython 1.54, you can accomplish the same thing with one extraimport:
>>> from Bio.Phylo.PhyloXML import Phylogeny>>> tree = Phylogeny.from_tree(tree)
Note that the file formats Newick and Nexus don’t support branch colorsor widths, so if you use these attributes in Bio.Phylo, you will only beable to save the values in PhyloXML format. (You can still save a treeas Newick or Nexus, but the color and width values will be skipped inthe output file.)
Now we can begin assigning colors. First, we’ll color the root cladegray. We can do that by assigning the 24-bit color value as an RGBtriple, an HTML-style hex string, or the name of one of the predefinedcolors.
>>> tree.root.color = (128, 128, 128)
Or:
Or:
>>> tree.root.color = "gray"
Colors for a clade are treated as cascading down through the entireclade, so when we colorize the root here, it turns the whole tree gray.We can override that by assigning a different color lower down on thetree.
Let’s target the most recent common ancestor (MRCA) of the nodes named“E” and “F”. The common_ancestor
method returns a reference to thatclade in the original tree, so when we color that clade “salmon”, thecolor will show up in the original tree.
>>> mrca = tree.common_ancestor({"name": "E"}, {"name": "F"})>>> mrca.color = "salmon"
If we happened to know exactly where a certain clade is in the tree, interms of nested list entries, we can jump directly to that position inthe tree by indexing it. Here, the index [0,1]
refers to the secondchild of the first child of the root.
>>> tree.clade[0, 1].color = "blue"
Finally, show our work:
>>> Phylo.draw(tree)
See Fig. 7.
Note that a clade’s color includes the branch leading to that clade, aswell as its descendents. The common ancestor of E and F turns out to bejust under the root, and with this coloring we can see exactly where theroot of the tree is.
My, we’ve accomplished a lot! Let’s take a break here and save our work.Call the write
function with a file name or handle — here we usestandard output, to see what would be written — and the formatphyloxml
. PhyloXML saves the colors we assigned, so you can openthis phyloXML file in another tree viewer like Archaeopteryx, and thecolors will show up there, too.
>>> import sys>>> n = Phylo.write(tree, sys.stdout, "phyloxml") <phyloxml ...> <phylogeny rooted="true"> <clade> <color> <red>128</red> <green>128</green> <blue>128</blue> </color> <clade> <clade> <clade> <name>A</name> </clade> <clade> <name>B</name> </clade> </clade> <clade> <color> <red>0</red> <green>0</green> <blue>255</blue> </color> <clade> <name>C</name> </clade> ... </clade> </phylogeny></phyloxml>>>> n1
The rest of this chapter covers the core functionality of Bio.Phylo ingreater detail. For more examples of using Bio.Phylo, see the cookbookpage on Biopython.org:
http://biopython.org/wiki/Phylo_cookbook
I/O functions
Like SeqIO and AlignIO, Phylo handles file input and output through fourfunctions: parse
, read
, write
and convert
, all of whichsupport the tree file formats Newick, NEXUS, phyloXML and NeXML, as wellas the Comparative Data Analysis Ontology (CDAO).
The read
function parses a single tree in the given file and returnsit. Careful; it will raise an error if the file contains more than onetree, or no trees.
>>> from Bio import Phylo>>> tree = Phylo.read("Tests/Nexus/int_node_labels.nwk", "newick")>>> print(tree) Tree(rooted=False, weight=1.0) Clade(branch_length=75.0, name='gymnosperm') Clade(branch_length=25.0, name='Coniferales') Clade(branch_length=25.0) Clade(branch_length=10.0, name='Tax+nonSci') Clade(branch_length=90.0, name='Taxaceae') Clade(branch_length=125.0, name='Cephalotaxus') ...
(Example files are available in the Tests/Nexus/
andTests/PhyloXML/
directories of the Biopython distribution.)
To handle multiple (or an unknown number of) trees, use the parse
function iterates through each of the trees in the given file:
>>> trees = Phylo.parse("Tests/PhyloXML/phyloxml_examples.xml", "phyloxml")>>> for tree in trees:... print(tree) ...Phylogeny(description='phyloXML allows to use either a "branch_length" attribute...', name='example from Prof. Joe Felsenstein's book "Inferring Phyl...', rooted=True) Clade() Clade(branch_length=0.06) Clade(branch_length=0.102, name='A') ...
Write a tree or iterable of trees back to file with the write
function:
>>> trees = Phylo.parse("Tests/PhyloXML/phyloxml_examples.xml", "phyloxml")>>> tree1 = next(trees)>>> Phylo.write(tree1, "tree1.nwk", "newick")1>>> Phylo.write(trees, "other_trees.xml", "phyloxml") # write the remaining trees12
Convert files between any of the supported formats with the convert
function:
>>> Phylo.convert("tree1.nwk", "newick", "tree1.xml", "nexml")1>>> Phylo.convert("other_trees.xml", "phyloxml", "other_trees.nex", "nexus")12
To use strings as input or output instead of actual files, useStringIO
as you would with SeqIO and AlignIO:
>>> from Bio import Phylo>>> from io import StringIO>>> handle = StringIO("(((A,B),(C,D)),(E,F,G));")>>> tree = Phylo.read(handle, "newick")
View and export trees
The simplest way to get an overview of a Tree
object is to print
it:
>>> from Bio import Phylo>>> tree = Phylo.read("PhyloXML/example.xml", "phyloxml")>>> print(tree)Phylogeny(description='phyloXML allows to use either a "branch_length" attribute...', name='example from Prof. Joe Felsenstein's book "Inferring Phyl...', rooted=True) Clade() Clade(branch_length=0.06) Clade(branch_length=0.102, name='A') Clade(branch_length=0.23, name='B') Clade(branch_length=0.4, name='C')
This is essentially an outline of the object hierarchy Biopython uses torepresent a tree. But more likely, you’d want to see a drawing of thetree. There are three functions to do this.
As we saw in the demo, draw_ascii
prints an ascii-art drawing of thetree (a rooted phylogram) to standard output, or an open file handle ifgiven. Not all of the available information about the tree is shown, butit provides a way to quickly view the tree without relying on anyexternal dependencies.
>>> tree = Phylo.read("PhyloXML/example.xml", "phyloxml")>>> Phylo.draw_ascii(tree) __________________ A __________|_| |___________________________________________ B | |___________________________________________________________________________ C
The draw
function draws a more attractive image using the matplotliblibrary. See the API documentation for details on the arguments itaccepts to customize the output.
>>> Phylo.draw(tree, branch_labels=lambda c: c.branch_length)
See Fig. 8 for example.
See the Phylo page on the Biopython wiki(http://biopython.org/wiki/Phylo) for descriptions and examples of themore advanced functionality in draw_ascii
, draw_graphviz
andto_networkx
.
Using Tree and Clade objects
The Tree
objects produced by parse
and read
are containersfor recursive sub-trees, attached to the Tree
object at the root
attribute (whether or not the phylogenetic tree is actually consideredrooted). A Tree
has globally applied information for the phylogeny,such as rootedness, and a reference to a single Clade
; a Clade
has node- and clade-specific information, such as branch length, and alist of its own descendent Clade
instances, attached at theclades
attribute.
So there is a distinction between tree
and tree.root
. Inpractice, though, you rarely need to worry about it. To smooth over thedifference, both Tree
and Clade
inherit from TreeMixin
,which contains the implementations for methods that would be commonlyused to search, inspect or modify a tree or any of its clades. Thismeans that almost all of the methods supported by tree
are alsoavailable on tree.root
and any clade below it. (Clade
also has aroot
property, which returns the clade object itself.)
Search and traversal methods
For convenience, we provide a couple of simplified methods that returnall external or internal nodes directly as a list:
get_terminals
makes a list of all of this tree’s terminal (leaf) nodes.
get_nonterminals
makes a list of all of this tree’s nonterminal (internal) nodes.
These both wrap a method with full control over tree traversal,find_clades
. Two more traversal methods, find_elements
andfind_any
, rely on the same core functionality and accept the samearguments, which we’ll call a “target specification” for lack of abetter description. These specify which objects in the tree will bematched and returned during iteration. The first argument can be any ofthe following types:
A TreeElement instance, which tree elements will match byidentity — so searching with a Clade instance as the target will findthat clade in the tree;
A string, which matches tree elements’ string representation — inparticular, a clade’s
name
(added in Biopython 1.56);A class or type, where every tree element of the same type(or sub-type) will be matched;
A dictionary where keys are tree element attributes and valuesare matched to the corresponding attribute of each tree element. Thisone gets even more elaborate:
If an
int
is given, it matches numerically equal attributes,e.g. 1 will match 1 or 1.0If a boolean is given (True or False), the corresponding attributevalue is evaluated as a boolean and checked for the same
None
matchesNone
If a string is given, the value is treated as a regular expression(which must match the whole string in the corresponding elementattribute, not just a prefix). A given string without specialregex characters will match string attributes exactly, so if youdon’t use regexes, don’t worry about it. For example, in a treewith clade names Foo1, Foo2 and Foo3,
tree.find_clades({"name": "Foo1"})
matches Foo1,{"name": "Foo.*"}
matches all three clades, and{"name": "Foo"}
doesn’t match anything.
Since floating-point arithmetic can produce some strange behavior, wedon’t support matching
float
s directly. Instead, use thebooleanTrue
to match every element with a nonzero value in thespecified attribute, then filter on that attribute manually with aninequality (or exact number, if you like living dangerously).If the dictionary contains multiple entries, a matching element mustmatch each of the given attribute values — think “and”, not “or”.
A function taking a single argument (it will be applied to eachelement in the tree), returning True or False. For convenience,LookupError, AttributeError and ValueError are silenced, so thisprovides another safe way to search for floating-point values in thetree, or some more complex characteristic.
After the target, there are two optional keyword arguments:
- terminal
— A boolean value to select for or against terminal clades (a.k.a.leaf nodes): True searches for only terminal clades, False fornon-terminal (internal) clades, and the default, None, searches bothterminal and non-terminal clades, as well as any tree elementslacking the
is_terminal
method.- order
— Tree traversal order:
"preorder"
(default) is depth-firstsearch,"postorder"
is DFS with child nodes preceding parents,and"level"
is breadth-first search.
Finally, the methods accept arbitrary keyword arguments which aretreated the same way as a dictionary target specification: keys indicatethe name of the element attribute to search for, and the argument value(string, integer, None or boolean) is compared to the value of eachattribute found. If no keyword arguments are given, then any TreeElementtypes are matched. The code for this is generally shorter than passing adictionary as the target specification:tree.find_clades({"name": "Foo1"})
can be shortened totree.find_clades(name="Foo1")
.
(In Biopython 1.56 or later, this can be even shorter:tree.find_clades("Foo1")
)
Now that we’ve mastered target specifications, here are the methods usedto traverse a tree:
find_clades
Find each clade containing a matching element. That is, find eachelement as with
find_elements
, but return the corresponding cladeobject. (This is usually what you want.)The result is an iterable through all matching objects, searchingdepth-first by default. This is not necessarily the same order as theelements appear in the Newick, Nexus or XML source file!
find_elements
Find all tree elements matching the given attributes, and return thematching elements themselves. Simple Newick trees don’t have complexsub-elements, so this behaves the same as
find_clades
on them.PhyloXML trees often do have complex objects attached to clades, sothis method is useful for extracting those.find_any
Return the first element found by
find_elements()
, or None. Thisis also useful for checking whether any matching element exists inthe tree, and can be used in a conditional.
Two more methods help navigating between nodes in the tree:
get_path
List the clades directly between the tree root (or current clade) andthe given target. Returns a list of all clade objects along thispath, ending with the given target, but excluding the root clade.
trace
List of all clade object between two targets in this tree. Excludingstart, including finish.
Information methods
These methods provide information about the whole tree (or any clade).
common_ancestor
Find the most recent common ancestor of all the given targets. (Thiswill be a Clade object). If no target is given, returns the root ofthe current clade (the one this method is called from); if 1 targetis given, this returns the target itself. However, if any of thespecified targets are not found in the current tree (or clade), anexception is raised.
count_terminals
Counts the number of terminal (leaf) nodes within the tree.
depths
Create a mapping of tree clades to depths. The result is a dictionarywhere the keys are all of the Clade instances in the tree, and thevalues are the distance from the root to each clade (includingterminals). By default the distance is the cumulative branch lengthleading to the clade, but with the
unit_branch_lengths=True
option, only the number of branches (levels in the tree) is counted.distance
Calculate the sum of the branch lengths between two targets. If onlyone target is specified, the other is the root of this tree.
total_branch_length
Calculate the sum of all the branch lengths in this tree. This isusually just called the “length” of the tree in phylogenetics, but weuse a more explicit name to avoid confusion with Python terminology.
The rest of these methods are boolean checks:
is_bifurcating
True if the tree is strictly bifurcating; i.e. all nodes have either2 or 0 children (internal or external, respectively). The root mayhave 3 descendents and still be considered part of a bifurcatingtree.
is_monophyletic
Test if all of the given targets comprise a complete subclade — i.e.,there exists a clade such that its terminals are the same set as thegiven targets. The targets should be terminals of the tree. Forconvenience, this method returns the common ancestor (MCRA) of thetargets if they are monophyletic (instead of the value
True
), andFalse
otherwise.is_parent_of
True if target is a descendent of this tree — not required to be adirect descendent. To check direct descendents of a clade, simply uselist membership testing:
if subclade in clade: ...
is_preterminal
True if all direct descendents are terminal; False if any directdescendent is not terminal.
Modification methods
These methods modify the tree in-place. If you want to keep the originaltree intact, make a complete copy of the tree first, using Python’scopy
module:
tree = Phylo.read("example.xml", "phyloxml")import copynewtree = copy.deepcopy(tree)
collapse
Deletes the target from the tree, relinking its children to itsparent.
collapse_all
Collapse all the descendents of this tree, leaving only terminals.Branch lengths are preserved, i.e. the distance to each terminalstays the same. With a target specification (see above), collapsesonly the internal nodes matching the specification.
ladderize
Sort clades in-place according to the number of terminal nodes.Deepest clades are placed last by default. Use
reverse=True
tosort clades deepest-to-shallowest.prune
Prunes a terminal clade from the tree. If taxon is from abifurcation, the connecting node will be collapsed and its branchlength added to remaining terminal node. This might no longer be ameaningful value.
root_with_outgroup
Reroot this tree with the outgroup clade containing the giventargets, i.e. the common ancestor of the outgroup. This method isonly available on Tree objects, not Clades.
If the outgroup is identical to self.root, no change occurs. If theoutgroup clade is terminal (e.g. a single terminal node is given asthe outgroup), a new bifurcating root clade is created with a0-length branch to the given outgroup. Otherwise, the internal nodeat the base of the outgroup becomes a trifurcating root for the wholetree. If the original root was bifurcating, it is dropped from thetree.
In all cases, the total branch length of the tree stays the same.
root_at_midpoint
Reroot this tree at the calculated midpoint between the two mostdistant tips of the tree. (This uses
root_with_outgroup
under thehood.)split
Generate n (default 2) new descendants. In a species tree, this isa speciation event. New clades have the given
branch_length
andthe same name as this clade’s root plus an integer suffix (countingfrom 0) — for example, splitting a clade named “A” produces thesub-clades “A0” and “A1”.
See the Phylo page on the Biopython wiki(http://biopython.org/wiki/Phylo) for more examples of using theavailable methods.
Features of PhyloXML trees
The phyloXML file format includes fields for annotating trees withadditional data types and visual cues.
See the PhyloXML page on the Biopython wiki(http://biopython.org/wiki/PhyloXML) for descriptions and examples ofusing the additional annotation features provided by PhyloXML.
Running external applications
While Bio.Phylo doesn’t infer trees from alignments itself, there arethird-party programs available that do. These can be accessed fromwithin python by using the subprocess
module.
Below is an example on how to use a python script to interact with PhyML(http://www.atgc-montpellier.fr/phyml/). The program accepts an inputalignment in phylip-relaxed
format (that’s Phylip format, butwithout the 10-character limit on taxon names) and a variety of options.
>>> import subprocess>>> cmd = "phyml -i Tests/Phylip/random.phy">>> results = subprocess.run(cmd, shell=True, stdout=subprocess.PIPE, text=True)
The ‘stdout = subprocess.PIPE‘ argument makes the output of the programaccessible through ‘results.stdout‘ for debugging purposes, (the samecan be done for ‘stderr‘), and ‘text=True‘ makes the returnedinformation be a python string, instead of a ‘bytes‘ object.
This generates a tree file and a stats file with the names[inputfilename]_phyml_tree.txt
and[inputfilename]_phyml_stats.txt
. The tree file is in Newickformat:
>>> from Bio import Phylo>>> tree = Phylo.read("Tests/Phylip/random.phy_phyml_tree.txt", "newick")>>> Phylo.draw_ascii(tree) __________________ F | | I |_| ________ C | ________| | | | , J | | |________| | | | , H |___________| |__________| | |______________ D | , G | | , E |________________| | ___________________________ A |________________| |_________ B
The subprocess
module can also be used for interacting with anyother programs that provide a command line interface such as RAxML(https://sco.h-its.org/exelixis/software.html), FastTree(http://www.microbesonline.org/fasttree/), dnaml
and protml
.
PAML integration
Biopython 1.58 brought support for PAML(http://abacus.gene.ucl.ac.uk/software/paml.html), a suite of programsfor phylogenetic analysis by maximum likelihood. Currently the programscodeml, baseml and yn00 are implemented. Due to PAML’s usage of controlfiles rather than command line arguments to control runtime options,usage of this wrapper strays from the format of other applicationwrappers in Biopython.
A typical workflow would be to initialize a PAML object, specifying analignment file, a tree file, an output file and a working directory.Next, runtime options are set via the set_options()
method or byreading an existing control file. Finally, the program is run via therun()
method and the output file is automatically parsed to aresults dictionary.
Here is an example of typical usage of codeml:
>>> from Bio.Phylo.PAML import codeml>>> cml = codeml.Codeml()>>> cml.alignment = "Tests/PAML/Alignments/alignment.phylip">>> cml.tree = "Tests/PAML/Trees/species.tree">>> cml.out_file = "results.out">>> cml.working_dir = "./scratch">>> cml.set_options(... seqtype=1,... verbose=0,... noisy=0,... RateAncestor=0,... model=0,... NSsites=[0, 1, 2],... CodonFreq=2,... cleandata=1,... fix_alpha=1,... kappa=4.54006,... )>>> results = cml.run()>>> ns_sites = results.get("NSsites")>>> m0 = ns_sites.get(0)>>> m0_params = m0.get("parameters")>>> print(m0_params.get("omega"))
Existing output files may be parsed as well using a module’s read()
function:
>>> results = codeml.read("Tests/PAML/Results/codeml/codeml_NSsites_all.out")>>> print(results.get("lnL max"))
Detailed documentation for this new module currently lives on theBiopython wiki: http://biopython.org/wiki/PAML
Future plans
Bio.Phylo is under active development. Here are some features we mightadd in future releases:
- New methods
Generally useful functions for operating on Tree or Clade objectsappear on the Biopython wiki first, so that casual users can testthem and decide if they’re useful before we add them to Bio.Phylo:
http://biopython.org/wiki/Phylo_cookbook
- Bio.Nexus port
Much of this module was written during Google Summer of Code 2009,under the auspices of NESCent, as a project to implement Pythonsupport for the phyloXML data format (see Features of PhyloXML trees).Support for Newick and Nexus formats was added by porting part of theexisting Bio.Nexus module to the new classes used by Bio.Phylo.
Currently, Bio.Nexus contains some useful features that have not yetbeen ported to Bio.Phylo classes — notably, calculating a consensustree. If you find some functionality lacking in Bio.Phylo, try pokingthrough Bio.Nexus to see if it’s there instead.
We’re open to any suggestions for improving the functionality andusability of this module; just let us know on the mailing list or ourbug database.
Finally, if you need additional functionality not yet included in thePhylo module, check if it’s available in another of the high-qualityPython libraries for phylogenetics such as DendroPy(https://dendropy.org/) or PyCogent (http://pycogent.org/). Since theselibraries also support standard file formats for phylogenetic trees, youcan easily transfer data between libraries by writing to a temporaryfile or StringIO object.