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:

• add_attribute()
• add_catch_all()

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 &&)=default
	IndexedAttributeTreeNewickReaderPlugin (IndexedAttributeTreeNewickReaderPlugin const &)=default
virtual	~IndexedAttributeTreeNewickReaderPlugin ()=default
self_type &	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. More...
self_type &	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. More...
self_type &	add_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_type &	add_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_type &	operator= (IndexedAttributeTreeNewickReaderPlugin &&)=default
self_type &	operator= (IndexedAttributeTreeNewickReaderPlugin const &)=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

IndexedAttributeTreeNewickReaderPlugin() [1/3]

IndexedAttributeTreeNewickReaderPlugin ( )

default

~IndexedAttributeTreeNewickReaderPlugin()

virtual ~IndexedAttributeTreeNewickReaderPlugin ( )

virtualdefault

IndexedAttributeTreeNewickReaderPlugin() [2/3]

IndexedAttributeTreeNewickReaderPlugin ( IndexedAttributeTreeNewickReaderPlugin const &  )

default

IndexedAttributeTreeNewickReaderPlugin() [3/3]

IndexedAttributeTreeNewickReaderPlugin ( IndexedAttributeTreeNewickReaderPlugin &&  )

default

Member Function Documentation

add_attribute() [1/2]

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(
    IndexedAttributeTreeNewickReader::Source::kComment, 0,
    IndexedAttributeTreeNewickReader::Target::kEdge,    "bootstrap"
);
auto tree = reader.read( 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

source	Input Newick element to take the data from. One of kComment, kValue or kTag.
index	Input index of the element, e.g., 0, to select the first comment.
target	Target Tree element to store the data at. Either kNode or kEdge.
target_key	Target 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.

add_attribute() [2/2]

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

source	Input Newick element to take the data from. One of kComment, kValue or kTag.
index	Input index of the element, e.g., 0, to select the first comment.
target	Target Tree element to store the data at. Either kNode or kEdge.
target_key	Target key to use for storing the data in the AttributeTreeMap of the Node or Edge, e.g., "bootstrap".
default_value	Default value for Newick elements where there is no corresponding index.

Definition at line 53 of file indexed_newick_reader.cpp.

add_catch_all() [1/2]

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(
    IndexedAttributeTreeNewickReader::Source::kComment,
    IndexedAttributeTreeNewickReader::Target::kNode,    "comment_"
);
auto tree = reader.read( 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

source	Input Newick element to take the data from. One of kComment, kValue or kTag.
target	Target Tree element to store the data at. Either kNode or kEdge.
target_key_prefix	Prefix 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.

add_catch_all() [2/2]

IndexedAttributeTreeNewickReaderPlugin & add_catch_all

(

Target

target = Target::kNode

)

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

target

Optional 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.

clear()

void clear

(

)

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

Definition at line 82 of file indexed_newick_reader.cpp.

element_to_edge()

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

Definition at line 101 of file indexed_newick_reader.cpp.

element_to_node()

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

Definition at line 92 of file indexed_newick_reader.cpp.

operator=() [1/2]

self_type& operator= ( IndexedAttributeTreeNewickReaderPlugin &&  )

default

operator=() [2/2]

self_type& operator= ( IndexedAttributeTreeNewickReaderPlugin const &  )

default

register_with()

void register_with

(

NewickReader &

reader

)

const

Definition at line 110 of file indexed_newick_reader.cpp.

Member Typedef Documentation

self_type

using self_type = IndexedAttributeTreeNewickReaderPlugin

Definition at line 103 of file indexed_newick_reader.hpp.

Member Enumeration Documentation

Source

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.

Target

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:

• indexed_newick_reader.hpp
• indexed_newick_reader.cpp