Newick

Description

Reading

Schema-Specific Keyword Arguments

NewickReader.__init__(**kwargs)[source]
Keyword Arguments:

  • rooting (string, {['default-unrooted'], 'default-rooted', 'force-unrooted', 'force-rooted'}) –

    Specifies how trees in the data source should be intepreted with respect to their rooting:

    ’default-unrooted’ [default]:

    All trees are interpreted as unrooted unless a ‘[&R]’ comment token explicitly specifies them as rooted.

    ’default-rooted’

    All trees are interpreted as rooted unless a ‘[&U]’ comment token explicitly specifies them as unrooted.

    ’force-unrooted’

    All trees are unconditionally interpreted as unrooted.

    ’force-rooted’

    All trees are unconditionally interpreted as rooted.

  • edge_length_type (type, default: float) – Specifies the type of the edge lengths (int or float). Tokens interpreted as branch lengths will be cast to this type. Defaults to float.

  • suppress_edge_lengths (boolean, default: False) – If True, edge length values will not be processed. If False, edge length values will be processed.

  • extract_comment_metadata (boolean, default: True) – If True (default), any comments that begin with ‘&’ or ‘&&’ will be parsed and stored as part of the annotation set of the corresponding object (accessible through the annotations attribute of the object). This requires that the comment contents conform to a particular format (NHX or BEAST: ‘field = value’). If False, then the comments will not be parsed, but will be instead stored directly as elements of the comments list attribute of the associated object.

  • store_tree_weights (boolean, default: False) – If True, process the tree weight (e.g. “[&W 1/2]”) comment associated with each tree, if any. Defaults to False.

  • finish_node_fn (function object, default: None) – If specified, this function will be applied to each node after it has been constructed.

  • case_sensitive_taxon_labels (boolean, default: False) – If True, then taxon labels are case sensitive (e.g., “P.regius” and “P.REGIUS” wil be treated as different operation taxonomic unit concepts). Otherwise, taxon label intepretation will be made without regard for case.

  • preserve_underscores (boolean, default: False) – If True, unquoted underscores in labels will not converted to spaces. Defaults to False: all underscores not protected by quotes will be converted to spaces.

  • suppress_internal_node_taxa (boolean, default: True) – If False, internal node labels will be instantantiated into Taxon objects. If True, internal node labels will not be instantantiated as strings.

  • suppress_leaf_node_taxa (boolean, default: False) – If False, leaf (external) node labels will be instantantiated into Taxon objects. If True, leaf (external) node labels will not be instantantiated as strings.

  • is_parse_jplace_tokens (boolean: False) – If True, then accept edge numbering according to the jplace format, as described in Matsen et. al. PLoS One, 2012 http://dx.doi.org/10.1371/journal.pone.0031009. An instance variable edge_index is added to the returned tree, and an edge_number is added to each edge. If False [default], encountering edge labels raises a NewickReaderMalformedStatementError.

  • is_assign_internal_labels_to_edges (boolean, default: None) – If True, internal node labels will be assigned as edge labels.

  • terminating_semicolon_required (boolean, default: True) – If True [default], then a tree statement that does not end in a semi-colon is an error. If False, then no error will be raised.

  • 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.

Supported Methods

Tree.get

(method reference)

tree = dendropy.Tree.get(
    path="tree.tre",
    schema="newick",
    label=None,
    taxon_namespace=None,
    collection_offset=None,
    tree_offset=None,
    rooting="default-unrooted",
    edge_length_type=float,
    suppress_edge_lengths=False,
    extract_comment_metadata=True,
    store_tree_weights=False,
    encode_splits=False,
    finish_node_fn=None,
    case_sensitive_taxon_labels=False,
    preserve_underscores=False,
    suppress_internal_node_taxa=True,
    suppress_leaf_node_taxa=False,
    terminating_semicolon_required=True,
    ignore_unrecognized_keyword_arguments=False,
    )

TreeList.get

(method reference)

