分类学

这是一个用于读取、写入和编辑生物分类学的 Rust 库。它还提供了与 Python 的相关绑定，以便从 Python 访问大部分功能。

该库最初是 One Codex 的宏基因组分类流程中的一个组件，后来被重构、扩展并开源。它设计得可以与多种分类学格式一起使用，或者可以使用它提供的 Taxonomy 特性将最后共同祖先、遍历等方法添加到下游包的分类学实现中。

该库具有以下功能

• Rust 和 Python 之间的分类学处理支持
• 快速且内存使用低
• 支持 NCBI 分类学、JSON ("tree" 和 "node_link_data" 格式)、Newick 和 PhyloXML
• 易于扩展（在 Rust 中）以支持其他格式和操作

安装

Rust

可以将此库添加到现有的 Cargo.toml 文件中，并通过 crates.io 直接安装。

Python

您可以直接从 PyPI 安装 Python 绑定（仅针对选定的架构构建二进制文件）：

pip install taxonomy

Python 使用方法

Python 分类学 API 可以打开和操作 Rust 库中的所有格式。请注意，NCBI 格式的 Taxonomy ID 是整数，但在导入时转换为字符串。我们发现使用“字符串分类学 ID”大大简化了不同分类学系统之间的互操作性。

加载分类学

可以从各种来源加载分类学。

1. Taxonomy.from_newick(value: str): 从Newick编码的字符串中加载一个Taxonomy。

2. Taxonomy.from_ncbi(ncbi_filder: str): 从一对NCBI转储文件中加载一个Taxonomy。文件夹需要包含NCBI分类目录中的单个文件（例如nodes.dmp和names.dmp）。

3. Taxonomy.from_json(value: str, /, json_pointer: str): 从JSON编码的字符串中加载一个Taxonomy。格式可以是树或node_link_data类型，并且将自动检测（有关这两种格式的更多详细信息，请参阅文档。如果指定了json_pointer，则JSON将遍历到该子对象，然后解析为分类。

4. Taxonomy.from_phyloxml(value: &str): 从PhyloXML编码的字符串中加载一个Taxonomy。 实验性

5. Taxonomy.from_gtdb(value: &str): 从GTDB编码的字符串中加载一个Taxonomy。 实验性

导出分类

假设分类已经被实例化为名为tax的变量。

1. tax.to_newick(): 将Taxonomy导出为Newick编码的字节字符串。
2. tax.to_json_tree(): 将Taxonomy导出为树格式的JSON编码的字节字符串
3. tax.to_json_node_links(): 将Taxonomy导出为节点链接格式的JSON编码的字节字符串

使用分类

假设分类已经被实例化为名为tax的变量。请注意，TaxonomyNode是一个具有以下模式的类

class TaxonomyNode:
    id: str
    name: str
    parent: Optional[str]
    rank: str

请注意，在下述函数中传递的参数中的tax_id是字符串，但在NCBI的例子中，它基本上需要是引号中的整数：562 -> "562"。如果您通过JSON加载了分类并且文件中有其他数据，您可以通过索引访问它，例如node["readcount"]。

tax.clone() ->分类学

返回一个新的分类，相当于深拷贝。

tax.root->TaxonomyNode

指向分类的根

tax.parent(tax_id: str, /,at_rank: str) ->可选[TaxonomyNode]

返回节点id的直接父TaxonomyNode。

如果提供了 at_rank，将扫描节点谱系中的所有节点，并返回该rank的父id。

示例

parent = tax.parent("612")
parent = tax.parent("612", at_rank="species")
parent = tax.parent("612")
# Both variables will be `None` if we can't find the parent
parent = tax.parent("unknown")

tax.parent_with_distance(tax_id: str, /,at_rank: str) -> (Optional[TaxonomyNode], Optional[float])

与 parent 相同，但还返回距离，作为 (TaxonomyNode, float) 元组。

tax.node(tax_id: str) ->可选[TaxonomyNode]

返回指定id的节点。如果未找到，则返回 None。您还可以使用索引来完成此操作：tax["some_id"]，但如果没有找到节点，这将会引发异常。

tax.find_all_by_name(name: str) ->列表[TaxonomyNode]

返回所有具有该名称的节点。在NCBI中，它只考虑学名而不是同义词。

tax.children(tax_id: str) ->列表[TaxonomyNode]

返回给定tax id下的所有直接节点。

tax.descendants(tax_id: str) ->列表[TaxonomyNode]

返回给定tax id下的所有节点。相当于在 tax.children 的初始结果上递归运行 tax.children(tax_id)。

tax.lineage(tax_id: str) ->列表[TaxonomyNode]

返回给定tax id上方（包括自身）的所有节点。

tax.parents(tax_id: str) ->列表[TaxonomyNode]

返回给定tax id上方的所有节点。

tax.lca(id1: str,id2: str) ->可选[TaxonomyNode]

返回两个给定节点之间的 最低公共祖先。

tax.prune(keep:列表[str],remove:列表[str])->分类学

返回一个包含

• 只有 keep 和（如果提供）其父节点的分类的副本
• 除了在remove中以及在（如果提供）其子节点之外的所有节点

tax.remove_node(tax_id: str)

从树中删除节点，并按需重新附加父节点：仅删除单个节点。

tax.add_node(parent_tax_id: str,new_tax_id: str)

在提供的父节点中向树中添加一个新节点。

edit_node(tax_id: str, /,name: str,rank: str,parent_id: str,parent_dist:float)

编辑分类节点上的属性。

internal_index(tax_id: str)

返回某些应用程序使用的内部整数索引。对于JSON节点链接格式，这是节点数组中每个节点的位置索引。

异常

库有意引发一个异常：TaxonomyError。如果您收到 pyo3_runtime.PanicException（或任何包含 pyo3 的名称）的异常，这是底层Rust库的错误，请提交一个问题。

开发

Rust

有一个可执行的测试套件，可以通过 cargo test 运行。要测试Python绑定，您需要使用额外的 python_test 功能：cargo test --features python_test。

Python

要在Mac OS X/Unix系统上工作（需要Python 3）

# you need the nightly version of Rust installed
curl https://sh.rustup.rs -sSf | sh

# finally, install the library in the local virtualenv
maturin develop --features python

# or using pip
pip install .

构建二进制轮和推送到PyPI

# The Mac build requires switching through a few different python versions
maturin build --features python --release --strip

# The linux build requires switching through different python versions and linux compatibility targets.
# For example, to build for Python 3.10 and manylinux2010 compatibility:
docker run --rm -v $(pwd):/io ghcr.io/pyo3/maturin:main build --features=python --release --strip --interpreter=python3.10 --compatibility=manylinux2010

# Upload the wheels to PyPI:
twine upload target/wheels/*

其他分类库

其他编程语言也有分类工具包，它们提供了不同的功能，并为这个库提供了一些灵感。

ETE工具包 (http://etetoolkit.org/) 一个Python分类库

Taxize (https://ropensci.github.io/taxize-book/) 一个用于处理分类数据的R工具包