Package: taxonomy
TaxonomyThis 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 usedas iswith a number of taxonomic formatsorthe 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 PythonFast and low(er) memory usageNCBI taxonomy, JSON ("tree" and "node_link_data" formats), Newick, and PhyloXML supportEasily extensible (in Rust) to support other formats and operationsInstallationRustThis library can be added to an existing Cargo.toml file and installed straight from crates.io.PythonYou can install the Python bindings directly from PyPI (binaries are only built for select architectures) with:pipinstalltaxonomyPython UsageThe 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 taxonomyTaxonomy can be loaded from a variety of sources.Taxonomy.from_newick(value: str): loads a Taxonomy from a Newick-encoded string.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).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 onthe documentation. Ifjson_pointeris specified, the JSON will be traversed to that sub-object before being parsed as a taxonomy.Taxonomy.from_phyloxml(value: &str): loads a Taxonomy from a PhyloXML-encoded string.ExperimentalTaxonomy.from_gtdb(value: &str): loads a Taxonomy from a GTDB-encoded string.ExperimentalExporting a taxonomyAssuming that the taxonomy has been instantiated as a variable namedtax.tax.to_newick(): exports a Taxonomy as a Newick-encoded byte string.tax.to_json_tree(): exports a Taxonomy as a JSON-encoded byte string in a tree formattax.to_json_node_links(): exports a Taxonomy as a JSON-encoded byte string in a node links formatUsing a taxonomyAssuming that the taxonomy has been instantiated as a variable namedtax. Note thatTaxonomyNodeis a class with
the following schema:classTaxonomyNode:id:strname:strparent:Optional[str]rank:strNote 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() -> TaxonomyReturn a new taxonomy, equivalent to a deep copy.tax.root -> TaxonomyNodePoints to the root of the taxonomytax.parent(tax_id: str, /, at_rank: str) -> Optional[TaxonomyNode]Return the immediate parent TaxonomyNode of the node id.Ifat_rankis 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 parentparent=tax.parent("unknown")tax.parent_with_distance(tax_id: str, /, at_rank: str) -> (Optional[TaxonomyNode], Optional[float])Same asparentbut return the distance in addition, as a(TaxonomyNode, float)tuple.tax.node(tax_id: str) -> Optional[TaxonomyNode]Returns the node at that id. ReturnsNoneif 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 forscientific namesand 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 runningtax.childrenrecursively on the initial result oftax.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 thelowest common ancestorfor the 2 given nodes.tax.prune(keep: List[str], remove: List[str])-> TaxonomyReturn a copy of the taxonomy containing:only the nodes inkeepand their parents if providedall of the nodes except those in remove and their children if providedtax.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)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.ExceptionsOnly one exception is raised intentionally by the library:TaxonomyError.
If you get apyo3_runtime.PanicException(or anything withpyo3in its name), this is a bug in the underlying Rust library, please open an issue.DevelopmentRustThere is a test suite runable withcargo test. To test the Python-bindings you need to use the additionalpython_testfeature:cargo test --features python_test.PythonTo work on the Python library on a Mac OS X/Unix system (requires Python 3):# you need the nightly version of Rust installedcurlhttps://sh.rustup.rs-sSf|sh# finally, install the library in the local virtualenvmaturindevelop--featurespython# or using pippipinstall.Building binary wheels and pushing to 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

# Upload the wheels to PyPI:
twine upload target/wheels/*Other Taxonomy LibrariesThere 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 libraryTaxize (https://ropensci.github.io/taxize-book/)An R toolkit for working with taxonomic data