tree_list = dendropy.TreeList.get(
    path="path/to/file",
    schema="newick",
    label=None,
    taxon_namespace=None,
    collection_offset=None,
    tree_offset=None,
    rooting="default-unrooted",
    edge_length_type=float,
    suppress_edge_lengths=False,
    extract_comment_metadata=True,
    store_tree_weights=False,
    encode_splits=False,
    finish_node_fn=None,
    case_sensitive_taxon_labels=False,
    preserve_underscores=False,
    suppress_internal_node_taxa=True,
    suppress_leaf_node_taxa=False,
    terminating_semicolon_required=True,
    ignore_unrecognized_keyword_arguments=False,
    )

TreeList.read

(method reference)

tree_list = dendropy.TreeList()
tree_list.read(
    path="path/to/file",
    schema="newick",
    collection_offset=None,
    tree_offset=None,
    rooting="default-unrooted",
    edge_length_type=float,
    suppress_edge_lengths=False,
    extract_comment_metadata=True,
    store_tree_weights=False,
    encode_splits=False,
    finish_node_fn=None,
    case_sensitive_taxon_labels=False,
    preserve_underscores=False,
    suppress_internal_node_taxa=True,
    suppress_leaf_node_taxa=False,
    terminating_semicolon_required=True,
    ignore_unrecognized_keyword_arguments=False,
    )

TreeArray.read

(method reference)

tree_array = dendropy.TreeArray()
tree_array.read(
    path="path/to/file",
    schema="newick",
    label=None,
    collection_offset=None,
    tree_offset=None,
    rooting="default-unrooted",
    edge_length_type=float,
    suppress_edge_lengths=False,
    extract_comment_metadata=True,
    store_tree_weights=False,
    encode_splits=False,
    finish_node_fn=None,
    case_sensitive_taxon_labels=False,
    preserve_underscores=False,
    suppress_internal_node_taxa=True,
    suppress_leaf_node_taxa=False,
    terminating_semicolon_required=True,
    ignore_unrecognized_keyword_arguments=False,
    )

DataSet.get

(method reference)

data_set = dendropy.DataSet.get(
    path="path/to/file",
    schema="newick",
    label=None,
    taxon_namespace=None,
    exclude_chars=False,
    exclude_trees=False,
    rooting="default-unrooted",
    edge_length_type=float,
    suppress_edge_lengths=False,
    extract_comment_metadata=True,
    store_tree_weights=False,
    encode_splits=False,
    finish_node_fn=None,
    case_sensitive_taxon_labels=False,
    preserve_underscores=False,
    suppress_internal_node_taxa=True,
    suppress_leaf_node_taxa=False,
    terminating_semicolon_required=True,
    ignore_unrecognized_keyword_arguments=False,
    )

DataSet.read

(method reference)

data_set = dendropy.DataSet()
data_set.read(
    path="path/to/file",
    schema="newick",
    exclude_chars=False,
    exclude_trees=False,
    rooting="default-unrooted",
    edge_length_type=float,
    suppress_edge_lengths=False,
    extract_comment_metadata=True,
    store_tree_weights=False,
    encode_splits=False,
    finish_node_fn=None,
    case_sensitive_taxon_labels=False,
    preserve_underscores=False,
    suppress_internal_node_taxa=True,
    suppress_leaf_node_taxa=False,
    terminating_semicolon_required=True,
    ignore_unrecognized_keyword_arguments=False,
    )

Writing

Schema-Specific Keyword Arguments

NewickWriter.__init__(**kwargs)[source]
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.

Supported Methods

Tree.write

(method reference)

d.write(
        path='outputfile.tre',
        schema='newick',
        suppress_leaf_taxon_labels=False,
        suppress_leaf_node_labels=True,
        suppress_internal_taxon_labels=False,
        suppress_internal_node_labels=False,
        suppress_rooting=False,
        suppress_edge_lengths=False,
        unquoted_underscores=False,
        preserve_spaces=False,
        store_tree_weights=False,
        taxon_token_map=None,
        suppress_annotations=True,
        annotations_as_nhx=False,
        suppress_item_comments=True,
        node_label_element_separator=' ',
        node_label_compose_fn=None,
        edge_label_compose_fn=None,
        real_value_format_specifier='',
        ignore_unrecognized_keyword_arguments=False,
        )

