Input and output#

forestpd reads Newick trees itself (from a file or a list of strings, see User guide). These functions write trees out: as Newick, and as one weighted split system for split-diversity tools such as PDA.

forestpd.io.to_newick(tree, labels=None, lengths=True)[source]#

Write a PhyloTree as a Newick string.

The tree is unrooted, so the string is rooted at an arbitrary internal node. Reading it back with parse_newick() gives the same unrooted tree.

Parameters:

tree (PhyloTree) – The tree to write.
labels (Sequence[str] | None, optional) – Label per leaf id. None (default) writes the leaf ids themselves.
lengths (bool, default True) – Write branch lengths; False writes the topology only.

Returns:

The Newick string, ending in ;. Labels that are not plain words are single-quoted.

Return type:

str

Raises:

ForestPDInputError – If labels does not hold exactly one distinct label per leaf.

Examples

>>> t = PhyloTree.from_edges(6, [(0, 4), (1, 4), (4, 5), (2, 5), (3, 5)],
...                          [1.0, 2.0, 0.5, 1.0, 1.0], {i: i for i in range(4)})
>>> to_newick(t)
'(0:1.0,1:2.0,(2:1.0,3:1.0):0.5);'
>>> to_newick(t, ["a", "b", "c d", "e"])
"(a:1.0,b:2.0,('c d':1.0,e:1.0):0.5);"
>>> to_newick(t, lengths=False)
'(0,1,(2,3));'

forestpd.io.to_splits_nexus(trees, path, weights=None, *, labels=None, missing_branch_length='error')[source]#

Write the trees’ weighted split system (split_system()) as a NEXUS file, e.g. for PDA.

The file has a Taxa block and a Splits block (labels=no weights=yes), each split given as its weight and the 1-based taxon indices of one side. A split system holds unrooted trees only: no costs, survival probabilities or roots.

Parameters:

trees (str | os.PathLike | Sequence) – As for split_system().
path (str | os.PathLike) – The file to write.
weights – As for split_system().
labels – As for split_system().
missing_branch_length – As for split_system().

Returns:

The number of splits written.

Return type:

int

Raises:

ForestPDInputError – As split_system().
OSError – If path cannot be written.

PhyloZoo#

Conversion between forestpd trees and PhyloZoo networks, for plotting and the rest of the PhyloZoo ecosystem. Needs the optional extra (pip install "forestpd[phylozoo]"); this is the only module that imports PhyloZoo.

forestpd.io.pz.from_phylozoo(network, registry=None, missing_branch_length='error')[source]#

Convert a PhyloZoo tree into a PhyloTree.

Parameters:

network (SemiDirectedPhyNetwork | DirectedPhyNetwork) – A tree (no hybrid edges); a directed one is read as unrooted.
registry (TaxonRegistry | None, default None) – Global taxon id mapping; None builds one from this tree’s taxa.
missing_branch_length (str | float, default "error") – Policy for edges lacking a branch length: "error", "zero", or a numeric value.

Returns:

The tree, with leaf ids equal to the registry’s taxon ids.

Return type:

PhyloTree

Raises:

ForestPDInputError – If network is not a PhyloZoo network or not a tree, a taxon is missing from registry, or a branch length is invalid under the chosen policy.

forestpd.io.pz.to_phylozoo(tree, registry)[source]#

Convert a PhyloTree into a PhyloZoo SemiDirectedPhyNetwork.

Parameters:

tree (PhyloTree) – The tree, e.g. one of instance.trees.
registry (TaxonRegistry) – The registry the tree’s leaf ids refer to, e.g. instance.registry.

Returns:

The tree as a PhyloZoo network: leaves labelled by taxon, edges carrying branch_length.

Return type:

SemiDirectedPhyNetwork