# python-newick
[](https://github.com/dlce-eva/python-newick/actions?query=workflow%3Atests)
[](https://pypi.org/project/newick)
python package to read and write the
[Newick format](https://en.wikipedia.org/wiki/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:
```python
>>> from newick import loads
>>> trees = loads('(A,B,(C,D)E)F;')
>>> trees[0].name
'F'
>>> [n.name for n in trees[0].descendants]
['A', 'B', 'E']
```
- Reading from a `file`-like object:
```python
>>> import io
>>> from newick import load
>>> with io.open('fname', encoding='utf8') as fp:
... trees = load(fp)
```
- Reading from a path:
```python
>>> from newick import read
>>> trees = read('fname')
>>> import pathlib
>>> trees = read(pathlib.Path('fname'))
```
### Supported Newick dialects
While the set of reserved characters in Newick (`;(),:`) is relatively small, it's still often
seen as too restrictive, in particular when it comes to adding more data to tree nodes. Thus, Newick
provides two mechanisms to overcome this restriction:
- *quoted labels* to allow arbitrary text as node names,
- *comments* enclosed in square brackets.
#### Quoted node labels
Node labels in Newick may be quoted (i.e. enclosed in single quotes `'`) to make it possible to
add characters which are otherwise reserved. The `newick` package supports quoted labels.
```python
>>> from newick import loads
>>> print(loads("('A:B','C''D')'E(F)'")[0].ascii_art())
┌─'A:B'
──'E(F)'─┤
└─'C''D'
```
When creating Newick trees programmatically, names can be quoted (if necessary) automatically:
```python
>>> from newick import Node
>>> print(Node("A(F')", auto_quote=True).name)
'A(F'')'
>>> print(Node("A(F')", auto_quote=True).unquoted_name)
A(F')
```
Note: `newick` provides no support to parse structured data from node labels (as it can be found
in the trees distributed by the Genome Taxonomy Database).
#### Additional information in comments
The ["Newick specification"](http://biowiki.org/wiki/index.php/Newick_Format) 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:
```python
>>> newick.loads('[a comment](a,b)c;', strip_comments=True)[0].newick
'(a,b)c'
```
- 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:
```python
>>> newick.loads('(a[annotation],b)c;')[0].descendants[0].name
'a'
>>> newick.loads('(a[annotation],b)c;')[0].descendants[0].comment
'annotation'
>>> newick.loads('(a[annotation],b)c;')[0].newick
'(a[annotation],b)c'
```
Annotations may come before and/or after the `:` which separates node label and length:
- ```python
>>> newick.loads('(a[annotation]:2,b)c;')[0].descendants[0].length
2.0
>>> newick.loads('(a:[annotation]2,b)c;')[0].descendants[0].length
2.0
>>> newick.loads('(a[annotation1]:[annotation2]2,b)c;')[0].descendants[0].comments
['annotation1', 'annotation2']
```
Note that square brackets inside *quoted labels* will **not** be interpreted as comments
or annotations:
```python
>>> newick.loads("('a[label]',b)c;")[0].descendants[0].name
"'a[label]'"
>>> newick.loads("('a[label]',b)c;")[0].newick
"('a[label]',b)c"
```
Some support for reading key-value data from node comments is available as well. If the comment
format follows the [NHX](https://en.wikipedia.org/wiki/Newick_format#New_Hampshire_X_format) spec
or the `&<key>=<value>,...`-format used e.g. by the MrBayes or BEAST software, additional data
can be accessed from the `dict` `Node.properties`:
```python
>>> newick.loads('(A,B)C[&&NHX:k1=v1:k2=v2];')[0].properties
{'k1': 'v1', 'k2': 'v2'}
```
Note that we still don't support **typed** node properties. I.e. values in `Node.properties` are
always strings. Since typed properties tend to be specific to the application writing the newick,
this level of support would require more knowledge of the creation context of the tree than can
safely be inferred from the Newick string alone.
```python
>>> newick.loads('(A,B)C[&range={1,5},support="100"];')[0].properties
{'range': '{1,5}', 'support': '"100"'}
```
## 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:
```python
>>> import newick
>>> tree = newick.loads('(b,(c,(d,(e,(f,g))h)i)a)')[0]
>>> print(tree.ascii_art())
┌─b
────┤
│ ┌─c
└─a─┤
│ ┌─d
└─i─┤
│ ┌─e
└─h─┤
│ ┌─f
└───┤
└─g
```
- Pruning trees: The example below prunes the tree such that `b`, `c` and `i` are the only
remaining leafs.
```python
>>> tree.prune_by_names(['b', 'c', 'i'], inverse=True)
>>> print(tree.ascii_art())
┌─b
────┤
│ ┌─c
└─a─┤
└─i
```
- Running a callable on a filtered set of nodes:
```python
>>> tree.visit(lambda n: setattr(n, 'name', n.name.upper()), lambda n: n.name in ['a', 'b'])
>>> print(tree.ascii_art())
┌─B
────┤
│ ┌─c
└─A─┤
└─i
```
- Removing (topologically) redundant internal nodes:
```python
>>> tree.prune_by_names(['B', 'c'], inverse=True)
>>> print(tree.ascii_art())
┌─B
────┤
└─A ──c
>>> tree.remove_redundant_nodes(keep_leaf_name=True)
>>> print(tree.ascii_art())
┌─B
────┤
└─c
```
Raw data
{
"_id": null,
"home_page": "https://github.com/dlce-eva/python-newick",
"name": "newick",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "",
"author": "Robert Forkel",
"author_email": "robert_forkel@eva.mpg.de",
"download_url": "https://files.pythonhosted.org/packages/4d/d6/af0c7a6d02ff49942128c97267d6a506f52f365d60636649fce57bf0e6bb/newick-1.6.0.tar.gz",
"platform": "any",
"description": "# python-newick\n\n[](https://github.com/dlce-eva/python-newick/actions?query=workflow%3Atests)\n[](https://pypi.org/project/newick)\n\npython package to read and write the \n[Newick format](https://en.wikipedia.org/wiki/Newick_format).\n\n\n## Reading Newick\n\nSince Newick specifies a format for a **set of trees**, all functions to read Newick return\na `list` of `newick.Node` objects.\n\n- Reading from a string:\n ```python\n >>> from newick import loads\n >>> trees = loads('(A,B,(C,D)E)F;')\n >>> trees[0].name\n 'F'\n >>> [n.name for n in trees[0].descendants]\n ['A', 'B', 'E']\n ```\n\n- Reading from a `file`-like object:\n ```python\n >>> import io\n >>> from newick import load\n >>> with io.open('fname', encoding='utf8') as fp:\n ... trees = load(fp)\n ```\n\n- Reading from a path:\n ```python\n >>> from newick import read\n >>> trees = read('fname')\n >>> import pathlib\n >>> trees = read(pathlib.Path('fname'))\n ```\n\n### Supported Newick dialects\n\nWhile the set of reserved characters in Newick (`;(),:`) is relatively small, it's still often\nseen as too restrictive, in particular when it comes to adding more data to tree nodes. Thus, Newick\nprovides two mechanisms to overcome this restriction:\n- *quoted labels* to allow arbitrary text as node names,\n- *comments* enclosed in square brackets.\n\n\n#### Quoted node labels\n\nNode labels in Newick may be quoted (i.e. enclosed in single quotes `'`) to make it possible to\nadd characters which are otherwise reserved. The `newick` package supports quoted labels.\n\n```python\n>>> from newick import loads\n>>> print(loads(\"('A:B','C''D')'E(F)'\")[0].ascii_art())\n \u250c\u2500'A:B'\n\u2500\u2500'E(F)'\u2500\u2524\n \u2514\u2500'C''D'\n```\n\nWhen creating Newick trees programmatically, names can be quoted (if necessary) automatically:\n```python\n>>> from newick import Node\n>>> print(Node(\"A(F')\", auto_quote=True).name)\n'A(F'')'\n>>> print(Node(\"A(F')\", auto_quote=True).unquoted_name)\nA(F')\n```\n\nNote: `newick` provides no support to parse structured data from node labels (as it can be found\nin the trees distributed by the Genome Taxonomy Database).\n\n\n#### Additional information in comments\n\nThe [\"Newick specification\"](http://biowiki.org/wiki/index.php/Newick_Format) states\n\n> Comments are enclosed in square brackets and may appear anywhere\n\nThis has spawned a host of ad-hoc mechanisms to insert additional data into Newick trees.\n\nThe `newick` package allows to deal with comments in two ways.\n\n- Ignoring comments:\n ```python\n >>> newick.loads('[a comment](a,b)c;', strip_comments=True)[0].newick\n '(a,b)c'\n ```\n- Reading comments as node annotations: Several software packages use Newick comments to \n store node annotations, e.g. *BEAST, MrBayes or TreeAnnotator. Provided there are no\n comments in places where they cannot be interpreted as node annotations, `newick` supports\n reading and writing these annotations:\n ```python\n >>> newick.loads('(a[annotation],b)c;')[0].descendants[0].name\n 'a'\n >>> newick.loads('(a[annotation],b)c;')[0].descendants[0].comment\n 'annotation'\n >>> newick.loads('(a[annotation],b)c;')[0].newick\n '(a[annotation],b)c'\n ```\n Annotations may come before and/or after the `:` which separates node label and length:\n- ```python\n >>> newick.loads('(a[annotation]:2,b)c;')[0].descendants[0].length\n 2.0\n >>> newick.loads('(a:[annotation]2,b)c;')[0].descendants[0].length\n 2.0\n >>> newick.loads('(a[annotation1]:[annotation2]2,b)c;')[0].descendants[0].comments\n ['annotation1', 'annotation2']\n ```\n\nNote that square brackets inside *quoted labels* will **not** be interpreted as comments\nor annotations:\n```python\n>>> newick.loads(\"('a[label]',b)c;\")[0].descendants[0].name\n\"'a[label]'\"\n>>> newick.loads(\"('a[label]',b)c;\")[0].newick\n\"('a[label]',b)c\"\n```\n\nSome support for reading key-value data from node comments is available as well. If the comment\nformat follows the [NHX](https://en.wikipedia.org/wiki/Newick_format#New_Hampshire_X_format) spec\nor the `&<key>=<value>,...`-format used e.g. by the MrBayes or BEAST software, additional data\ncan be accessed from the `dict` `Node.properties`:\n```python\n>>> newick.loads('(A,B)C[&&NHX:k1=v1:k2=v2];')[0].properties\n{'k1': 'v1', 'k2': 'v2'}\n```\n\nNote that we still don't support **typed** node properties. I.e. values in `Node.properties` are\nalways strings. Since typed properties tend to be specific to the application writing the newick,\nthis level of support would require more knowledge of the creation context of the tree than can\nsafely be inferred from the Newick string alone.\n```python\n>>> newick.loads('(A,B)C[&range={1,5},support=\"100\"];')[0].properties\n{'range': '{1,5}', 'support': '\"100\"'}\n```\n\n## Writing Newick\n\nIn parallel to the read operations there are three functions to serialize a single `Node` object or a `list` of `Node`\nobjects to Newick format:\n- `dumps(trees) -> str`\n- `dump(trees, fp)`\n- `write(trees, 'fname')`\n\nA tree may be assembled using the factory methods of the `Node` class:\n- `Node.__init__`\n- `Node.create`\n- `Node.add_descendant`\n\n\n## Manipulating trees\n\n- Displaying tree topology in the terminal:\n ```python\n >>> import newick\n >>> tree = newick.loads('(b,(c,(d,(e,(f,g))h)i)a)')[0]\n >>> print(tree.ascii_art())\n \u250c\u2500b\n \u2500\u2500\u2500\u2500\u2524\n \u2502 \u250c\u2500c\n \u2514\u2500a\u2500\u2524\n \u2502 \u250c\u2500d\n \u2514\u2500i\u2500\u2524\n \u2502 \u250c\u2500e\n \u2514\u2500h\u2500\u2524\n \u2502 \u250c\u2500f\n \u2514\u2500\u2500\u2500\u2524\n \u2514\u2500g\n ```\n- Pruning trees: The example below prunes the tree such that `b`, `c` and `i` are the only\n remaining leafs.\n ```python\n >>> tree.prune_by_names(['b', 'c', 'i'], inverse=True)\n >>> print(tree.ascii_art())\n \u250c\u2500b\n \u2500\u2500\u2500\u2500\u2524\n \u2502 \u250c\u2500c\n \u2514\u2500a\u2500\u2524\n \u2514\u2500i\n ```\n- Running a callable on a filtered set of nodes:\n ```python\n >>> tree.visit(lambda n: setattr(n, 'name', n.name.upper()), lambda n: n.name in ['a', 'b'])\n >>> print(tree.ascii_art())\n \u250c\u2500B\n \u2500\u2500\u2500\u2500\u2524\n \u2502 \u250c\u2500c\n \u2514\u2500A\u2500\u2524\n \u2514\u2500i\n ```\n- Removing (topologically) redundant internal nodes:\n ```python\n >>> tree.prune_by_names(['B', 'c'], inverse=True)\n >>> print(tree.ascii_art())\n \u250c\u2500B\n \u2500\u2500\u2500\u2500\u2524\n \u2514\u2500A \u2500\u2500c\n >>> tree.remove_redundant_nodes(keep_leaf_name=True)\n >>> print(tree.ascii_art())\n \u250c\u2500B\n \u2500\u2500\u2500\u2500\u2524\n \u2514\u2500c\n ```\n",
"bugtrack_url": null,
"license": "Apache 2.0",
"summary": "A python module to read and write the Newick format",
"version": "1.6.0",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "db1d9ca295834da208442c2bc116a03162392f4e7a56f00f4a5cfd988a398a55",
"md5": "5f00bd1caa2fcb6b1f4ebc2289c9a0c2",
"sha256": "60e1102acf8a4dd83393162e5f848ba2faced468d8a0165ce7614c259a8d4b5f"
},
"downloads": -1,
"filename": "newick-1.6.0-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "5f00bd1caa2fcb6b1f4ebc2289c9a0c2",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.7",
"size": 14726,
"upload_time": "2023-01-11T07:48:44",
"upload_time_iso_8601": "2023-01-11T07:48:44.591274Z",
"url": "https://files.pythonhosted.org/packages/db/1d/9ca295834da208442c2bc116a03162392f4e7a56f00f4a5cfd988a398a55/newick-1.6.0-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "4dd6af0c7a6d02ff49942128c97267d6a506f52f365d60636649fce57bf0e6bb",
"md5": "a180776ca7552bfff0ed64bf365a8b5f",
"sha256": "5610335826c0afd35afe66ebbacba0881e69f25097418c2f08456be629be6eac"
},
"downloads": -1,
"filename": "newick-1.6.0.tar.gz",
"has_sig": false,
"md5_digest": "a180776ca7552bfff0ed64bf365a8b5f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 15060,
"upload_time": "2023-01-11T07:48:46",
"upload_time_iso_8601": "2023-01-11T07:48:46.535599Z",
"url": "https://files.pythonhosted.org/packages/4d/d6/af0c7a6d02ff49942128c97267d6a506f52f365d60636649fce57bf0e6bb/newick-1.6.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-01-11 07:48:46",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "dlce-eva",
"github_project": "python-newick",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": null,
"specs": []
}
],
"lcname": "newick"
}
JSON
