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

Inherited by KeyedAttributeTreeNewickReader.

Detailed Description

Provide a set of plugin functions for NewickReader to read key-value-pair data attributes into an AttributeTree.

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

The class can be used to read Newick trees that contain additional data in Newick comments, if this data is structured into key-value-pairs, e.g.,

((C,D)[&!color=#009966],(A,(B,X)[&bs=82,!color=#137693])[&bs=70],E);

This Newick tree contains a few values that represent branch colors (color) and bootstrap support values (bs).

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

Furthermore, it offers simple support for the New Hampshire eXtended (NHX) format, see set_nhx_delimiters() and add_nhx_attributes().

By default, the classes uses & as the comment prefix, , as the separator between key-value-pairs, and = as the symbol between the key and the value. This is what the example above uses. In order to change those, use set_delimiters().

Remark: This kind of key-value data is only useful in comments. Thus, different from the IndexedAttributeTreeNewickReaderPlugin, this plugin does not support Newick values or tags.

Definition at line 81 of file keyed_newick_reader.hpp.

Public Member Functions
	KeyedAttributeTreeNewickReaderPlugin ()=default

	KeyedAttributeTreeNewickReaderPlugin (KeyedAttributeTreeNewickReaderPlugin &&)=default

	KeyedAttributeTreeNewickReaderPlugin (KeyedAttributeTreeNewickReaderPlugin const &)=default

virtual	~KeyedAttributeTreeNewickReaderPlugin ()=default

self_type &	add_attribute (std::string const &key, Target target)
	Store values of a `key` at a `target` (i.e., Node or Edge). More...

self_type &	add_attribute (std::string const &source_key, Target target, std::string const &target_key)
	Store values of a `source_key` at a `target` (i.e., Node or Edge), using the `target_key`. More...

self_type &	add_attribute (std::string const &source_key, Target target, std::string const &target_key, std::string const &default_value)
	Store values of a `source_key` at a `target` (i.e., Node or Edge), using the `target_key`, and a `default_value`, if the key is not found in the source. More...

self_type &	add_catch_all (Target target=Target::kNode)
	Store all key-value-pairs of the Newick data in an AttributeTree. More...

self_type &	add_nhx_attributes ()
	Add typical attributes of the NHX format, and set the appropriate delimiters. More...

std::string	assigner () const
	Get the currently set assign symbol between a key and its value. More...

self_type &	assigner (std::string const &value)
	Set the assign symbol between a key and its value. More...

void	clear ()
	Reset all settings to the default and 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= (KeyedAttributeTreeNewickReaderPlugin &&)=default

self_type &	operator= (KeyedAttributeTreeNewickReaderPlugin const &)=default

std::string	prefix () const
	Get the currently set prefix to look for in Newick comments. More...

self_type &	prefix (std::string const &value)
	Set the prefix to look for in Newick comments. More...

void	register_with (NewickReader &reader) const

std::string	separator () const
	Get the currently set separator between key-value-pairs. More...

self_type &	separator (std::string const &value)
	Set the separator between key-value-pairs. More...

self_type &	set_delimiters (std::string const &prefix, std::string const &separator, std::string const &assigner="=")
	Set the delimiters for key-value-pairs. More...

self_type &	set_nhx_delimiters ()
	Set the delimiters to the format used by NHX. More...

bool	trim () const
	Get whether to trim keys and values before storing them in the Tree. More...

self_type &	trim (bool value)
	Set whether to trim keys and values before storing them in the Tree. More...

Public Types
using	self_type = KeyedAttributeTreeNewickReaderPlugin

enum	Target { kNode, kEdge }
	Select where to store the data, i.e., at Nodes or Edges of the Tree. More...

Constructor & Destructor Documentation

◆ KeyedAttributeTreeNewickReaderPlugin() [1/3]

KeyedAttributeTreeNewickReaderPlugin ( )

default

◆ ~KeyedAttributeTreeNewickReaderPlugin()

virtual ~KeyedAttributeTreeNewickReaderPlugin ( )

virtualdefault

◆ KeyedAttributeTreeNewickReaderPlugin() [2/3]

KeyedAttributeTreeNewickReaderPlugin ( KeyedAttributeTreeNewickReaderPlugin const & )

default

◆ KeyedAttributeTreeNewickReaderPlugin() [3/3]

KeyedAttributeTreeNewickReaderPlugin ( KeyedAttributeTreeNewickReaderPlugin && )

default

Member Function Documentation

◆ add_attribute() [1/3]

KeyedAttributeTreeNewickReaderPlugin & add_attribute	(	std::string const &	key,
		Target	target
	)

Store values of a key at a target (i.e., Node or Edge).

For example, using the Newick tree

((C,D)[&!color=#009966],(A,(B,X)[&bs=82,!color=#137693])[&bs=70],E);

we can read the bootstrap support values (bs) and store them at the Edges like this:

KeyedAttributeTreeNewickReader reader;
reader.add_attribute( "bs", KeyedAttributeTreeNewickReader::Target::kEdge );
auto tree = reader.read( from_file( "path/to/tree.newick" ));

This is a simple form which uses the same key for the source (Newick comment) and target (Node or Edge), and does not use a default value, i.e., if the key is not found, no value is added to the target.

See add_attribute( source_key, target, target_key ) for more details.

Parameters

key	Key of a key-value-pair. If found in the source Newick comment, the value is added to the target Node or Edge, using the same key.
target	Target Tree element to store the data at. Either `kNode` or `kEdge`.

Definition at line 68 of file keyed_newick_reader.cpp.

◆ add_attribute() [2/3]

KeyedAttributeTreeNewickReaderPlugin & add_attribute	(	std::string const &	source_key,
		Target	target,
		std::string const &	target_key
	)

Store values of a source_key at a target (i.e., Node or Edge), using the target_key.

Using this form, the source and target key can differ. For example, using the Newick tree

((C,D)[&!color=#009966],(A,(B,X)[&bs=82,!color=#137693])[&bs=70],E);

we can read the color values (!color) like this:

KeyedAttributeTreeNewickReader reader;
reader.add_attribute( "!color", KeyedAttributeTreeNewickReader::Target::kEdge, "color" );
auto tree = reader.read( from_file( "path/to/tree.newick" ));

which stores the values under the key color (without the leading exclamation mark).

The function does not use default values. I.e., if the key is not found in the source comment, no value is added to the target.

Also, see add_attribute( source_key, target, target_key, default_value ) for details.

Parameters

source_key	Source key of a key-value-pair. If found in the source Newick comment, the value is added to the target Node or Edge, using the `target_key`.
target	Target Tree element to store the data at. Either `kNode` or `kEdge`.
target_key	Target key, used to store a value, if the `source_key` is found in the Newick comment.

Definition at line 76 of file keyed_newick_reader.cpp.

◆ add_attribute() [3/3]

KeyedAttributeTreeNewickReaderPlugin & add_attribute	(	std::string const &	source_key,
		Target	target,
		std::string const &	target_key,
		std::string const &	default_value
	)

Store values of a source_key at a target (i.e., Node or Edge), using the target_key, and a default_value, if the key is not found in the source.

This is the most flexible form of this function. It is similar to add_attribute( source_key, target, target_key ), but additionally used a default value, if the key is not found in the source Newick comment.

Parameters

source_key	Source key of a key-value-pair. If found in the source Newick comment, the value is added to the target Node or Edge, using the `target_key`.
target	Target Tree element to store the data at. Either `kNode` or `kEdge`.
target_key	Target key, used to store a value at the target Node or Edge.
default_value	Default value to be used if the source Newick comment does not contain the `source_key`.

Definition at line 85 of file keyed_newick_reader.cpp.

◆ add_catch_all()

KeyedAttributeTreeNewickReaderPlugin & add_catch_all ( Target target = Target::kNode )

Store all key-value-pairs of the Newick data in an AttributeTree.

This function allows to capture all Newick comment data in key-value-form and store it at a Tree element (Node or Edge).

For example, given the Newick tree

((C,D)[&!color=#009966],(A,(B,X)[&bs=82,!color=#137693])[&bs=70],E);

we can store all data at the tree Edges using

KeyedAttributeTreeNewickReader reader;
reader.add_catch_all( KeyedAttributeTreeNewickReader::Target::kEdge );
auto tree = reader.read( from_file( "path/to/tree.newick" ));

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 captureing explicitly, using add_attribute().

Definition at line 95 of file keyed_newick_reader.cpp.

◆ add_nhx_attributes()

KeyedAttributeTreeNewickReaderPlugin & add_nhx_attributes ( )

Add typical attributes of the NHX format, and set the appropriate delimiters.

The New Hampshire eXtended (NHX) format is an extension of the Newick format that uses specially formatted Newick comments to store additional data for the nodes and edges of a tree. See for example https://sites.google.com/site/cmzmasek/home/software/forester/nhx and https://home.cc.umanitoba.ca/~psgendb/doc/atv/NHX.pdf for details.

This function adds capturing for the following keys:

Key	Target	Description
AC	Node	sequence accession
B	Edge	confidence value for parent branch
Co	Node	collapse this node when drawing the tree (default is not to collapse)
D	Node	duplication event
E	Node	EC number
GN	Node	gene name
L	Edge	log likelihood value on parent branch
O	Node	orthologous to this external node
S	Node	species name
SO	Node	"super orthologous" (no duplications on paths)
Sw	Edge	placing a subtree on the parent branch of this node makes the tree significantly worse according to Kishino/Hasegawa test (or similar)
T	Node	taxonomy ID

If you need other NHX keys, want to use different keys for the target, or want to use default values for keys that are not present in the Newick data, please use the normal add_attribute() functions or add_catch_all() instead. This is only meant to be a very basic simplification for supporting NHX.

Definition at line 110 of file keyed_newick_reader.cpp.

◆ assigner() [1/2]

std::string assigner ( ) const

inline

Get the currently set assign symbol between a key and its value.

Definition at line 354 of file keyed_newick_reader.hpp.

◆ assigner() [2/2]

self_type& assigner ( std::string const & value )

inline

Set the assign symbol between a key and its value.

Default is =, as used in the examples of this class.

Definition at line 345 of file keyed_newick_reader.hpp.

◆ clear()

void clear ( )

Reset all settings to the default and delete all attribute settings.

Definition at line 119 of file keyed_newick_reader.cpp.

◆ element_to_edge()

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

Definition at line 150 of file keyed_newick_reader.cpp.

◆ element_to_node()

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

Definition at line 134 of file keyed_newick_reader.cpp.

◆ operator=() [1/2]

self_type& operator= ( KeyedAttributeTreeNewickReaderPlugin && )

default

◆ operator=() [2/2]

self_type& operator= ( KeyedAttributeTreeNewickReaderPlugin const & )

default

◆ prefix() [1/2]

std::string prefix ( ) const

inline

Get the currently set prefix to look for in Newick comments.

Definition at line 316 of file keyed_newick_reader.hpp.

◆ prefix() [2/2]

self_type& prefix ( std::string const & value )

inline

Set the prefix to look for in Newick comments.

Default is &, as used in the examples of this class.

Definition at line 307 of file keyed_newick_reader.hpp.

◆ register_with()

void register_with ( NewickReader & reader ) const

Definition at line 166 of file keyed_newick_reader.cpp.

◆ separator() [1/2]

std::string separator ( ) const

inline

Get the currently set separator between key-value-pairs.

Definition at line 335 of file keyed_newick_reader.hpp.

◆ separator() [2/2]

self_type& separator ( std::string const & value )

inline

Set the separator between key-value-pairs.

Default is ,, as used in the examples of this class.

Definition at line 326 of file keyed_newick_reader.hpp.

◆ set_delimiters()

self_type& set_delimiters	(	std::string const &	prefix,
		std::string const &	separator,
		std::string const &	assigner = `"="`
	)

inline

Set the delimiters for key-value-pairs.

This function is a shortcut to set the prefix(), separator() and assigner() at once.

Definition at line 291 of file keyed_newick_reader.hpp.

◆ set_nhx_delimiters()

KeyedAttributeTreeNewickReaderPlugin & set_nhx_delimiters ( )

Set the delimiters to the format used by NHX.

These are

Prefix: &&NHX
Separator: :
Assigner: =

See add_nhx_attributes() for details on the NHX format.

Definition at line 102 of file keyed_newick_reader.cpp.

◆ trim() [1/2]

bool trim ( ) const

inline

Get whether to trim keys and values before storing them in the Tree.

Definition at line 373 of file keyed_newick_reader.hpp.

◆ trim() [2/2]

self_type& trim ( bool value )

inline

Set whether to trim keys and values before storing them in the Tree.

Default is true.

Definition at line 364 of file keyed_newick_reader.hpp.

Member Typedef Documentation

◆ self_type

using self_type = KeyedAttributeTreeNewickReaderPlugin

Definition at line 89 of file keyed_newick_reader.hpp.

Member Enumeration Documentation

◆ 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 94 of file keyed_newick_reader.hpp.

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

Detailed Description

Public Member Functions

Public Types

Constructor & Destructor Documentation

◆ KeyedAttributeTreeNewickReaderPlugin() [1/3]

◆ ~KeyedAttributeTreeNewickReaderPlugin()

◆ KeyedAttributeTreeNewickReaderPlugin() [2/3]

◆ KeyedAttributeTreeNewickReaderPlugin() [3/3]

Member Function Documentation

◆ add_attribute() [1/3]

◆ add_attribute() [2/3]

◆ add_attribute() [3/3]

◆ add_catch_all()

◆ add_nhx_attributes()

◆ assigner() [1/2]

◆ assigner() [2/2]

◆ clear()

◆ element_to_edge()

◆ element_to_node()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ prefix() [1/2]

◆ prefix() [2/2]

◆ register_with()

◆ separator() [1/2]

◆ separator() [2/2]

◆ set_delimiters()

◆ set_nhx_delimiters()

◆ trim() [1/2]

◆ trim() [2/2]

Member Typedef Documentation

◆ self_type

Member Enumeration Documentation

◆ Target