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

#include <genesis/tree/attribute_tree/indexed_newick_reader.hpp>

Inherited by IndexedAttributeTreeNewickReader.

Detailed Description

Provide a set of plugin functions for NewickReader to read ordered attributes of the Nodes and Edges into an AttributeTree.

This class is a plugin that adds functionality to a NewickReader. The easiest way to use it is to instanciate a IndexedAttributeTreeNewickReader, which combines a NewickReader with this plugin.

The class is useful for Newick trees that contain a fixed, ordered set of additional data stored for the nodes and edges of the tree, e.g.,

((C,D)[0.1],(A,(B,X)[0.3])[0.2],E);

This represents a Newick tree that contains bootstrap support values at the inner branches, where these data occur always as the first Newick comment for a given node.

The plugin allows to process the following types of Newick data:

  • Comments, of the form [0.1], e.g., bootstrap values.
  • Values, of the form :3.14, e.g., branch lengths.
  • Tags, of the form {42}, e.g., edge numbers using in the jplace format.

See NewickBrokerElement for more details on those Newick data types.

The class offers two ways to process and store these data:

See there for details.

Both ways use Source to select which Newick data to take (comments, values or tags), and use Target to select where to store it in the Tree (Nodes or Edges).

Be aware that the latter is an important distinction, as the semantics of the data are not given by Newick. For example, storing bootstrap support values at Nodes insteda of Edges can lead to unexpected and wrong results. You are supposed to know what kind of data the Newick file you are processing contains. See also https://academic.oup.com/mbe/article-lookup/doi/10.1093/molbev/msx055

This class is limited to the simple case where the Newick data is always stored in a certain order, i.e., the bootstrap values are always the first comment for a Newick node. Another common Newick data type are key-value-pairs, for example the New Hampshire eXtended (NHX) format. For such Newick trees, see KeyedAttributeTreeNewickReaderPlugin. If you have even more complex Newick data, you need to add your own NewickReader plugin functions.

Definition at line 95 of file indexed_newick_reader.hpp.

Public Member Functions

 IndexedAttributeTreeNewickReaderPlugin ()=default
 
 IndexedAttributeTreeNewickReaderPlugin (IndexedAttributeTreeNewickReaderPlugin const &)=default
 
 IndexedAttributeTreeNewickReaderPlugin (IndexedAttributeTreeNewickReaderPlugin &&)=default
 
virtual ~IndexedAttributeTreeNewickReaderPlugin ()=default
 
self_typeadd_attribute (Source source, size_t index, Target target, std::string const &target_key)
 Store the Newick data at a given index in an AttributeTreeMap. More...
 
self_typeadd_attribute (Source source, size_t index, Target target, std::string const &target_key, std::string const &default_value)
 Store the Newick data at a given index in an AttributeTreeMap, using a default value if there is no data at that index. More...
 
self_typeadd_catch_all (Source source, Target target, std::string const &target_key_prefix)
 Store all Newick data of a given source in an AttributeTreeMap. More...
 
self_typeadd_catch_all (Target target=Target::kNode)
 Store all Newick data in an AttributeTreeMap. More...
 
void clear ()
 Reset all settings to the default, i.e., delete all attribute settings. More...
 
void element_to_edge (NewickBrokerElement const &element, TreeEdge &edge) const
 
void element_to_node (NewickBrokerElement const &element, TreeNode &node) const
 
self_typeoperator= (IndexedAttributeTreeNewickReaderPlugin const &)=default
 
self_typeoperator= (IndexedAttributeTreeNewickReaderPlugin &&)=default
 
void register_with (NewickReader &reader) const
 

Public Types

using self_type = IndexedAttributeTreeNewickReaderPlugin
 
enum  Source { kValue, kComment, kTag }
 Select which kind of Newick data to take, i.e., either comments, values, or tags. More...
 
enum  Target { kNode, kEdge }
 Select where to store the data, i.e., at Nodes or Edges of the Tree. More...
 

Constructor & Destructor Documentation

virtual ~IndexedAttributeTreeNewickReaderPlugin ( )
virtualdefault

Member Function Documentation

IndexedAttributeTreeNewickReaderPlugin & add_attribute ( Source  source,
size_t  index,
Target  target,
std::string const &  target_key 
)

Store the Newick data at a given index in an AttributeTreeMap.

Consider the exemplary Newick tree

((C,D)[0.1],(A,(B,X)[0.3])[0.2],E);

In this tree, Newick comments are used to store bootstrap support values. The values are always the first Newick comment of a node (if they occur), i.e. the comment with index 0.

To store these values in the attributes map of the corresponding AttributeTreeEdgeData, we can use:

IndexedAttributeTreeNewickReader reader;
reader.add_attribute(
);
auto tree = reader.from_file( "path/to/tree.newick" );

This stores the Newick comment (such as "[0.1]" in the example) with index 0 (the first one) at the corresponding Edge, using the key "bootstrap".

The same can be done for Newick values and tags (see NewickBrokerElement for their description), and we can store them on the Node instead of the Edge.

