A toolkit for working with phylogenetic data.
v0.19.0
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
Taxonomy Class Reference

#include <genesis/taxonomy/taxonomy.hpp>

Inherited by Taxon.

Detailed Description

Store a Taxonomy, i.e., a nested hierarchy of Taxa.

We call a string of the form

Animalia;Vertebrata;Mammalia;Carnivora

a taxonomic path string. Those strings are often found in taxonomic databases, and usually use semicola to separete their parts. Each part of such a string is called a Taxon, and can have a rank associated with it. See Taxopath for details on the format.

In the example above, the rank associations could be

Kingdom: Animalia
Phylum:  Vertebrata
Class:   Mammalia
Order:   Carnivora

We use the term "taxon" to refer to one element in such a string, and model this in the Taxon class. Both the Taxonomy and Taxon classes work with just those parts of the string. Each Taxon can itself contain further lower level Taxa, resulting in a hierarchy.

The above taxonomic path string for example would give a hierarchy of Taxa like this

Animalia
    Vertebrata
        Mammalia
            Carnivora

where each line is one Taxon, stored within their parent Taxa. A Taxonomy is the uppermost parent of the Taxa in the hierarchy.

There are functions to work with taxonomic path strings and Taxopaths directly, for example to "translate" them into a Taxonomy or to find a Taxon given a Taxopath. See the namespace taxonomy for a list of those functions.

In a sense, each Taxon is itself a Taxonomy, because of their hierarchical relationship. However, we use the distinction between the two in order to separate concerns. That means, only the Taxonomy should be seen as the top level of the hierarchy.

This class serves as a container for storing a list of Taxa. It allows to add, remove and get Taxa by their name, as well as iterating over them.

Definition at line 96 of file taxonomy/taxonomy.hpp.

Public Member Functions

 Taxonomy ()=default
 
 Taxonomy (Taxonomy const &)
 Copy constructor. More...
 
 Taxonomy (Taxonomy &&)
 Move constructor. More...
 
virtual ~Taxonomy ()=default
 
Taxonadd_child (Taxon const &child)
 Add a child Taxon as a copy of a given Taxon and return it. More...
 
Taxonadd_child (std::string const &name)
 Add a child Taxon by creating a new one with the given name and return it. More...
 
Taxon const & at (size_t index) const
 Return the child Taxon at the given index. More...
 
Taxonat (size_t index)
 Return the child Taxon at the given index. More...
 
iterator begin ()
 Return an iterator to the beginning of the child taxa. More...
 
const_iterator begin () const
 Return a const iterator to the beginning of the child taxa. More...
 
const_iterator cbegin () const
 Return a const iterator to the beginning of the child taxa. More...
 
const_iterator cend () const
 Return a const iterator to the end of the child taxa. More...
 
void clear_children ()
 Remove all children. More...
 
iterator end ()
 Return an iterator to the end of the child taxa. More...
 
const_iterator end () const
 Return a const iterator to the end of the child taxa. More...
 
Taxon const & get_child (std::string name) const
 Return the child Taxon with a given name if it exists, or throw otherwise. More...
 
Taxonget_child (std::string name)
 Return the child Taxon with a given name if it exists, or throw otherwise. More...
 
bool has_child (std::string name) const
 Return whether an immediate child Taxon with the given name exists. More...
 
size_t index_of (std::string const &name) const
 
Taxonomyoperator= (Taxonomy const &)
 Copy assigment operator. More...
 
Taxonomyoperator= (Taxonomy &&)
 Move assignment operator. More...
 
Taxon const & operator[] (std::string name) const
 Return the child Taxon with a given name if it exists, or throw otherwise. More...
 
Taxonoperator[] (std::string name)
 Return the child Taxon with a given name if it exists, or throw otherwise. More...
 
Taxon const & operator[] (size_t index) const
 Return the child Taxon at the given index. More...
 
Taxonoperator[] (size_t index)
 Return the child Taxon at the given index. More...
 
void remove_child (std::string const &name)
 Remove a child Taxon with a certain name. More...
 
size_t size () const
 Return the number of immediate child Taxa. More...
 

Public Types

typedef std::vector< Taxon >
::const_iterator 
const_iterator
 
typedef std::vector< Taxon >
::iterator 
iterator
 

Protected Member Functions

virtual Taxonadd_child_ (Taxon const &child)
 Virtual implementation function for adding a child Taxon. More...
 
void reset_parent_pointers_ (Taxon *parent)
 Internal helper function that resets the parent pointer of all stored Taxa. More...
 

Friends

void swap (Taxonomy &lhs, Taxonomy &rhs)
 Swapperator for Taxonomy. More...
 

Constructor & Destructor Documentation

Taxonomy ( )
default
virtual ~Taxonomy ( )
virtualdefault
Taxonomy ( Taxonomy const &  other)

Copy constructor.

We need a custom version of this in order to set the Taxon::parent() pointers of all children correctly when copying.

Definition at line 51 of file taxonomy.cpp.

Taxonomy ( Taxonomy &&  other)

Move constructor.

We need a custom version of this in order to set the Taxon::parent() pointers of all children correctly when copying.

Definition at line 63 of file taxonomy.cpp.

Member Function Documentation

Taxon & add_child ( Taxon const &  child)

Add a child Taxon as a copy of a given Taxon and return it.

If a child Taxon with the same name already exists, it is recursively merged with the given Taxon.