Tree.as_string

(method reference)

s = d.as_string(
        schema='newick',
        suppress_leaf_taxon_labels=False,
        suppress_leaf_node_labels=True,
        suppress_internal_taxon_labels=False,
        suppress_internal_node_labels=False,
        suppress_rooting=False,
        suppress_edge_lengths=False,
        unquoted_underscores=False,
        preserve_spaces=False,
        store_tree_weights=False,
        taxon_token_map=None,
        suppress_annotations=True,
        annotations_as_nhx=False,
        suppress_item_comments=True,
        node_label_element_separator=' ',
        node_label_compose_fn=None,
        edge_label_compose_fn=None,
        real_value_format_specifier='',
        ignore_unrecognized_keyword_arguments=False,
        )

TreeList.write

(method reference)

d.write(
        path='outputfile.tre',
        schema='newick',
        suppress_leaf_taxon_labels=False,
        suppress_leaf_node_labels=True,
        suppress_internal_taxon_labels=False,
        suppress_internal_node_labels=False,
        suppress_rooting=False,
        suppress_edge_lengths=False,
        unquoted_underscores=False,
        preserve_spaces=False,
        store_tree_weights=False,
        taxon_token_map=None,
        suppress_annotations=True,
        annotations_as_nhx=False,
        suppress_item_comments=True,
        node_label_element_separator=' ',
        node_label_compose_fn=None,
        edge_label_compose_fn=None,
        real_value_format_specifier='',
        ignore_unrecognized_keyword_arguments=False,
        )

TreeList.as_string

(method reference)

s = d.as_string(
        schema='newick',
        suppress_leaf_taxon_labels=False,
        suppress_leaf_node_labels=True,
        suppress_internal_taxon_labels=False,
        suppress_internal_node_labels=False,
        suppress_rooting=False,
        suppress_edge_lengths=False,
        unquoted_underscores=False,
        preserve_spaces=False,
        store_tree_weights=False,
        taxon_token_map=None,
        suppress_annotations=True,
        annotations_as_nhx=False,
        suppress_item_comments=True,
        node_label_element_separator=' ',
        node_label_compose_fn=None,
        edge_label_compose_fn=None,
        real_value_format_specifier='',
        ignore_unrecognized_keyword_arguments=False,
        )

DataSet.write

(method reference)

d.write(
        path='outputfile.tre',
        schema='newick',
        suppress_leaf_taxon_labels=False,
        suppress_leaf_node_labels=True,
        suppress_internal_taxon_labels=False,
        suppress_internal_node_labels=False,
        suppress_rooting=False,
        suppress_edge_lengths=False,
        unquoted_underscores=False,
        preserve_spaces=False,
        store_tree_weights=False,
        taxon_token_map=None,
        suppress_annotations=True,
        annotations_as_nhx=False,
        suppress_item_comments=True,
        node_label_element_separator=' ',
        node_label_compose_fn=None,
        edge_label_compose_fn=None,
        real_value_format_specifier='',
        ignore_unrecognized_keyword_arguments=False,
        )

DataSet.as_string

(method reference)

s = d.as_string(
        schema='newick',
        suppress_leaf_taxon_labels=False,
        suppress_leaf_node_labels=True,
        suppress_internal_taxon_labels=False,
        suppress_internal_node_labels=False,
        suppress_rooting=False,
        suppress_edge_lengths=False,
        unquoted_underscores=False,
        preserve_spaces=False,
        store_tree_weights=False,
        taxon_token_map=None,
        suppress_annotations=True,
        annotations_as_nhx=False,
        suppress_item_comments=True,
        node_label_element_separator=' ',
        node_label_compose_fn=None,
        edge_label_compose_fn=None,
        real_value_format_specifier='',
        ignore_unrecognized_keyword_arguments=False,
        )