Skip to main content

Taxonomy

PyPI version Crates version CI

This is a Rust library for reading, writing, and editing biological taxonomies. There are associated Python bindings for accessing most of the functionality from Python.

This library was developed initially as a component in One Codex's metagenomic classification pipeline before being refactored out, expanded, and open-sourced. It is designed such that it can be used as is with a number of taxonomic formats or the Taxonomy trait it provides can be used to add last common ancestor, traversal, etc. methods to a downstream package's taxonomy implementation.

The library ships with a number of features:

  • Common support for taxonomy handling across Rust and Python
  • Fast and low(er) memory usage
  • NCBI taxonomy, JSON ("tree" and "node_link_data" formats), Newick, and PhyloXML support
  • Easily extensible (in Rust) to support other formats and operations

Installation

Rust

This library can be added to an existing Cargo.toml file and installed straight from crates.io.

Python

You can install the Python bindings directly from PyPI (binaries are only built for select architectures) with:

pip install taxonomy

Python Usage

The Python taxonomy API can open and manipulate all of the formats from the Rust library. Note that Taxonomy IDs in NCBI format are integers, but they're converted to strings on import. We find working with "string taxonomy IDs" greatly simplifies inter-operation between different taxonomy systems.

Loading a taxonomy

Taxonomy can be loaded from a variety of sources.

  1. Taxonomy.from_newick(value: str): loads a Taxonomy from a Newick-encoded string.

  2. Taxonomy.from_ncbi(ncbi_filder: str): loads a Taxonomy from a pair of NCBI dump files. The folder needs to contain the individual files in the NCBI taxonomy directory (e.g. nodes.dmp and names.dmp).

  3. Taxonomy.from_json(value: str, /, json_pointer: str): loads a Taxonomy from a JSON-encoded string. The format can either be of the tree or node_link_data types and will be automatically detected (more details on both formats on the documentation. If json_pointer is specified, the JSON will be traversed to that sub-object before being parsed as a taxonomy.

  4. Taxonomy.from_phyloxml(value: &str): loads a Taxonomy from a PhyloXML-encoded string. Experimental

  5. Taxonomy.from_gtdb(value: &str): loads a Taxonomy from a GTDB-encoded string. Experimental

Exporting a taxonomy

Assuming that the taxonomy has been instantiated as a variable named tax.

  1. tax.to_newick(): exports a Taxonomy as a Newick-encoded byte string.
  2. tax.to_json_tree(): exports a Taxonomy as a JSON-encoded byte string in a tree format
  3. tax.to_json_node_links(): exports a Taxonomy as a JSON-encoded byte string in a node links format

Using a taxonomy

Assuming that the taxonomy has been instantiated as a variable named tax. Note that TaxonomyNode is a class with the following schema:

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

Note that tax_id in parameters passed in functions described below are string but for example in the case of NCBI need to be essentially quoting integers: 562 -> "562". If you loaded a taxonomy via JSON and you had additional data in your file, you can access it via indexing, node["readcount"] for example.

tax.clone() -> Taxonomy

Return a new taxonomy, equivalent to a deep copy.

tax.root -> TaxonomyNode

Points to the root of the taxonomy

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

Return the immediate parent TaxonomyNode of the node id.

If at_rank is provided, scan all the nodes in the node's lineage and return the parent id at that rank.

Examples:

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

Same as parent but return the distance in addition, as a (TaxonomyNode, float) tuple.

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

Returns the node at that id. Returns None if not found. You can also use indexing to accomplish that: tax["some_id"] but this will raise an exception if the node is not found.

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

Returns all the nodes with that name. In NCBI, it only accounts for scientific names and not synonyms.

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

Returns all direct nodes below the given tax id.

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

Returns all nodes below the given tax id. Equivalent to running tax.children recursively on the initial result of tax.children(tax_id).

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

Returns all nodes above the given tax id, including itself.

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

Returns all nodes above the given tax id.

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

Returns the lowest common ancestor for the 2 given nodes.

tax.prune(keep: List[str], remove: List[str])-> Taxonomy

Return a copy of the taxonomy containing:

  • only the nodes in keep and their parents if provided
  • all of the nodes except those in remove and their children if provided

tax.remove_node(tax_id: str)

Remove the node from the tree, re-attaching parents as needed: only a single node is removed.

tax.add_node(parent_tax_id: str, new_tax_id: str, /, name: str, rank: str)

Add a new node to the tree at the parent provided.

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

Edit properties on a taxonomy node.

internal_index(tax_id: str)

Return internal integer index used by some applications. For the JSON node-link format, this is the positional index of each node in the nodes array.

Exceptions

Only one exception is raised intentionally by the library: TaxonomyError. If you get a pyo3_runtime.PanicException (or anything with pyo3 in its name), this is a bug in the underlying Rust library, please open an issue.

Development

Rust

There is a test suite runable with cargo test. To test the Python-bindings you need to use the additional python_test feature: cargo test --features python_test.

Python

To work on the Python library on a Mac OS X/Unix system (requires 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 .

Building binary wheels and pushing to PyPI

There is a Github Workflow that will build Python wheels for macOS (x86 and ARM) and Ubuntu (x86). To run, create a new release.

To build wheels locally, run:

uv venv --python 3.11 #
source .venv/bin/activate
uv build

# or, using maturin by itself:

maturin build --features python --release --strip^

Other Taxonomy Libraries

There are taxonomic toolkits for other programming languages that offer different features and provided some inspiration for this library:

ETE Toolkit (http://etetoolkit.org/) A Python taxonomy library

Taxize (https://ropensci.github.io/taxize-book/) An R toolkit for working with taxonomic data

Metadata

Release files for taxonomy 0.10.6

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for taxonomy 0.10.6
File Size Uploaded Provenance Actions
taxonomy-0.10.6.tar.gz 114.9 kB Without provenance Details for taxonomy-0.10.6.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for taxonomy 0.10.6
File Actions
taxonomy-0.10.6-cp315-cp315-manylinux_2_17_x86_64.manylinux2014_x86_64.whl CPython 3.15 CPython 3.15 Linux glibc 2.17+ x86-64 Details for taxonomy-0.10.6-cp315-cp315-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
taxonomy-0.10.6-cp315-cp315-macosx_11_0_arm64.whl CPython 3.15 CPython 3.15 macOS 11.0+ ARM64 Details for taxonomy-0.10.6-cp315-cp315-macosx_11_0_arm64.whl
taxonomy-0.10.6-cp315-cp315-macosx_10_7_x86_64.whl CPython 3.15 CPython 3.15 macOS 10.7+ x86-64 Details for taxonomy-0.10.6-cp315-cp315-macosx_10_7_x86_64.whl
taxonomy-0.10.6-cp314-cp314-manylinux_2_17_x86_64.manylinux2014_x86_64.whl CPython 3.14 CPython 3.14 Linux glibc 2.17+ x86-64 Details for taxonomy-0.10.6-cp314-cp314-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
taxonomy-0.10.6-cp314-cp314-macosx_11_0_arm64.whl CPython 3.14 CPython 3.14 macOS 11.0+ ARM64 Details for taxonomy-0.10.6-cp314-cp314-macosx_11_0_arm64.whl
taxonomy-0.10.6-cp314-cp314-macosx_10_7_x86_64.whl CPython 3.14 CPython 3.14 macOS 10.7+ x86-64 Details for taxonomy-0.10.6-cp314-cp314-macosx_10_7_x86_64.whl
taxonomy-0.10.6-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl CPython 3.13 CPython 3.13 Linux glibc 2.17+ x86-64 Details for taxonomy-0.10.6-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
taxonomy-0.10.6-cp313-cp313-macosx_11_0_arm64.whl CPython 3.13 CPython 3.13 macOS 11.0+ ARM64 Details for taxonomy-0.10.6-cp313-cp313-macosx_11_0_arm64.whl
taxonomy-0.10.6-cp313-cp313-macosx_10_7_x86_64.whl CPython 3.13 CPython 3.13 macOS 10.7+ x86-64 Details for taxonomy-0.10.6-cp313-cp313-macosx_10_7_x86_64.whl
taxonomy-0.10.6-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl CPython 3.12 CPython 3.12 Linux glibc 2.17+ x86-64 Details for taxonomy-0.10.6-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
taxonomy-0.10.6-cp312-cp312-macosx_11_0_arm64.whl CPython 3.12 CPython 3.12 macOS 11.0+ ARM64 Details for taxonomy-0.10.6-cp312-cp312-macosx_11_0_arm64.whl
taxonomy-0.10.6-cp312-cp312-macosx_10_7_x86_64.whl CPython 3.12 CPython 3.12 macOS 10.7+ x86-64 Details for taxonomy-0.10.6-cp312-cp312-macosx_10_7_x86_64.whl
taxonomy-0.10.6-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl CPython 3.11 CPython 3.11 Linux glibc 2.17+ x86-64 Details for taxonomy-0.10.6-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
taxonomy-0.10.6-cp311-cp311-macosx_11_0_arm64.whl CPython 3.11 CPython 3.11 macOS 11.0+ ARM64 Details for taxonomy-0.10.6-cp311-cp311-macosx_11_0_arm64.whl
taxonomy-0.10.6-cp311-cp311-macosx_10_7_x86_64.whl CPython 3.11 CPython 3.11 macOS 10.7+ x86-64 Details for taxonomy-0.10.6-cp311-cp311-macosx_10_7_x86_64.whl

Total release size: 7.4 MB

Release files / taxonomy-0.10.6.tar.gz

Download URL taxonomy-0.10.6.tar.gz
Size 114.9 kB
Tags Source
SHA-256 checksum
How to use checksums
d4335c7d8be118944602115935cd8a74cbdce2070daaca1b17f7b12f1db930c1
BLAKE2b-256 checksum
How to use checksums
b7a05b3b472cdaff085e529bd0fecd65ca324428a2d750e7cc5ca5dadd5e0f3b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.15.0

Release files / taxonomy-0.10.6-cp315-cp315-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Download URL taxonomy-0.10.6-cp315-cp315-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Size 521.2 kB
Tags CPython 3.15 Linux glibc 2.17+ x86-64
SHA-256 checksum
How to use checksums
915b32c94b4cd2a425ee4d18752a1a16e3de56a1f7520efd6b735b17da3bdd67
BLAKE2b-256 checksum
How to use checksums
7dfd472a0b444379f3e5ae68fc4e9ca77a5a06f3d6efb40fa8a75800e5258d62
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.15.0

Release files / taxonomy-0.10.6-cp315-cp315-macosx_11_0_arm64.whl

Download URL taxonomy-0.10.6-cp315-cp315-macosx_11_0_arm64.whl
Size 458.0 kB
Tags CPython 3.15 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
05ace1349af55867460203a06a9ec6e52e1db86fff1396622d7d2d55d5953efa
BLAKE2b-256 checksum
How to use checksums
96affc22806e1e36ac5565d85e78aaf12edcaff5679b78febb6db958a8969e0f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.15.0

Release files / taxonomy-0.10.6-cp315-cp315-macosx_10_7_x86_64.whl

Download URL taxonomy-0.10.6-cp315-cp315-macosx_10_7_x86_64.whl
Size 470.2 kB
Tags CPython 3.15 macOS 10.7+ x86-64
SHA-256 checksum
How to use checksums
b4cf54ff808bd2acc352bede8abce180c7e7e45ab5bfe387b8b0a1231bcd452d
BLAKE2b-256 checksum
How to use checksums
2452cb849ac5355ab4eecd18a6c1546ff7b1d8b12f2c3c5670704ad1f736fb5b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.15.0

Release files / taxonomy-0.10.6-cp314-cp314-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Download URL taxonomy-0.10.6-cp314-cp314-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Size 520.9 kB
Tags CPython 3.14 Linux glibc 2.17+ x86-64
SHA-256 checksum
How to use checksums
f8a4cc45d7e97842f8cd5fb23534dcb6e4c71ffd3ade65294645e8657c874ade
BLAKE2b-256 checksum
How to use checksums
6dfc28381933842f875c807571f50a4894f9cd373dca138bc8f4a2b2cda29966
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.15.0

Release files / taxonomy-0.10.6-cp314-cp314-macosx_11_0_arm64.whl

Download URL taxonomy-0.10.6-cp314-cp314-macosx_11_0_arm64.whl
Size 458.0 kB
Tags CPython 3.14 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
40d93687b319bcd67766bad745ea2839877116a5fdf4f93696d82109f3efae0f
BLAKE2b-256 checksum
How to use checksums
b2a39e1a68eb9b053cbe7c7fb803db88b3dfca310f87b4b3ed4ad1790a5f094e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.15.0

Release files / taxonomy-0.10.6-cp314-cp314-macosx_10_7_x86_64.whl

Download URL taxonomy-0.10.6-cp314-cp314-macosx_10_7_x86_64.whl
Size 468.7 kB
Tags CPython 3.14 macOS 10.7+ x86-64
SHA-256 checksum
How to use checksums
7be88500cb1e62df1271cb24f6ad3e2bc8c0db12c9a28130accdcb3a1b5646ca
BLAKE2b-256 checksum
How to use checksums
d08d7053e298abfb514889b6969373e8ae76a084d4302202e321f1ba6fe97c6c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.15.0

Release files / taxonomy-0.10.6-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Download URL taxonomy-0.10.6-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Size 519.9 kB
Tags CPython 3.13 Linux glibc 2.17+ x86-64
SHA-256 checksum
How to use checksums
dad859724c4a6d7e414a99b024dc832b0a99ad53a71d9617fc04ec38b27350dd
BLAKE2b-256 checksum
How to use checksums
a776cb33d27f65b0769762a8dbb916b44e317f0c61de2fece55032013311bce6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.15.0

Release files / taxonomy-0.10.6-cp313-cp313-macosx_11_0_arm64.whl

Download URL taxonomy-0.10.6-cp313-cp313-macosx_11_0_arm64.whl
Size 456.9 kB
Tags CPython 3.13 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
3b0b324e052911212099142d8680d77e8c7cd6b9d9c7a85ebb2ef82762fd525b
BLAKE2b-256 checksum
How to use checksums
41ccb4bb669c5c4e3d0bcdb63485d96e63e9a612fe8d9a6c2b457f199bc12d73
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.15.0

Release files / taxonomy-0.10.6-cp313-cp313-macosx_10_7_x86_64.whl

Download URL taxonomy-0.10.6-cp313-cp313-macosx_10_7_x86_64.whl
Size 468.6 kB
Tags CPython 3.13 macOS 10.7+ x86-64
SHA-256 checksum
How to use checksums
201ffdb201676d9795a71aaee642e4c05efa4d845bc3fa2c7f00ee3a6514a098
BLAKE2b-256 checksum
How to use checksums
5f2797d6bf630f38a42bc2711a3c8e732df5a025ec6b1e7b01688cffb10292b4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.15.0

Release files / taxonomy-0.10.6-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Download URL taxonomy-0.10.6-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Size 518.9 kB
Tags CPython 3.12 Linux glibc 2.17+ x86-64
SHA-256 checksum
How to use checksums
9709be06e64871ab99eb36c8e38a9feae7b26b1aa63c73e40e38c3976d45f917
BLAKE2b-256 checksum
How to use checksums
16289691d0fdfe03e4029e5975a2d581c8e3139725e3100b68039bd748217fb1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.15.0

Release files / taxonomy-0.10.6-cp312-cp312-macosx_11_0_arm64.whl

Download URL taxonomy-0.10.6-cp312-cp312-macosx_11_0_arm64.whl
Size 456.7 kB
Tags CPython 3.12 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
4a5afa2f2bfa09f93faa6510fa494927b2b54db580638955292a0d268a30a77d
BLAKE2b-256 checksum
How to use checksums
b565e8f0607e24738c259cb0a9b433a162af34363d5f604d70874b87d88396d4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.15.0

Release files / taxonomy-0.10.6-cp312-cp312-macosx_10_7_x86_64.whl

Download URL taxonomy-0.10.6-cp312-cp312-macosx_10_7_x86_64.whl
Size 467.7 kB
Tags CPython 3.12 macOS 10.7+ x86-64
SHA-256 checksum
How to use checksums
69b66f6f086b6a1e99e125e02b3e640c2bd0551bd29bf1df517488fd4b017846
BLAKE2b-256 checksum
How to use checksums
bbf5e41a3ac0376963a47a41049aa1f163d9630e902f0ae55ee97d70f785c5c6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.15.0

Release files / taxonomy-0.10.6-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Download URL taxonomy-0.10.6-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Size 524.5 kB
Tags CPython 3.11 Linux glibc 2.17+ x86-64
SHA-256 checksum
How to use checksums
c5550c8bec0eb8a691d0f6df2c68939547742eb9bf8621589b2d60613e1f9c00
BLAKE2b-256 checksum
How to use checksums
6b2767aa370a51833933a6ec2de484c3059a92fd8e88c8b72da9fe78c12498ca
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.15.0

Release files / taxonomy-0.10.6-cp311-cp311-macosx_11_0_arm64.whl

Download URL taxonomy-0.10.6-cp311-cp311-macosx_11_0_arm64.whl
Size 461.6 kB
Tags CPython 3.11 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
29c5059f920675059facec774e726644af8ed9e1f30c1e15333df8aaa217abc2
BLAKE2b-256 checksum
How to use checksums
2e0abe53a3660151bf6f7daeba5a73e29e67700c1be3de9dd5ffcb90dd191886
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.15.0

Release files / taxonomy-0.10.6-cp311-cp311-macosx_10_7_x86_64.whl

Download URL taxonomy-0.10.6-cp311-cp311-macosx_10_7_x86_64.whl
Size 466.7 kB
Tags CPython 3.11 macOS 10.7+ x86-64
SHA-256 checksum
How to use checksums
b30e5a603a860c87f6f1d4004b73fe1c34f41b4c4c7a490917b49a6c039850da
BLAKE2b-256 checksum
How to use checksums
4d74f00c3a4c513cc90314ca8dbc2a807cfd9815399042bcd52a66208d935547
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.15.0

Security for taxonomy 0.10.6

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page