Skip to main content

A python module to read and write the Newick format

Project description


Build Status PyPI

python package to read and write the Newick format.

Reading Newick

Since Newick specifies a format for a set of trees, all functions to read Newick return a list of newick.Node objects.

  • Reading from a string:

    >>> from newick import loads
    >>> trees = loads('(A,B,(C,D)E)F;')
    >>> trees[0].name
    >>> [ for n in trees[0].descendants]
    ['A', 'B', 'E']
  • Reading from a file-like object:

    >>> import io
    >>> from newick import load
    >>> with'fname', encoding='utf8') as fp:
    ...     trees = load(fp)
  • Reading from a path:

    >>> from newick import read
    >>> trees = read('fname')
    >>> import pathlib
    >>> trees = read(pathlib.Path('fname'))

Supported Newick dialects

The "Newick specification" states

Comments are enclosed in square brackets and may appear anywhere

This has spawned a host of ad-hoc mechanisms to insert additional data into Newick trees.

The newick package allows to deal with comments in two ways.

  • Ignoring comments:
    >>> newick.loads('[a comment](a,b)c;', strip_comments=True)[0].newick
  • Reading comments as node annotations: Several software packages use Newick comments to store node annotations, e.g. *BEAST, MrBayes or TreeAnnotator. Provided there are no comments in places where they cannot be interpreted as node annotations, newick supports reading and writing these annotations:
    >>> newick.loads('(a[annotation],b)c;')[0].descendants[0].name
    >>> newick.loads('(a[annotation],b)c;')[0].descendants[0].comment
    >>> newick.loads('(a[annotation],b)c;')[0].newick
    Annotations may come before or after the : which separates node label and length:
  • >>> newick.loads('(a[annotation]:2,b)c;')[0].descendants[0].length
    >>> newick.loads('(a:[annotation]2,b)c;')[0].descendants[0].length
    but if they preceed the colon, they must not contain ::
  • >>> newick.loads('(a[annotation:]:2,b)c;')[0].descendants[0].comment
    ValueError: Node names or branch lengths must not contain ":"

Note that square brackets inside quoted labels will not be interpreted as comments or annotations:

>>> newick.loads("('a[label]',b)c;")[0].descendants[0].name
>>> newick.loads("('a[label]',b)c;")[0].newick

Writing Newick

In parallel to the read operations there are three functions to serialize a single Node object or a list of Node objects to Newick format:

  • dumps(trees) -> str
  • dump(trees, fp)
  • write(trees, 'fname')

A tree may be assembled using the factory methods of the Node class:

  • Node.__init__
  • Node.create
  • Node.add_descendant

Manipulating trees

  • Displaying tree topology in the terminal:
    >>> import newick
    >>> tree = newick.loads('(b,(c,(d,(e,(f,g))h)i)a)')[0]
    >>> print(tree.ascii_art())
  • Pruning trees: The example below prunes the tree such that b, c and i are the only remaining leafs.
    >>> tree.prune_by_names(['b', 'c', 'i'], inverse=True)
    >>> print(tree.ascii_art())
  • Running a callable on a filtered set of nodes:
    >>> tree.visit(lambda n: setattr(n, 'name',, lambda n: in ['a', 'b'])
    >>> print(tree.ascii_art())
  • Removing (topologically) redundant internal nodes:
    >>> tree.prune_by_names(['B', 'c'], inverse=True)
    >>> print(tree.ascii_art())
        └─A ──c
    >>> tree.remove_redundant_nodes(keep_leaf_name=True)
    >>> print(tree.ascii_art())

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

newick-1.4.0.tar.gz (13.2 kB view hashes)

Uploaded Source

Built Distribution

newick-1.4.0-py2.py3-none-any.whl (12.5 kB view hashes)

Uploaded Python 2 Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page