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

#include <genesis/tree/tree.hpp>

Detailed Description

Class for representing phylogenetic trees.

A tree in this implementation consists of three types of elements: Links, Nodes and Edges. The topoloty of the tree is completely described by the links, while nodes and edges add the capability to store data on the tree.

Data in the Tree is not directly stored in the elements (Links, Nodes, Edges) of the Tree. Instead, data belonging to nodes and edges can be stored in their data pointers. For this, the data classes need to derive from BaseNodeData and BaseEdgeData, respectively.

Additional information concerning the whole tree, as well as special algorithms working on the tree and its data are also not direct members of the tree - for reasons of flexibility and extensibility: Instead of adding more and more data and algorithms to the tree, we create new classes that encapsulate a tree and all the other needed code to work with it. See the Sample class for an example.

Thus, the tree itself only contains the needed information to store and work with a topology.

This class has several redundant ways of representing the same information. On the one hand, this makes using a Tree easy, as one can chose the representaion of data that best fits a given task. On the other hand, maintaining all those invariants when changing the tree topology is tedious. Here is a (comprehensive?) list of invariants of this class:

  • The indices in all three arrays (nodes(), links() and edges()) have to match the index integers stored in those elements: node_at(i).index() == i.
  • The link that is stored in a node has to be the one pointing towards the root.
  • The primary link of an edge has to point towards the root, the secondary away from it.

Those invariants are established when the Tree is constructed.

Definition at line 95 of file tree/tree.hpp.

Public Member Functions

 Tree ()=default
 
 Tree (Tree const &other)
 Copy constructor. More...
 
 Tree (Tree &&)=default
 
 ~Tree ()=default
 
IteratorEdges begin_edges ()
 
ConstIteratorEdges begin_edges () const
 
IteratorLinks begin_links ()
 
ConstIteratorLinks begin_links () const
 
IteratorNodes begin_nodes ()
 
ConstIteratorNodes begin_nodes () const
 
void clear ()
 Deletes all data of the tree, including all links, nodes and edges. More...
 
Tree clone_topology () const
 Return a Tree with the same topology, but without any data. More...
 
TreeEdgeedge_at (size_t index)
 Return the TreeEdge at a certain index. More...
 
TreeEdge const & edge_at (size_t index) const
 Return the TreeEdge at a certain index. More...
 
size_t edge_count () const
 Return the number of TreeEdges of the Tree. More...
 
utils::Range< IteratorEdgesedges ()
 
utils::Range< ConstIteratorEdgesedges () const
 
bool empty () const
 Return whether the Tree is empty (i.e., has no nodes, edges and links). More...
 
IteratorEdges end_edges ()
 
ConstIteratorEdges end_edges () const
 
IteratorLinks end_links ()
 
ConstIteratorLinks end_links () const
 
IteratorNodes end_nodes ()
 
ConstIteratorNodes end_nodes () const
 
EdgeContainerTypeexpose_edge_container ()
 Get the container that stores all TreeEdges of the Tree. More...
 
LinkContainerTypeexpose_link_container ()
 Get the container that stores all TreeLinks of the Tree. More...
 
NodeContainerTypeexpose_node_container ()
 Get the container that stores all TreeNodes of the Tree. More...
 
TreeLinklink_at (size_t index)
 Return the TreeLink at a certain index. More...
 
TreeLink const & link_at (size_t index) const
 Return the TreeLink at a certain index. More...
 
size_t link_count () const
 Return the number of TreeLinks of the Tree. More...
 
utils::Range< IteratorLinkslinks ()
 
utils::Range< ConstIteratorLinkslinks () const
 
TreeNodenode_at (size_t index)
 Return the TreeNode at a certain index. More...
 
TreeNode const & node_at (size_t index) const
 Return the TreeNode at a certain index. More...
 
size_t node_count () const
 Return the number of TreeNodes of the Tree. More...
 
utils::Range< IteratorNodesnodes ()
 
utils::Range< ConstIteratorNodesnodes () const
 
Treeoperator= (Tree const &other)
 Assignment operator. More...
 
Treeoperator= (Tree &&)=default
 
Treereset_root_link_index (size_t val)
 Reset the index of the link that is considered to be the root of the Tree. More...
 
TreeLinkroot_link ()
 Return the TreeLink at the current root of the Tree. More...
 
TreeLink const & root_link () const
 Return the TreeLink at the current root of the Tree. More...
 
TreeNoderoot_node ()
 Return the TreeNode at the current root of the Tree. More...
 
TreeNode const & root_node () const
 Return the TreeNode at the current root of the Tree. More...
 
void swap (Tree &other)
 Swap. More...
 

Public Types

using ConstIteratorEdges = typename ContainerType< TreeEdge >::const_iterator
 
using ConstIteratorLinks = typename ContainerType< TreeLink >::const_iterator
 
