taxutils-rs
Rust port of the Python
taxutils package, optimized for parallelism and incorporation into Rust repositories with its crate. The port was performed entirely by codex with GPT-5.6-sol. Available for download from bioconda.
The Rust package provides both:
- the
tucommand-line program - the
taxutilsRust library crate, [crates.io]
Installation
Install via conda or mamba from the bioconda forge:
conda install bioconda::taxutils-rs
Or install the command-line program from crates.io:
cargo install taxutils
tu --help
The Cargo package and library are named taxutils; the installed executable is
named tu. To use the library in another Rust project:
cargo add taxutils
Data directory
Like the Python package, taxutils-rs stores downloaded NCBI taxonomy and
accession resources in ./taxutils/ by default. Set TAXUTILS_GLOBALS to use a persistent location instead:
export TAXUTILS_GLOBALS=/path/to/taxutils/cache
tu filter -i input.fasta -o filtered.fasta --keep-taxids 2697049
The Rust library reads TAXUTILS_GLOBALS when TaxutilsOptions::default() or
TaxutilsBuilder::new() is constructed. Set the variable before constructing
the builder. Applications that manage configuration directly can set the same
path without an environment variable:
let tu = new
.save_folder
.low_memory
.keep_accession_downloads
.build?;
# Ok::
Managed resources include:
names.dmpandnodes.dmpfrom the NCBI taxdumptargets.jsonnucl_gb.accession2taxid.gz- optional
nucl_wgs.accession2taxid.gz nucl.accession2taxid.dbwhen using indexed SQLite lookup
Library
use ;
let mut tu = new
.low_memory
.wgs
.build?;
let accession = tu.parse_accession;
tu.load_a2t?;
let branch = tu.get_branch;
let subtree = tu.get_subtree;
let lca = tu.get_lca;
let distance = tu.get_distance;
let profile = tu.topology?;
let scale = tu.topology_stat?;
# Ok::
TaxutilsOptions::default() reads TAXUTILS_GLOBALS at construction time and
otherwise uses ./taxutils/, matching the Python package.
The library API is centered on TaxonomicUtils and provides the Python object
capabilities:
parse_accession,load_a2t, andget_t2aget_branch,get_subtree,get_ancestor,is_leaf,is_child, andis_descendentget_lca,get_distance,sort_taxa, andformat_treetopologyandtopology_statget_rank_orderandhigher_than_rankextract_accessions,clean_fasta_headers,grep_fasta, andfilter_fastafor embedding the same bounded, ordered FASTA workflows used bytulookup_accession_taxidsandlookup_taxid_accessionsfor bulk mapping without constructing the full taxonomy objectensure_accession_databasefor an atomic, tuned SQLite bulk build shared by Rust applications and the Python extension
SQLite databases are populated and indexed in a sibling temporary file, then
atomically installed only after the build succeeds. Set
TaxutilsBuilder::keep_accession_downloads(false) when using indexed mode to
discard the compressed NCBI inputs after the database is ready. They are
downloaded again only if a later compressed-file lookup or rebuild needs them.
Python uses one method name for both scalar and pandas/NumPy inputs. Rust keeps the same scalar names and provides explicit, parallel batch forms:
| Python capability | Rust scalar | Rust batch |
|---|---|---|
parse_accession |
parse_accession |
parse_accessions |
get_ancestor |
get_ancestor |
get_ancestors |
is_leaf |
is_leaf |
are_leaves |
is_child |
is_child |
are_children |
is_descendent |
is_descendent |
are_descendents |
topology |
topology |
topologies |
topology(..., stat=...) |
topology_stat |
topology_stats |
The object exposes names, nodes, parent, target_taxa, and a2t, using
typed Rust collections and records (Vec, HashMap, HashSet, TaxonNode,
and TopologyProfile) where Python returns pandas or NumPy containers.
The FASTA functions return structured counts and are shared by the tu binary
and language bindings, so both interfaces use the same implementation.
Command line
tu extract input.fasta -o accessions.txt
tu clean -i input.fasta -o clean.fasta
tu grep -i input.fasta -a NC_045512.2,NC_001422.1 -o hits.fasta
tu filter -i input.fasta -o filtered.fasta --keep-taxids 2697049
tu filter -i input.fasta --keep-taxids 2697049 # atomic in-place filtering
tu filter -i input.fasta -o filtered.fasta --remove-taxids 9606
The CLI uses all available logical CPUs for accession parsing and filtering.
Use tu --threads N <command> ... (or place --threads N after the command)
to cap worker threads. FASTA records are written in bounded, ordered batches,
so parallel execution does not reorder records. filter first collects one
entry per unique accession for a single bulk SQLite lookup, then scans the FASTA
again to write records. If --output is omitted, or names the input file,
filter writes <input>.tmp beside the input and atomically replaces the input
only after filtering finishes successfully.
Taxid and accession arguments may also name text files. grep --no-version
matches accessions without versions. filter uses the indexed SQLite mode just
like the Python CLI and is the command that uses the resources under
TAXUTILS_GLOBALS. extract, clean, and grep operate directly on FASTA
data and do not require the NCBI resource cache.
Performance model
- FASTA records are streamed in bounded batches instead of retaining sequence
data in memory.
filterretains one map entry per unique parsed accession. - Header parsing and filter decisions run in parallel; large buffered reads and writes preserve input order without issuing I/O for every FASTA line.
filterperforms one bulk accession-to-taxid query before its output pass, avoiding a SQLite connection, temporary table, and join for every batch.cleanis normally limited by sequential input/output throughput. Additional threads accelerate header parsing but do not divide the input file into shards.--batch-sizecontrols records per batch forextractandfilter, and approximate bytes per batch forgrep.- GB and WGS gzip mapping files are scanned concurrently when WGS mode is enabled.
- SQLite lookups use indexed temporary-table joins instead of one query per key.
- NCBI dump parsing avoids allocating a temporary field vector for every row.
- Batch accession parsing, ancestor lookup, rank checks, target expansion, node
materialization, and
topologiesuse the shared Rayon worker pool.