Definition at line 233 of file taxonomy.cpp.

Taxon & add_child ( std::string const &  name)

Add a child Taxon by creating a new one with the given name and return it.

If a child Taxon with the same name already exists, nothing happens.

Definition at line 243 of file taxonomy.cpp.

Taxon & add_child_ ( Taxon const &  child)
protectedvirtual

Virtual implementation function for adding a child Taxon.

This function is invoked by all add_child() functions in order to implement the non-virtual interface pattern.

It needs to be virtual because adding a child Taxon differs for Taxonomy and Taxon. In the latter case, the additional parent property has to be set. Thus, this function is overridden by Taxon, see Taxon::add_child_().

If a child Taxon with the same name already exists, it is recursively merged with the given Taxon. The function returns the child.

Reimplemented in Taxon.

Definition at line 352 of file taxonomy.cpp.

Taxon const & at ( size_t  index) const

Return the child Taxon at the given index.

The function throws an exception if the index in invalid, i.e., >= size().

Definition at line 179 of file taxonomy.cpp.

Taxon & at ( size_t  index)

Return the child Taxon at the given index.

The function throws an exception if the index in invalid, i.e., >= size().

Definition at line 189 of file taxonomy.cpp.

Taxonomy::iterator begin ( )

Return an iterator to the beginning of the child taxa.

Definition at line 290 of file taxonomy.cpp.

Taxonomy::const_iterator begin ( ) const

Return a const iterator to the beginning of the child taxa.

Definition at line 306 of file taxonomy.cpp.

Taxonomy::const_iterator cbegin ( ) const

Return a const iterator to the beginning of the child taxa.

Definition at line 322 of file taxonomy.cpp.

Taxonomy::const_iterator cend ( ) const

Return a const iterator to the end of the child taxa.

Definition at line 330 of file taxonomy.cpp.

void clear_children ( )

Remove all children.

Definition at line 278 of file taxonomy.cpp.

Return an iterator to the end of the child taxa.

Definition at line 298 of file taxonomy.cpp.

Taxonomy::const_iterator end ( ) const

Return a const iterator to the end of the child taxa.

Definition at line 314 of file taxonomy.cpp.

Taxon const & get_child ( std::string  name) const

Return the child Taxon with a given name if it exists, or throw otherwise.

Definition at line 135 of file taxonomy.cpp.

Taxon & get_child ( std::string  name)

Return the child Taxon with a given name if it exists, or throw otherwise.

Definition at line 148 of file taxonomy.cpp.

bool has_child ( std::string  name) const

Return whether an immediate child Taxon with the given name exists.

Definition at line 121 of file taxonomy.cpp.

size_t index_of ( std::string const &  name) const

Definition at line 214 of file taxonomy.cpp.

Taxonomy & operator= ( Taxonomy const &  other)

Copy assigment operator.

We need a custom version of this in order to set the Taxon::parent() pointers of all children correctly when copying.

Definition at line 75 of file taxonomy.cpp.

Taxonomy & operator= ( Taxonomy &&  other)

Move assignment operator.

We need a custom version of this in order to set the Taxon::parent() pointers of all children correctly when copying.

Definition at line 88 of file taxonomy.cpp.

Taxon const & operator[] ( std::string  name) const

Return the child Taxon with a given name if it exists, or throw otherwise.

Definition at line 161 of file taxonomy.cpp.

Taxon & operator[] ( std::string  name)

Return the child Taxon with a given name if it exists, or throw otherwise.

Definition at line 169 of file taxonomy.cpp.

Taxon const & operator[] ( size_t  index) const

Return the child Taxon at the given index.

The function does not check whether the provided index is within the valid range of size().

Definition at line 199 of file taxonomy.cpp.

Taxon & operator[] ( size_t  index)

Return the child Taxon at the given index.

The function does not check whether the provided index is within the valid range of size().

Definition at line 209 of file taxonomy.cpp.

void remove_child ( std::string const &  name)

Remove a child Taxon with a certain name.

The Taxon (and all its sub-taxa) are destroyed. Throws an std::runtime_error if there is no Taxon with the given name.

Definition at line 254 of file taxonomy.cpp.

void reset_parent_pointers_ ( Taxon parent)
protected

Internal helper function that resets the parent pointer of all stored Taxa.

This function is used whenever the children_ container is changed (copy, move, add elements) in order to make sure that all parent pointers are correct.

As all constructors and assignment operators use this function, we also make sure that adding or removing elements or changing their order (sort etc) does not break the correctness of the parent pointers. This might be slightly inefficient if many such moves (and thus, reset operations) are done in sequence. However, this is acceptable in order to keep the object stable at any time.

Definition at line 388 of file taxonomy.cpp.

size_t size ( ) const

Return the number of immediate child Taxa.

See total_taxa_count() for counting all Taxa, including all nested ones.

Definition at line 113 of file taxonomy.cpp.

Friends And Related Function Documentation

void swap ( Taxonomy lhs,
Taxonomy rhs 
)
friend

Swapperator for Taxonomy.

Definition at line 98 of file taxonomy.cpp.

Member Typedef Documentation

typedef std::vector<Taxon>::const_iterator const_iterator

Definition at line 105 of file taxonomy/taxonomy.hpp.

typedef std::vector<Taxon>::iterator iterator

Definition at line 104 of file taxonomy/taxonomy.hpp.


The documentation for this class was generated from the following files: