Trait taxonomy::Taxonomy

pub trait Taxonomy<'t, T>where
    T: Clone + Debug + Display + PartialEq + 't,{
    // Required methods
    fn root(&'t self) -> T;
    fn children(&'t self, tax_id: T) -> TaxonomyResult<Vec<T>>;
    fn descendants(&'t self, tax_id: T) -> TaxonomyResult<Vec<T>>;
    fn parent(&'t self, tax_id: T) -> TaxonomyResult<Option<(T, f32)>>;
    fn name(&'t self, tax_id: T) -> TaxonomyResult<&str>;
    fn rank(&'t self, tax_id: T) -> TaxonomyResult<TaxRank>;

    // Provided methods
    fn lineage(&'t self, tax_id: T) -> TaxonomyResult<Vec<T>> { ... }
    fn parent_at_rank(
        &'t self,
        tax_id: T,
        rank: TaxRank
    ) -> TaxonomyResult<Option<(T, f32)>> { ... }
    fn lca(&'t self, id1: T, id2: T) -> TaxonomyResult<T> { ... }
    fn data(
        &'t self,
        _tax_id: T
    ) -> TaxonomyResult<Cow<'t, HashMap<String, Value>>> { ... }
    fn traverse(&'t self, node: T) -> TaxonomyResult<TaxonomyIterator<'t, T>>
       where Self: Sized { ... }
    fn len(&'t self) -> usize
       where Self: Sized { ... }
    fn is_empty(&'t self) -> bool
       where Self: Sized { ... }
}

The trait to implement for each form we implement. It does include some default implementations for a few functions as well as a way to iterate through it, starting with the specified node.

Required Methods

fn root(&'t self) -> T

Returns the root node of the entire tree.

fn children(&'t self, tax_id: T) -> TaxonomyResult<Vec<T>>

Returns a Vec of all the direct children IDs of the given tax_id.

fn descendants(&'t self, tax_id: T) -> TaxonomyResult<Vec<T>>

Returns a Vec of all the children IDs of the given tax_id.

fn parent(&'t self, tax_id: T) -> TaxonomyResult<Option<(T, f32)>>

Returns the parent of the given taxonomic node and the distance to said parent. The parent of the root node will return None.

fn name(&'t self, tax_id: T) -> TaxonomyResult<&str>

Returns the name of the tax_id provided.

fn rank(&'t self, tax_id: T) -> TaxonomyResult<TaxRank>

Returns the taxonomic rank of the tax_id provided.

Provided Methods

fn lineage(&'t self, tax_id: T) -> TaxonomyResult<Vec<T>>

Returns a Vec of taxonomy nodes from the one provided back to root. This method must return the node itself as the first entry in the list and the root node as the last entry in the list.

fn parent_at_rank(
&'t self,
tax_id: T,
rank: TaxRank
) -> TaxonomyResult<Option<(T, f32)>>

Returns the parent at a given taxonomic rank (note this may not be the immediate parent). This also returns the distance to that parent.

fn lca(&'t self, id1: T, id2: T) -> TaxonomyResult<T>

Returns the first common parent between two nodes. E.g. for the tree:

/– C – D

A – B –

-- E

The LCA (lowest common ancestor) of nodes D and E is node B and the LCA of nodes D and C is node C itself.

fn data(&'t self, _tax_id: T) -> TaxonomyResult<Cow<'t, HashMap<String, Value>>>

Returns the additional data at the given tax id node This is only used by the json taxonomy so the value is serde_json::Value By default it just returns an empty hashmap

fn traverse(&'t self, node: T) -> TaxonomyResult<TaxonomyIterator<'t, T>>where
Self: Sized,

Generates an iterator that traces over the entire taxonomic tree from the given node. During preorder traversal, it returns (T, true) and during postorder traversal it returns (T, false)

fn len(&'t self) -> usizewhere
Self: Sized,

Returns the number of nodes in the taxonomy

fn is_empty(&'t self) -> boolwhere
Self: Sized,

Determines if there are any nodes at all in the taxonomy. This should almost always be implemented for performance reasons.

Implementors

impl<'t> Taxonomy<'t, &'t str> for GeneralTaxonomy

This is the implementation for &str taxonomy access for a more end-user understandable (but slightly slower) workflow.

impl<'t> Taxonomy<'t, usize> for GeneralTaxonomy

This is the implementation for “internal” tax ID lookup; these IDs are arbitrary (they’re positions of the tax nodes in the internal array) and not linked at all to the “external” (e.g. NCBI) IDs. Using these IDs directly can lead to a decent speed up without having to build indices. This is about 3-8x faster than the &str impl, depending on the usage.