baltic treebuliders

This module provides the core baltic functions make_tree() and make_tree_JSON().

Notes

This version of baltic (v1.0 (Cedar)) contains many API changes from previous versions, and is not backwards-compatible. If you find pieces of documentation that refer to the old API, please let us know and we will try to update them with the next update.

Attributes

loggerlogging.Logger

Default logger which will be passed to other baltic functions.

baltic.baltic.make_tree(data, treeType, tre=None)

Parse a Newick-like tree string into a baltic.tree.Tree.

Handles BEAST integer tips, [&...] annotation comments and #label reticulations in addition to plain Newick. The returned tree has not been traversed; the loaders in baltic.io do that, so call baltic.tree.Tree.traverse_tree() if using this directly.

Note

If every branch length parses as 0.0 – as happens with a topology-only cladogram such as "((A,B),C);" – branch lengths are rewritten to make the tree ultrametric with a height of 1.0, and a warning is logged. The lengths in the resulting tree are therefore invented, not parsed.

Parameters

datastr

Tree string to parse.

treeType{‘divergence’, ‘time’}

Interpretation of branch lengths in the resulting tree.

trebaltic.tree.Tree, optional

Existing tree object to populate. If omitted, a new tree is created.

Returns

baltic.tree.Tree

Parsed tree object.

Raises

AssertionError

If the string does not end in a semicolon, if parentheses are unbalanced, or if parsing stalls on a character it cannot interpret.

Exception

If a reticulation label is used more than once in the tree.

Examples

>>> import baltic as bt
>>> ll = bt.make_tree("((A:1.0,B:1.5):0.5,C:2.0);", treeType="divergence")
>>> [tip.name for tip in ll.get_external()]
['A', 'B', 'C']

baltic.baltic.make_tree_JSON(jsonNode, jsonTranslationDict, treeType, tre=None)

Build a baltic.tree.Tree from an Auspice-style JSON node hierarchy.

Parameters

jsonNodedict

Root JSON node to parse.

jsonTranslationDictdict

Mapping from baltic attribute names to JSON keys.

treeType{‘divergence’, ‘time’}

Interpretation of branch lengths in the resulting tree.

trebaltic.tree.Tree, optional

Existing tree object to populate recursively. If omitted, a new tree is created.

Returns

baltic.tree.Tree

Parsed tree object, already traversed.

Raises

KeyError

If a JSON leaf lacks the name field named by jsonTranslationDict.

Notes

Internal nodes without a name in the JSON are assigned a generated NODE_<n> identifier, matching Auspice’s own convention. This is why the second example below reports 'NODE_0000001' for an unnamed root.

Examples

>>> import baltic as bt
>>> json_tree = {
...     "name": "root",
...     "node_attrs": {"div": 0.0},
...     "children": [
...         {"name": "A", "node_attrs": {"div": 1.0}},
...         {"name": "B", "node_attrs": {"div": 1.2}},
...     ],
... }
>>> translation = {"name": "name", "height": "div"}
>>> ll = bt.make_tree_JSON(json_tree, translation, treeType="divergence")
>>> sorted(tip.name for tip in ll.get_external())
['A', 'B']
>>> unnamed_json_tree = {
...     "node_attrs": {"div": 0.0},
...     "children": [
...         {"name": "A", "node_attrs": {"div": 1.0}},
...         {"name": "B", "node_attrs": {"div": 1.2}},
...     ],
... }
>>> ll = bt.make_tree_JSON(unnamed_json_tree, translation, treeType="divergence")
>>> ll.root.index
'NODE_0000001'