#! /usr/bin/env python
# -*- coding: utf-8 -*-
##############################################################################
## DendroPy Phylogenetic Computing Library.
##
## Copyright 2010-2015 Jeet Sukumaran and Mark T. Holder.
## All rights reserved.
##
## See "LICENSE.rst" for terms and conditions of usage.
##
## If you use this work or any portion thereof in published work,
## please cite it as:
##
## Sukumaran, J. and M. T. Holder. 2010. DendroPy: a Python library
## for phylogenetic computing. Bioinformatics 26: 1569-1571.
##
##############################################################################
"""
Writing of Newick-format tree to a stream.
"""
from dendropy.utility import textprocessing
from dendropy.dataio import nexusprocessing
from dendropy.dataio import ioservice
##############################################################################
## NewickReader
class NewickWriter(ioservice.DataWriter):
"""
Formatter for Newick data.
"""
[docs]
def __init__(self, **kwargs):
"""
Keyword Arguments
-----------------
suppress_leaf_taxon_labels : boolean, default: |False|
If |True|, then taxon labels will not be rendered for leaves.
Default is |False|: render leaf taxon labels. See notes below for
details.
suppress_leaf_node_labels : boolean, default: |True|
If |False|, then node labels (if available) will be printed for
leaves. Defaults to |True|: do not render leaf node labels. See
notes below for details.
suppress_internal_taxon_labels : boolean, default: |False|
If |True|, then taxon labels will not be printed for internal
nodes. Default is |False|: print taxon labels for internal nodes.
See notes below for details.
suppress_internal_node_labels : boolean, default: |False|
If |True|, then node labels will not be printed for internal nodes.
Default is |False|: print node labels for internal nodes. See notes
below for details.
suppress_rooting : boolean, default: |False|
If |True|, will not write rooting token ('[&R]' or '[&U]').
Default is |False|: rooting token will be written.
suppress_edge_lengths : boolean, default: |False|
If |True|, will not write edge lengths. Default is |False|: edge
lengths will be written.
unquoted_underscores : boolean, default: |False|
If |True|, labels with underscores will not be quoted, which will
mean that they will be interpreted as spaces if read again ("soft"
underscores). If |False|, then labels with underscores
will be quoted, resulting in "hard" underscores. Default is
|False|.
preserve_spaces : boolean, default: |False|
If |True|, spaces will not be replaced with underscores in labels
(which means any labels containing spaces will have to be quoted).
Default is |False|: spaces will be converted to underscores.
False.
store_tree_weights : boolean, default: |False|
If |True|, tree weights are written. Default is |False|: tree
weights will not be written.
taxon_token_map : boolean or dict or |None|, default: |None|.
If not |False| or |None|, a "TRANSLATE" statement will be written
and referenced in tree statements (instead of using the taxon
labels). If |True|, then a default translate statement will
be used, with tokens given by the taxon indexes. If a dictionary is
given, then the keys should be |Taxon| objects and the
values should be the token (strings).
suppress_annotations : boolean, default: |True|
If |False|, metadata annotations will be written out as special
comments. Defaults to |True|: metadata annotations will be ignored.
annotations_as_nhx : boolean, default: |False|
If |True|, and if ``suppress_annotations`` is |False|, will write
annotation as NHX statements. Default is |False|: annotations
will not be written as NHX statements.
suppress_item_comments : boolean, default: |True|
If |False|, any additional comments associated with trees, nodes,
edges, etc. will be written. Default is |True|: comments will be
ignored.
node_label_element_separator : string, default: ' '
If both ``suppress_leaf_taxon_labels`` and
``suppress_leaf_node_labels`` are |False|, then this will be the
string used to join them. Defaults to ' ' (space).
node_label_compose_fn : function object or |None|, default: |None|
If not |None|, should be a function that takes a |Node|
object as an argument and returns the string to be used to
represent the node in the tree statement. The return value from
this function is used unconditionally to print a node
representation in a tree statement, by-passing the default
labelling function, ignoring ``suppress_leaf_taxon_labels``,
``suppress_leaf_node_labels=True``, ``suppress_internal_taxon_labels``,
``suppress_internal_node_labels``, etc. Defaults to |None|.
edge_label_compose_fn : function object or |None|, default: |None|
If not |None|, should be a function that takes an Edge object as
an argument, and returns the string to be used to represent the
edge length in the tree statement.
real_value_format_specifier : string, default: ''
Format specification for real/float values. Will be applied to edge
lengths (if ``edge_label_compose_fn`` is not given) as well as
annotations. The format specifier should be given in Python's
string format specification mini-language. E.g. ".8f", ".4E",
"8.4f".
ignore_unrecognized_keyword_arguments : boolean, default: |False|
If |True|, then unsupported or unrecognized keyword arguments will
not result in an error. Default is |False|: unsupported keyword
arguments will result in an error.
Notes
-----
DendroPy distinguishes between *taxon* labels and *node*
labels.
In a Newick string, however, no such distinction is possible, and
any one node can only be rendered with a single token or symbol. Thus,
if there is more than one source of label available for a particular
node (e.g., if both ``suppress_leaf_taxon_labels`` and
``suppress_leaf_node_labels`` are |False|, and a particular leaf
node has both a taxon *and* a label associated with it), then
the node symbol will be rendered as concatenation of the unsuppressed
candidate labels, with each candidate label separated by the value
given in ``node_label_element_separator``. Note that this concatenated
label requires special handling when being re-read to avoid being
interpreted as the operational taxonomic unit concept label in
its entirety. These defaults can all be overridden using the
various keywords, or a custom label can be composed for the
node by passing an appropriate function object via the
``node_label_compose_fn`` argument.
Note that, in typical Newick usage, labels of leaf nodes represent
operational taxonomic unit concepts, and thus the default setting to
render leaf taxon labels but suppress leaf node labels. Internal node
labels, on the other hand, are typically used both to represent
operational taxonomic unit concepts (e.g., ancestral taxa) as well as
other concepts (e.g., support or geographic range), and thus the
default internal node rendering is to not to suppress either the taxon
labels or the node labels.
"""
ioservice.DataWriter.__init__(self)
legacy = {
"internal_labels": "Use 'suppress_internal_taxon_labels' instead",
"write_rooting": "Use 'suppress_rooting' instead",
"quote_underscores" : "Use 'unquoted_underscores' instead",
"annotations_as_comments": "Use 'suppress_annotations' instead"
}
for kw in legacy:
if kw in kwargs:
raise TypeError("'{}' is no longer supported: {}".format(kw, legacy[kw]))
ioservice.DataWriter.__init__(self, **kwargs)
self.suppress_leaf_taxon_labels = kwargs.pop("suppress_leaf_taxon_labels", False)
self.suppress_leaf_node_labels = kwargs.pop("suppress_leaf_node_labels", True)
self.suppress_internal_taxon_labels = kwargs.pop("suppress_internal_taxon_labels", False)
# self.suppress_internal_taxon_labels = not kwargs.pop("internal_labels", not sef.suppress_internal_taxon_labels) # legacy
self.suppress_internal_node_labels = kwargs.pop("suppress_internal_node_labels", False)
# self.suppress_internal_node_labels = not kwargs.pop("internal_labels", not self.suppress_internal_node_labels) # legacy
self.suppress_rooting = kwargs.pop("suppress_rooting", False)
# self.suppress_rooting = not kwargs.pop("write_rooting", not self.suppress_rooting) # legacy
self.suppress_edge_lengths = kwargs.pop("suppress_edge_lengths", False)
# self.suppress_edge_lengths = not kwargs.pop("edge_lengths", not self.suppress_edge_lengths) # legacy
self.unquoted_underscores = kwargs.pop("unquoted_underscores", False)
# self.unquoted_underscores = not kwargs.pop('quote_underscores', not self.unquoted_underscores) # legacy
self.preserve_spaces = kwargs.pop("preserve_spaces", False)
self.store_tree_weights = kwargs.pop("store_tree_weights", False)
self.taxon_token_map = kwargs.pop("taxon_token_map", {})
self.suppress_annotations = kwargs.pop("suppress_annotations", True)
# self.suppress_annotations = not kwargs.pop("annotations_as_comments", not self.suppress_annotations) # legacy
self.annotations_as_nhx = kwargs.pop("annotations_as_nhx", False)
self.suppress_item_comments = kwargs.pop("suppress_item_comments", True)
self.suppress_item_comments = not kwargs.pop("write_item_comments", not self.suppress_item_comments)
self.node_label_element_separator = kwargs.pop("node_label_element_separator", ' ')
self.node_label_compose_fn = kwargs.pop("node_label_compose_fn", None)
self.edge_label_compose_fn = kwargs.pop("edge_label_compose_fn", None)
self._real_value_format_specifier = ""
self._real_value_formatter = None
self.real_value_format_specifier = kwargs.pop("real_value_format_specifier", self._real_value_format_specifier)
if self.edge_label_compose_fn is None:
self.edge_label_compose_fn = self._format_edge_length
self.check_for_unused_keyword_arguments(kwargs)
def _get_taxon_tree_token(self, taxon):
if self.taxon_token_map is None:
self.taxon_token_map = {}
try:
return self.taxon_token_map[taxon]
except KeyError:
t = str(taxon.label)
self.taxon_token_map[taxon] = t
return t
def _get_real_value_format_specifier(self):
return self._real_value_format_specifier
def _set_real_value_format_specifier(self, f):
if f is None:
f = ""
self._real_value_format_specifier = f
s = "{:" + self._real_value_format_specifier + "}"
self._real_value_formatter = s.format
real_value_format_specifier = property(_get_real_value_format_specifier, _set_real_value_format_specifier)
def _format_edge_length(self, edge):
"""
Note: instance method to allow overriding.
"""
return self._real_value_formatter(edge.length)
def _write(self,
stream,
taxon_namespaces=None,
tree_lists=None,
char_matrices=None,
global_annotations_target=None):
for tree_list in tree_lists:
if (self.attached_taxon_namespace is not None
and tree_list.taxon_namespace is not self.attached_taxon_namespace):
continue
self._write_tree_list(stream, tree_list)
def _write_tree_list(self, stream, tree_list):
"""
Writes a |TreeList| in Newick schema to ``stream``.
"""
for tree in tree_list:
self._write_tree(stream, tree)
stream.write("\n")
# In Newick format, no clear way to distinguish between
# annotations/comments associated with tree collection and
# annotations/comments associated with first tree. So we place them at
# *end* of document.
if (not self.suppress_annotations) and (hasattr(tree_list, "_annotations")):
annotation_comments = nexusprocessing.format_item_annotations_as_comments(tree_list,
nhx=self.annotations_as_nhx,
real_value_format_specifier=self.real_value_format_specifier,
)
else:
annotation_comments = ""
treelist_comments = self._compose_comment_string(tree_list)
stream.write("{}{}".format(
annotation_comments,
treelist_comments))
def _write_tree(self, stream, tree):
"""
Composes and writes ``tree`` to ``stream``.
"""
if tree.rooting_state_is_undefined or self.suppress_rooting:
rooting = ""
elif tree.is_rooted:
rooting = "[&R] "
elif not tree.is_rooted:
rooting = "[&U] "
else:
rooting = ""
if self.store_tree_weights and tree.weight is not None:
weight = "[&W {}] ".format(tree.weight)
else:
weight = ""
if not self.suppress_annotations:
annotation_comments = nexusprocessing.format_item_annotations_as_comments(tree,
nhx=self.annotations_as_nhx,
real_value_format_specifier=self.real_value_format_specifier,
)
else:
annotation_comments = ""
tree_comments = self._compose_comment_string(tree)
stream.write("{}{}{}{}".format(
rooting,
weight,
annotation_comments,
tree_comments,
))
tree.apply(
before_fn=lambda x: self._write_node_open(x, stream),
after_fn=lambda x: self._write_node_close(x, stream),
leaf_fn=lambda x: self._write_leaf(x, stream),
)
stream.write(";")
def _write_node_open(self, node, out):
if node._parent_node is None or node._parent_node._child_nodes[0] is node:
out.write("(")
else:
out.write(",(")
def _write_leaf(self, node, out):
if not (node._parent_node is None or node._parent_node._child_nodes[0] is node):
out.write(",")
self._write_node_body(node, out)
def _write_node_close(self, node, out):
out.write(")")
self._write_node_body(node, out)
def _write_node_body(self, node, out):
out.write(self._render_node_tag(node))
if node.edge and node.edge.length != None and not self.suppress_edge_lengths:
out.write(":{}".format(self.edge_label_compose_fn(node.edge)))
if not self.suppress_annotations:
node_annotation_comments = nexusprocessing.format_item_annotations_as_comments(node,
nhx=self.annotations_as_nhx,
real_value_format_specifier=self.real_value_format_specifier)
out.write(node_annotation_comments)
edge_annotation_comments = nexusprocessing.format_item_annotations_as_comments(node.edge,
nhx=self.annotations_as_nhx,
real_value_format_specifier=self.real_value_format_specifier)
out.write(edge_annotation_comments)
out.write(self._compose_comment_string(node))
out.write(self._compose_comment_string(node.edge))
def _compose_comment_string(self, item):
if not self.suppress_item_comments and item.comments:
item_comments = []
if textprocessing.is_str_type(item.comments):
item.comments = [item.comments]
for comment in item.comments:
item_comments.append("[{}]".format(comment))
item_comment_str = "".join(item_comments)
else:
item_comment_str = ""
return item_comment_str
def _render_node_tag(self, node):
"""
Based on current settings, the attributes of a node, and
whether or not the node is a leaf, returns an appropriate tag.
"""
tag = None
if self.node_label_compose_fn:
tag = self.node_label_compose_fn(node)
else:
tag_parts = []
is_leaf = len(node.child_nodes()) == 0
if is_leaf:
if hasattr(node, 'taxon') \
and node.taxon \
and node.taxon.label is not None \
and not self.suppress_leaf_taxon_labels:
tag_parts.append(self._get_taxon_tree_token(node.taxon))
if hasattr(node, 'label') \
and node.label \
and node.label is not None \
and not self.suppress_leaf_node_labels:
tag_parts.append(str(node.label))
if len(tag_parts) > 0:
tag = self.node_label_element_separator.join(tag_parts)
else:
return "" # anonymous leaf
else:
if hasattr(node, 'taxon') \
and node.taxon \
and node.taxon.label is not None \
and not self.suppress_internal_taxon_labels:
tag_parts.append(self._get_taxon_tree_token(node.taxon))
if hasattr(node, 'label') \
and node.label \
and node.label is not None \
and not self.suppress_internal_node_labels:
tag_parts.append(str(node.label))
if len(tag_parts) > 0:
tag = self.node_label_element_separator.join(tag_parts)
else:
return ""
if tag:
tag = nexusprocessing.escape_nexus_token(tag,
preserve_spaces=self.preserve_spaces,
quote_underscores=not self.unquoted_underscores,
protect_regex=r'''[()[\]{},;:'"\0\t\n]''')
return tag
else:
return ""
# def _compose_node(self, node):
# """
# Given a DendroPy Node, this returns the Node as a Newick
# statement according to the class-defined formatting rules.
# """
# child_nodes = node.child_nodes()
# if child_nodes:
# subnodes = [self._compose_node(child) for child in child_nodes]
# statement = '(' + ','.join(subnodes) + ')'
# if not (self.suppress_internal_taxon_labels and self.suppress_internal_node_labels):
# statement = statement + self._render_node_tag(node)
# if node.edge and node.edge.length != None and not self.suppress_edge_lengths:
# statement = "{}:{}".format(statement, self.edge_label_compose_fn(node.edge))
# else:
# statement = self._render_node_tag(node)
# if node.edge and node.edge.length != None and not self.suppress_edge_lengths:
# statement = "{}:{}".format(statement, self.edge_label_compose_fn(node.edge))
# if not self.suppress_annotations:
# node_annotation_comments = nexusprocessing.format_item_annotations_as_comments(node,
# nhx=self.annotations_as_nhx,
# real_value_format_specifier=self.real_value_format_specifier)
# edge_annotation_comments = nexusprocessing.format_item_annotations_as_comments(node.edge,
# nhx=self.annotations_as_nhx,
# real_value_format_specifier=self.real_value_format_specifier)
# statement = statement + node_annotation_comments + edge_annotation_comments
# edge_comment_str = self._compose_comment_string(node.edge)
# node_comment_str = self._compose_comment_string(node)
# statement = statement + node_comment_str + edge_comment_str
# return statement