In cases where there is no corresponding index in the Newick element data, no data is added. For example, the Newick tree above does not contain any bootstrap support values for the leaf nodes. That means, the comments of the NewickBrokerElement is empty, so there is no index 0 in them. If you want to use a default value in such cases, use add_attribute( Source, size_t, Target, std::string const&, std::string const& ) instead.

Parameters
sourceInput Newick element to take the data from. One of kComment, kValue or kTag.
indexInput index of the element, e.g., 0, to select the first comment.
targetTarget Tree element to store the data at. Either kNode or kEdge.
target_keyTarget key to use for storing the data in the AttributeTreeMap of the Node or Edge, e.g., "bootstrap".

Definition at line 43 of file indexed_newick_reader.cpp.

IndexedAttributeTreeNewickReaderPlugin & add_attribute ( Source  source,
size_t  index,
Target  target,
std::string const &  target_key,
std::string const &  default_value 
)

Store the Newick data at a given index in an AttributeTreeMap, using a default value if there is no data at that index.

The function behaves the same as add_attribute( Source, size_t, Target, std::string const& ) in cases where the given index is found at a Newick element.

However, in cases where there is no corresponding index in the Newick element data, this function uses a default value in the attribute map, insted of ingoring it.

For example, the Newick tree

((C,D)[0.1],(A,(B,X)[0.3])[0.2],E);

does not contain any bootstrap support values for the leaf nodes. That means, the comments of the NewickBrokerElement is empty, so there is no index 0 in them. In this case, the specified default value is used.

Parameters
sourceInput Newick element to take the data from. One of kComment, kValue or kTag.
indexInput index of the element, e.g., 0, to select the first comment.
targetTarget Tree element to store the data at. Either kNode or kEdge.
target_keyTarget key to use for storing the data in the AttributeTreeMap of the Node or Edge, e.g., "bootstrap".
default_valueDefault value for Newick elements where there is no corresponding index.

Definition at line 53 of file indexed_newick_reader.cpp.

IndexedAttributeTreeNewickReaderPlugin & add_catch_all ( Source  source,
Target  target,
std::string const &  target_key_prefix 
)

Store all Newick data of a given source in an AttributeTreeMap.

This function allows to capture all Newick data of a given type (comment, value or tag) and store it at a Tree element (Node or Edge), using a given prefix and a sequential number.

For example, given the Newick tree

((C,D)[inner_A],(A,(B,X)[inner_B])[inner_C],E);

we can store all comments at the tree Nodes using

IndexedAttributeTreeNewickReader reader;
reader.add_catch_all(
);
auto tree = reader.from_file( "path/to/tree.newick" );

The resulting tree has attributes at the inner nodes, with the key comment_0 and the values inner_A, inner_B and inner_C, respectively.

Remark: This will store all data at either the Nodes or Edges of the Tree. This can lead to problems if some of the data actually belongs to the other element (Edges or Nodes). In these cases, better set the capturing explicitly, using add_attribute().

Parameters
sourceInput Newick element to take the data from. One of kComment, kValue or kTag.
targetTarget Tree element to store the data at. Either kNode or kEdge.
target_key_prefixPrefix for the target key, to which a sequential number according to the index of the data is appended.

Definition at line 64 of file indexed_newick_reader.cpp.

Store all Newick data in an AttributeTreeMap.

This is a simplification of add_catch_all(), which adds three catch-alls for the Newick comments, values and tags at once. It uses comment_, value_ and tag_ as key prefix, respectively. The function is meant for the most general use case, where we want to capture all Newick data and store it in an AttributeTree.

Parameters
targetOptional parameter that can be used to specify where to store the data; default is to store it at the Tree Nodes.

Definition at line 73 of file indexed_newick_reader.cpp.

void clear ( )

Reset all settings to the default, i.e., delete all attribute settings.

Definition at line 82 of file indexed_newick_reader.cpp.

void element_to_edge ( NewickBrokerElement const &  element,
TreeEdge edge 
) const

Definition at line 101 of file indexed_newick_reader.cpp.

void element_to_node ( NewickBrokerElement const &  element,
TreeNode node 
) const

Definition at line 92 of file indexed_newick_reader.cpp.

self_type& operator= ( IndexedAttributeTreeNewickReaderPlugin const &  )
default
void register_with ( NewickReader reader) const

Definition at line 110 of file indexed_newick_reader.cpp.

Member Typedef Documentation

Member Enumeration Documentation

enum Source
strong

Select which kind of Newick data to take, i.e., either comments, values, or tags.

See NewickBrokerElement for more details.

Enumerator
kValue 

Take data from Newick values, i.e., :3.14.

kComment 

Take data from Newick comments, i.e., [something].

kTag 

Take data from Newick tags, i.e., {42}.

Definition at line 110 of file indexed_newick_reader.hpp.

enum Target
strong

Select where to store the data, i.e., at Nodes or Edges of the Tree.

Enumerator
kNode 

Store data at the attributes map of an AttributeTreeNode.

kEdge 

Store data at the attributes map of an AttributeTreeEdge.

Definition at line 131 of file indexed_newick_reader.hpp.


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