Trait taxonomy::Taxonomy

pub trait Taxonomy<'t, T: 't, D: 't> where
    T: Clone + Debug + Display + PartialEq,
    D: Debug + PartialOrd + PartialEq + Sum, {
    fn root(&'t self) -> T;
    fn children(&'t self, tax_id: T) -> Result<Vec<T>>;
    fn parent(&'t self, tax_id: T) -> Result<Option<(T, D)>>;
    fn name(&self, tax_id: T) -> Result<&str>;
    fn rank(&self, tax_id: T) -> Result<TaxRank>;

    fn lineage(&'t self, tax_id: T) -> Result<Vec<T>> { ... }
    fn parent_at_rank(
        &'t self, 
        tax_id: T, 
        rank: TaxRank
    ) -> Result<Option<(T, D)>> { ... }
    fn lca(&'t self, id1: T, id2: T) -> Result<T> { ... }
    fn traverse(&'t self, node: T) -> Result<TaxonomyIterator<'t, T, D>>
    where
        Self: Sized,
    { ... }
    fn len(&'t self) -> usize
    where
        Self: Sized,
    { ... }
    fn is_empty(&'t self) -> bool
    where
        Self: Sized,
    { ... }
}

Taxonomy is a trait exposing a number of traversal and informational methods given a smaller number of required methods. This allows different taxonomic data structures with different memory/speed requirements to have a common set of methods. T is the type for the taxonomy ID and D for the distance

Required methods

fn root(&'t self) -> T

Returns the root node of the entire tree.

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

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

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

Returns the parent of the given taxonomic node and the distance to said parent. The parent of the root node should always be None.

fn name(&self, tax_id: T) -> Result<&str>

Returns the name of the tax_id provided.

Although not strictly required for many taxonomic operations, this method allows taxonomic exports to conveniently have access to names in a standardized fashion.

fn rank(&self, tax_id: T) -> Result<TaxRank>

Returns the taxonomic rank of the tax_id provided.

Although not strictly required for many of the operations we implement here, this is primarily here to allow taxonomic exports to conveniently have access to ranks in a standardized fashion.

Provided methods

fn lineage(&'t self, tax_id: T) -> Result<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) -> Result<Option<(T, D)>>

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) -> Result<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 traverse(&'t self, node: T) -> Result<TaxonomyIterator<'t, T, D>> where
    Self: Sized, 

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

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

Returns the number of nodes in the taxonomy

A default implementation is specified, but you almost always want to provide your own for speed reasons.

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

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

Implementors

impl<'s> Taxonomy<'s, &'s str, f32> for GeneralTaxonomy

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

impl<'s> Taxonomy<'s, usize, f32> 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.