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

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.7
File Size Uploaded Provenance Actions
taxonomy-0.10.7.tar.gz 114.9 kB Without provenance Details for taxonomy-0.10.7.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for taxonomy 0.10.7
File Actions
taxonomy-0.10.7-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.7-cp315-cp315-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
taxonomy-0.10.7-cp315-cp315-macosx_11_0_arm64.whl CPython 3.15 CPython 3.15 macOS 11.0+ ARM64 Details for taxonomy-0.10.7-cp315-cp315-macosx_11_0_arm64.whl
taxonomy-0.10.7-cp315-cp315-macosx_10_7_x86_64.whl CPython 3.15 CPython 3.15 macOS 10.7+ x86-64 Details for taxonomy-0.10.7-cp315-cp315-macosx_10_7_x86_64.whl
taxonomy-0.10.7-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.7-cp314-cp314-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
taxonomy-0.10.7-cp314-cp314-macosx_11_0_arm64.whl CPython 3.14 CPython 3.14 macOS 11.0+ ARM64 Details for taxonomy-0.10.7-cp314-cp314-macosx_11_0_arm64.whl
taxonomy-0.10.7-cp314-cp314-macosx_10_7_x86_64.whl CPython 3.14 CPython 3.14 macOS 10.7+ x86-64 Details for taxonomy-0.10.7-cp314-cp314-macosx_10_7_x86_64.whl
taxonomy-0.10.7-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.7-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
taxonomy-0.10.7-cp313-cp313-macosx_11_0_arm64.whl CPython 3.13 CPython 3.13 macOS 11.0+ ARM64 Details for taxonomy-0.10.7-cp313-cp313-macosx_11_0_arm64.whl
taxonomy-0.10.7-cp313-cp313-macosx_10_7_x86_64.whl CPython 3.13 CPython 3.13 macOS 10.7+ x86-64 Details for taxonomy-0.10.7-cp313-cp313-macosx_10_7_x86_64.whl
taxonomy-0.10.7-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.7-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
taxonomy-0.10.7-cp312-cp312-macosx_11_0_arm64.whl CPython 3.12 CPython 3.12 macOS 11.0+ ARM64 Details for taxonomy-0.10.7-cp312-cp312-macosx_11_0_arm64.whl
taxonomy-0.10.7-cp312-cp312-macosx_10_7_x86_64.whl CPython 3.12 CPython 3.12 macOS 10.7+ x86-64 Details for taxonomy-0.10.7-cp312-cp312-macosx_10_7_x86_64.whl
taxonomy-0.10.7-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.7-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
taxonomy-0.10.7-cp311-cp311-macosx_11_0_arm64.whl CPython 3.11 CPython 3.11 macOS 11.0+ ARM64 Details for taxonomy-0.10.7-cp311-cp311-macosx_11_0_arm64.whl
taxonomy-0.10.7-cp311-cp311-macosx_10_7_x86_64.whl CPython 3.11 CPython 3.11 macOS 10.7+ x86-64 Details for taxonomy-0.10.7-cp311-cp311-macosx_10_7_x86_64.whl

Total release size: 7.4 MB

Release files / taxonomy-0.10.7.tar.gz

Download URL taxonomy-0.10.7.tar.gz
Size 114.9 kB
Tags Source
SHA-256 checksum
How to use checksums
68e45bdbe947268c059360b645a85f49f5488fd03daad19c5dd853431c1837e5
BLAKE2b-256 checksum
How to use checksums
95cb0c26e95549be0d1c22127fbd00eaf0a6d4e28b1c60861daf577e6e0e2d99
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.16.0

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

Download URL taxonomy-0.10.7-cp315-cp315-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Size 520.7 kB
Tags CPython 3.15 Linux glibc 2.17+ x86-64
SHA-256 checksum
How to use checksums
5ef0dbf942c5ed477017696ece65912884e02d0faef3467edd8da9634834fa87
BLAKE2b-256 checksum
How to use checksums
81bfd2c5bae413b43aa199f49d1e85c262c5771003d72546bc658a9c30a30527
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.16.0

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

Download URL taxonomy-0.10.7-cp315-cp315-macosx_11_0_arm64.whl
Size 458.8 kB
Tags CPython 3.15 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
a7d6390bdfc4952ade0dc52fa168b91f22112d5d45abf5ffc702268c25b2235b
BLAKE2b-256 checksum
How to use checksums
19d406a27a76c6abde9af8f3edb892b4422588c0b2dd9d31858d4f03b59f0493
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.16.0

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

Download URL taxonomy-0.10.7-cp315-cp315-macosx_10_7_x86_64.whl
Size 469.6 kB
Tags CPython 3.15 macOS 10.7+ x86-64
SHA-256 checksum
How to use checksums
136a21fe4e5ac6c87e78b996e536961179bcb6f8e67fa09e2645fd84d8e04ec3
BLAKE2b-256 checksum
How to use checksums
a573decf90b33449d68e9cf5295842b1574b9606a1e95c185f2fde1719c7eaea
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.16.0

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

Download URL taxonomy-0.10.7-cp314-cp314-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Size 520.5 kB
Tags CPython 3.14 Linux glibc 2.17+ x86-64
SHA-256 checksum
How to use checksums
65949c0ca01f18df9a4fa44aacaa55534853770309058f94be3fe435ff2b08f3
BLAKE2b-256 checksum
How to use checksums
fcd78aa69136e8defb47b903bd6c00d098df8ff767ad8f7fac07ee7972016bbc
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.16.0

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

