Bio Phylo Tree Io

Version Compatibility

Reference examples tested with: BioPython 1.83+. Annotation-preserving alternatives: DendroPy 5+ (Python), treeio 1.26+ / ape 5.8+ (R).

Before using code patterns, verify installed versions match. If versions differ:

• Python: pip show biopython then help(module.function) to check signatures
• R: packageVersion('treeio') then ?read.beast to verify parameters

If code throws ImportError, AttributeError, or TypeError, introspect the installed package and adapt the example to match the actual API rather than retrying.

Bio.Phylo stores a Newick [&...] bracket as opaque .comment text and does NOT parse BEAST key-values; DendroPy extract_comment_metadata=True and treeio read.beast do.

Tree I/O -- A Tree File Is a Lossy Serialization

"Read and convert my tree files" -> Parse a tree into an in-memory object and re-serialize it, knowing which annotations each format and parser preserves.

• Python: Phylo.read('tree.nwk', 'newick'), Phylo.convert(...) (Bio.Phylo)
• Annotation-critical: dendropy.Tree.get(..., extract_comment_metadata=True) or treeio read.beast()

Scope: reading, writing, converting, and inspecting tree files, and selecting a parser that keeps the annotations the analysis needs. Rooting, pruning, collapsing -> tree-manipulation. Plotting and mapping annotations onto branches -> tree-visualization. Producing BEAST/MrBayes annotated trees -> bayesian-inference, divergence-dating. Taxon-name sanitization shares the whitespace traps in sequence-io/read-sequences.

The Single Most Important Modern Insight

A tree file is a lossy serialization of a richer in-memory object. The biologist cares about the topology plus its annotations -- branch supports, posterior probabilities, 95% HPD intervals on node heights, per-branch rates, divergence dates, taxon metadata -- and formats differ enormously in which of these they can hold, while parsers differ in which they actually read back. Three load-bearing facts:

1. Conversion is a silent data-destroying operation. Reading a BEAST MCC tree and writing plain Newick produces a topologically identical tree that plots fine, but the HPD intervals, clade posteriors, and per-branch rates are gone and unrecoverable without re-running a multi-day MCMC. The loss is invisible until a reviewer asks where the credible intervals went.
2. The tool, not the format string, decides whether [&...] metadata survives. In Python the naive default (Bio.Phylo) drops BEAST key-values; in R the naive default (ape::read.nexus) drops them; the tools built to preserve them are DendroPy (extract_comment_metadata=True) and treeio (read.beast). Route annotated trees through those.
3. In plain Newick a bare number has no fixed meaning. In (A,B)95:0.3 the 95 could be a bootstrap, a posterior, an internal clade name, or a second branch length. Only the tool that wrote the file knows; a parser that guesses wrong turns supports into names silently. IQ-TREE overloads the slot further, writing SH-aLRT/UFBoot (e.g. 87.5/98), which a single-value parser truncates or chokes on.

Tool Taxonomy

References: Bio.Phylo Talevich 2012; DendroPy Sukumaran 2010; ETE3 Huerta-Cepas 2016; ape Paradis 2019; treeio Wang 2020.

One-line decision rule: if the file came from BEAST, MrBayes, or RevBayes or carries [&...]/&&NHX that matters, read it with treeio (R) or DendroPy (Py); otherwise Bio.Phylo (Py) or ape (R) is fine. Never route a BEAST MCC tree through Bio.Phylo or ape::read.nexus when the HPDs are needed.

Format Capability (What Each Format Can Hold)

Newick/NHX are compact and grep-able; phyloXML/NeXML are verbose XML (often 5-20x larger) but typed and validatable -- prefer XML for archiving/exchange where machine-checkable semantics matter, Newick/Nexus for pipeline interchange. BEAST/FigTree metadata rides inside a Nexus (or Newick) [&...] comment, so "it is a Nexus file" says nothing about whether annotations survive -- only the parser does.

Reading, Writing, and Converting (Bio.Phylo)

Goal: Move trees between formats and inspect them without assuming a single tree or losing annotations.

Approach: Use Phylo.read for exactly one tree and Phylo.parse for many (posterior sets); use Phylo.convert only among formats of equal or greater capability; check .confidence vs .name to confirm support was read into the right slot.

from Bio import Phylo

tree = Phylo.read('tree.nwk', 'newick')          # exactly one tree; raises if 0 or >1
posterior = list(Phylo.parse('run.trees', 'nexus'))   # many trees: posterior/bootstrap set
Phylo.write(tree, 'tree.xml', 'phyloxml')        # phyloXML is Bio.Phylo's richest format

Phylo.convert('tree.nex', 'nexus', 'tree.nwk', 'newick')   # WARNING: Newick cannot hold [&...]; annotations dropped

for clade in tree.get_nonterminals():
    print(clade.confidence, clade.name)          # confirm the support landed in .confidence, not .name

Supported format strings: newick, nexus, phyloxml, nexml, cdao. Colors and branch widths persist only in phyloXML.

Preserve BEAST/MrBayes Annotations Before Down-Converting

Goal: Keep posteriors, HPD intervals, and rates when a downstream tool wants plain Newick.

Approach: Read with an annotation-aware parser, extract the numbers into a side table that travels with the analysis, and only then write a stripped topology -- never down-convert first.

import dendropy

tree = dendropy.Tree.get(path='mcc.tree', schema='nexus', extract_comment_metadata=True)
for node in tree:
    if node.annotations.get_value('posterior') is not None:
        post = node.annotations.get_value('posterior')
        hpd = node.annotations.get_value('height_95%_HPD')   # raw BEAST key; treeio typically exposes it as height_0.95_HPD (exact name varies by source program and version -- introspect the columns)
        # persist post/hpd to a side table keyed by the clade before any conversion
tree.write(path='topology.nwk', schema='newick', suppress_annotations=True)   # intentional, after extraction

In R the equivalent is treeio read.beast('mcc.tree') then get.data() / as_tibble(), feeding ggtree (tree-visualization); write.beast() re-serializes with annotations intact.

Per-Method Failure Modes

BEAST/MrBayes MCC to Plain Newick Erases the Credible Intervals

Trigger: Phylo.convert, ape::read.nexus + write.tree, or any "just give me the topology" step on an annotated tree. Mechanism: The HPDs, posteriors, and rates live only in the [&...] comments, which plain Newick cannot hold and stripping parsers discard. Symptom: The output plots fine but the credible intervals are gone, irrecoverable without re-running the MCMC. Fix: Read with treeio read.beast or DendroPy extract_comment_metadata=True; extract the numbers to a side table; keep the original .tree as the source of truth.