using ConstIteratorNodes = typename ContainerType< TreeNode >::const_iterator
 
template<class T >
using ContainerType = std::vector< std::unique_ptr< T >>
 Alias for the container type that is used to store TreeLinks, TreeNodes and TreeEdges. More...
 
using EdgeContainerType = ContainerType< TreeEdge >
 Alias for the container type that is used to store TreeEdges. More...
 
using IteratorEdges = typename ContainerType< TreeEdge >::iterator
 
using IteratorLinks = typename ContainerType< TreeLink >::iterator
 
using IteratorNodes = typename ContainerType< TreeNode >::iterator
 
using LinkContainerType = ContainerType< TreeLink >
 Alias for the container type that is used to store TreeLinks. More...
 
using NodeContainerType = ContainerType< TreeNode >
 Alias for the container type that is used to store TreeNodes. More...
 

Friends

bool validate_topology (Tree const &tree)
 Validate the correctness of all Tree pointers etc. More...
 

Constructor & Destructor Documentation

Tree ( )
default
~Tree ( )
default
Tree ( Tree const &  other)

Copy constructor.

This function creates all links, nodes and edges new, and shapes them so that the final Tree has the same topology as the input Tree.

The data belonging to the edges and nodes is copied using the clone function of the respective data classes for the nodes and edges. As this data might contain pointers and other structures that need a deep copy, it is the responsibility of the clone function of those data classes to make sure its own data is copied correctly.

This function internally uses clone_topology() first, and then uses the clone functions of the data for all nodes and edges.

Definition at line 63 of file tree/tree.cpp.

Tree ( Tree &&  )
default

Member Function Documentation

Tree::IteratorEdges begin_edges ( )

Definition at line 498 of file tree/tree.cpp.

Tree::ConstIteratorEdges begin_edges ( ) const

Definition at line 508 of file tree/tree.cpp.

Tree::IteratorLinks begin_links ( )

Definition at line 430 of file tree/tree.cpp.

Tree::ConstIteratorLinks begin_links ( ) const

Definition at line 440 of file tree/tree.cpp.

Tree::IteratorNodes begin_nodes ( )

Definition at line 464 of file tree/tree.cpp.

Tree::ConstIteratorNodes begin_nodes ( ) const

Definition at line 474 of file tree/tree.cpp.

void clear ( )

Deletes all data of the tree, including all links, nodes and edges.

This functions results in an empty tree.

Definition at line 207 of file tree/tree.cpp.

Tree clone_topology ( ) const

Return a Tree with the same topology, but without any data.

All data pointers of the nodes and edges of the returned tree are nullptr.

Definition at line 137 of file tree/tree.cpp.

TreeEdge & edge_at ( size_t  index)

Return the TreeEdge at a certain index.

If the index is invalid, the functions throws an std::out_of_range exception.

Definition at line 324 of file tree/tree.cpp.

TreeEdge const & edge_at ( size_t  index) const

Return the TreeEdge at a certain index.

If the index is invalid, the functions throws an std::out_of_range exception.

Definition at line 334 of file tree/tree.cpp.

size_t edge_count ( ) const

Return the number of TreeEdges of the Tree.

Definition at line 358 of file tree/tree.cpp.

Definition at line 518 of file tree/tree.cpp.

Definition at line 523 of file tree/tree.cpp.

bool empty ( ) const

Return whether the Tree is empty (i.e., has no nodes, edges and links).

Definition at line 222 of file tree/tree.cpp.

Tree::IteratorEdges end_edges ( )

Definition at line 503 of file tree/tree.cpp.

Tree::ConstIteratorEdges end_edges ( ) const

Definition at line 513 of file tree/tree.cpp.

Tree::IteratorLinks end_links ( )

Definition at line 435 of file tree/tree.cpp.

Tree::ConstIteratorLinks end_links ( ) const

Definition at line 445 of file tree/tree.cpp.

Tree::IteratorNodes end_nodes ( )

Definition at line 469 of file tree/tree.cpp.

Tree::ConstIteratorNodes end_nodes ( ) const

Definition at line 479 of file tree/tree.cpp.

Tree::EdgeContainerType & expose_edge_container ( )

Get the container that stores all TreeEdges of the Tree.

This function gives direct access to the underlying container for the Links. It is meant to be used by external functions that need to manupulate the Tree, e.g., for reading or re-rooting the tree, or for adding elements to it. Use with care!

Definition at line 417 of file tree/tree.cpp.

Tree::LinkContainerType & expose_link_container ( )

Get the container that stores all TreeLinks of the Tree.

This function gives direct access to the underlying container for the Links. It is meant to be used by external functions that need to manupulate the Tree, e.g., for reading or re-rooting the tree, or for adding elements to it. Use with care!

Definition at line 393 of file tree/tree.cpp.

