python-newick

一个Python包，用于读取和写入Newick格式。

读取Newick

由于Newick为树集合指定了格式，因此所有读取Newick的函数都返回一个newick.Node对象列表。

• 从字符串读取

  >>> 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']
  

• 从类似文件的对象读取

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

• 从路径读取

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

支持的Newick方言

尽管Newick保留字符集（;(),:）相对较小，但它仍然经常被认为过于限制，尤其是在向树节点添加更多数据时。因此，Newick提供了两种机制来克服这种限制

• 引号标签以允许作为节点名称的任意文本，
• 注释括在方括号内。

引号节点标签

Newick中的节点标签可能被引用（即用单引号'括起来），以便添加其他情况下保留的字符。newick包支持引用标签。

>>> from newick import loads
>>> print(loads("('A:B','C''D')'E(F)'")[0].ascii_art())
         ┌─'A:B'
──'E(F)'─┤
         └─'C''D'

在程序创建Newick树时，名称可以（如果需要）自动引用

>>> 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')

注意：newick不提供解析从节点标签（如在基因组分类数据库分发的树中找到的）中获取的结构化数据的功能。

注释中的附加信息

"Newick规范"指出

注释括在方括号内，可以出现在任何位置

这催生了一系列专门的机制来向Newick树中插入附加数据。

newick包允许以两种方式处理注释。

• 忽略注释

  >>> newick.loads('[a comment](a,b)c;', strip_comments=True)[0].newick
  '(a,b)c'
  

• 将注释作为节点注释读取：多个软件包使用Newick注释来存储节点注释，例如*BEAST、MrBayes或TreeAnnotator。如果没有注释出现在无法将其解释为节点注释的位置，newick支持读取和写入这些注释

  >>> 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'
  

  注释可以位于节点标签和长度分隔符:之前和/或之后

• >>> 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']
  

注意，引号标签内的方括号将不会被视为注释或注释

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

还提供了一些读取节点注释中键值数据的支持。如果注释格式遵循NHX规范或MrBayes或BEAST软件使用的&<key>=<value>,...格式，则可以从dict Node.properties中访问附加数据

>>> newick.loads('(A,B)C[&&NHX:k1=v1:k2=v2];')[0].properties
{'k1': 'v1', 'k2': 'v2'}

限制

• 类型化节点属性不受支持。即Node.properties中的值始终是字符串。由于类型化属性往往特定于编写newick的应用程序，此级别的支持需要比仅从Newick字符串中可以安全推断出的树创建上下文更多知识。

  >>> newick.loads('(A,B)C[&range={1,5},support="100"];')[0].properties
  {'range': '{1,5}', 'support': '"100"'}
  

• 注释中的节点注释不是完全往返安全的。特别是，在序列化Newick节点时，每个节点可能有多个注释合并在一起（使用|作为分隔符）

  >>> newick.loads('(a,b)c[c1][c2]:3')[0].newick
  '(a,b)c[c1|c2]:3'
  

写入Newick

在读取操作的同时，有三个函数可以序列化单个Node对象或Node对象列表到Newick格式

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

可以使用Node类的工厂方法构建树

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

操作树

• 在终端显示树拓扑

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

• 修剪树：以下示例修剪树，使得b、c和i是唯一剩余的叶节点。

  >>> tree.prune_by_names(['b', 'c', 'i'], inverse=True)
  >>> print(tree.ascii_art())
      ┌─b
  ────┤
      │   ┌─c
      └─a─┤
          └─i
  

• 在过滤节点集中运行可调用对象

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

• 删除（拓扑上）冗余的内部节点

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