Download URL taxonomy-0.10.7-cp314-cp314-macosx_11_0_arm64.whl
Size 458.6 kB
Tags CPython 3.14 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
6249bbce62169251ed501b58da604a7f1171edad4e442a0aa5c30b6339a65bfd
BLAKE2b-256 checksum
How to use checksums
35c3d904ebd1ad35f716e9f58e8d9316c8f29610f11d0103234438702f6b3db0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.16.0

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

Download URL taxonomy-0.10.7-cp314-cp314-macosx_10_7_x86_64.whl
Size 469.7 kB
Tags CPython 3.14 macOS 10.7+ x86-64
SHA-256 checksum
How to use checksums
ae3b6e0008b21771a5dc39ebc22c276f1b47e1fb42dbdcbbea6ed934fcc31a40
BLAKE2b-256 checksum
How to use checksums
97763b078bfcdecb51f477bb462a484cfcb637e5e318bde709e804c981b803a9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.16.0

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

Download URL taxonomy-0.10.7-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Size 519.5 kB
Tags CPython 3.13 Linux glibc 2.17+ x86-64
SHA-256 checksum
How to use checksums
04dd7f158e2b977dc0ea2fa76022cf80e64caac012f361282f4050029371d33b
BLAKE2b-256 checksum
How to use checksums
67f2e7627d44745681b5fee60960ccac98c8124a831998f96fc607afa404f904
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.16.0

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

Download URL taxonomy-0.10.7-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
821946e45b8713024dafec136f089db3558b21b78ab7258a621b130b18dcc903
BLAKE2b-256 checksum
How to use checksums
8478588a60343904b4db25ac13cf3094e115c91d1550e11697392f1c3b9dd262
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.16.0

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

Download URL taxonomy-0.10.7-cp313-cp313-macosx_10_7_x86_64.whl
Size 466.5 kB
Tags CPython 3.13 macOS 10.7+ x86-64
SHA-256 checksum
How to use checksums
bd09d4d23a9d58d5f5f557a0c95195b50dfc792e8466ca6087ef1f5064a06267
BLAKE2b-256 checksum
How to use checksums
565f2d62970fb39d97bd35a6de54bd8b8885a2338751f34646c8eb22e220d06c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.16.0

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

Download URL taxonomy-0.10.7-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Size 520.1 kB
Tags CPython 3.12 Linux glibc 2.17+ x86-64
SHA-256 checksum
How to use checksums
4ebcbaca25566fe16bc1c1cf4ff2bfb486922fefe43d8967902dada4f6e42024
BLAKE2b-256 checksum
How to use checksums
cf158f51a06f53b065029b99d68bb43956a8083b8f9e9b2b448bf5ac5dd84f98
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.16.0

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

Download URL taxonomy-0.10.7-cp312-cp312-macosx_11_0_arm64.whl
Size 456.5 kB
Tags CPython 3.12 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
af25492d5325058b57f3b7536f7a77a5cf89e7d130d86843d515073719bbbc68
BLAKE2b-256 checksum
How to use checksums
0f9ca7c06824c8e70184c6b2900d78dfc6ac4a9239790407043696f45bf76354
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.16.0

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

Download URL taxonomy-0.10.7-cp312-cp312-macosx_10_7_x86_64.whl
Size 468.2 kB
Tags CPython 3.12 macOS 10.7+ x86-64
SHA-256 checksum
How to use checksums
9a8be49ef85d4168f1b2ff09f4df95608c4354fe2d014ddd20ccd8c133908837
BLAKE2b-256 checksum
How to use checksums
509a29012967ccb3273015d3e3f112b7b1917a152d763af7409c40e513b92494
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.16.0

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

Download URL taxonomy-0.10.7-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Size 524.2 kB
Tags CPython 3.11 Linux glibc 2.17+ x86-64
SHA-256 checksum
How to use checksums
40d74a704848b562ac42124913f6c9f6527b51936e6e47e36d7dfbb56e79841f
BLAKE2b-256 checksum
How to use checksums
680e2abc67da03f62adaa7762a562c0deb4a1607e681fd636ddab19241b6e097
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.16.0

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

Download URL taxonomy-0.10.7-cp311-cp311-macosx_11_0_arm64.whl
Size 460.9 kB
Tags CPython 3.11 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
65e599ec16533886d9cd696d5f6d432afd444585ff250fecfcac17eee2e82951
BLAKE2b-256 checksum
How to use checksums
dc2946b8a3d9e60cdcc9930a5229c145c335c4d66f4033dfb133be94fc20fdd9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.16.0

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

Download URL taxonomy-0.10.7-cp311-cp311-macosx_10_7_x86_64.whl
Size 466.9 kB
Tags CPython 3.11 macOS 10.7+ x86-64
SHA-256 checksum
How to use checksums
8b33fd6572f5ab572b50fc8b2b13ef08ee4bb8033ccbed81c5cc12b63245cc9e
BLAKE2b-256 checksum
How to use checksums
72269cbc0f29e64b2a25de99f6363e321b1d2d03552b225188cb46884cb63f84
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.16.0

Security for taxonomy 0.10.7

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