Tree::NodeContainerType & expose_node_container ( )

Get the container that stores all TreeNodes of the Tree.

This function gives direct access to the underlying container for the Links. It is meant to be used by external functions that need to manupulate the Tree, e.g., for reading or re-rooting the tree, or for adding elements to it. Use with care!

Definition at line 405 of file tree/tree.cpp.

TreeLink & link_at ( size_t  index)

Return the TreeLink at a certain index.

If the index is invalid, the functions throws an std::out_of_range exception.

Definition at line 284 of file tree/tree.cpp.

TreeLink const & link_at ( size_t  index) const

Return the TreeLink at a certain index.

If the index is invalid, the functions throws an std::out_of_range exception.

Definition at line 294 of file tree/tree.cpp.

size_t link_count ( ) const

Return the number of TreeLinks of the Tree.

Definition at line 342 of file tree/tree.cpp.

Definition at line 450 of file tree/tree.cpp.

Definition at line 455 of file tree/tree.cpp.

TreeNode & node_at ( size_t  index)

Return the TreeNode at a certain index.

If the index is invalid, the functions throws an std::out_of_range exception.

Definition at line 304 of file tree/tree.cpp.

TreeNode const & node_at ( size_t  index) const

Return the TreeNode at a certain index.

If the index is invalid, the functions throws an std::out_of_range exception.

Definition at line 314 of file tree/tree.cpp.

size_t node_count ( ) const

Return the number of TreeNodes of the Tree.

Definition at line 350 of file tree/tree.cpp.

Definition at line 484 of file tree/tree.cpp.

Definition at line 489 of file tree/tree.cpp.

Tree & operator= ( Tree const &  other)

Assignment operator.

See Tree copy constructor for more information.

Definition at line 119 of file tree/tree.cpp.

Tree& operator= ( Tree &&  )
default
Tree & reset_root_link_index ( size_t  val)

Reset the index of the link that is considered to be the root of the Tree.

This function is meant for tree manipulation functions. Use with care!

Caveat: This function simply sets the index, but does not change any other properties of the tree. Particularly the correct primary/secondary order of TreeEdges and primary links of TreeNodes needs to be maintained manually when using this function! Otherwise, we end up with an invalid Tree that breaks its invariants!

Definition at line 377 of file tree/tree.cpp.

TreeLink & root_link ( )

Return the TreeLink at the current root of the Tree.

If the tree is empty(), the functions throws an std::out_of_range exception.

Definition at line 232 of file tree/tree.cpp.

TreeLink const & root_link ( ) const

Return the TreeLink at the current root of the Tree.

If the tree is empty(), the functions throws an std::out_of_range exception.

Definition at line 245 of file tree/tree.cpp.

TreeNode & root_node ( )

Return the TreeNode at the current root of the Tree.

If the tree is empty(), the functions throws an std::out_of_range exception.

Definition at line 258 of file tree/tree.cpp.

TreeNode const & root_node ( ) const

Return the TreeNode at the current root of the Tree.

If the tree is empty(), the functions throws an std::out_of_range exception.

Definition at line 271 of file tree/tree.cpp.

void swap ( Tree other)

Swap.

Definition at line 191 of file tree/tree.cpp.

Friends And Related Function Documentation

bool validate_topology ( Tree const &  tree)
friend

Validate the correctness of all Tree pointers etc.

This function is defined in tree/functions/operators.hpp

This check is a bit pedantic, but better safe than sorry.

Definition at line 296 of file tree/function/operators.cpp.

Member Typedef Documentation

using ConstIteratorEdges = typename ContainerType< TreeEdge >::const_iterator

Definition at line 132 of file tree/tree.hpp.

using ConstIteratorLinks = typename ContainerType< TreeLink >::const_iterator

Definition at line 126 of file tree/tree.hpp.

using ConstIteratorNodes = typename ContainerType< TreeNode >::const_iterator

Definition at line 129 of file tree/tree.hpp.

using ContainerType = std::vector< std::unique_ptr< T >>

Alias for the container type that is used to store TreeLinks, TreeNodes and TreeEdges.

Definition at line 108 of file tree/tree.hpp.

Alias for the container type that is used to store TreeEdges.

Definition at line 123 of file tree/tree.hpp.

using IteratorEdges = typename ContainerType< TreeEdge >::iterator

Definition at line 131 of file tree/tree.hpp.

using IteratorLinks = typename ContainerType< TreeLink >::iterator

Definition at line 125 of file tree/tree.hpp.

using IteratorNodes = typename ContainerType< TreeNode >::iterator

Definition at line 128 of file tree/tree.hpp.

Alias for the container type that is used to store TreeLinks.

Definition at line 113 of file tree/tree.hpp.

Alias for the container type that is used to store TreeNodes.

Definition at line 118 of file tree/tree.hpp.


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