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

#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 const &)=default
 
 KeyedAttributeTreeNewickReaderPlugin (KeyedAttributeTreeNewickReaderPlugin &&)=default
 
virtual ~KeyedAttributeTreeNewickReaderPlugin ()=default
 
self_typeadd_attribute (std::string const &key, Target target)
 Store values of a key at a target (i.e., Node or Edge). More...
 
self_typeadd_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_typeadd_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_typeadd_catch_all (Target target=Target::kNode)
 Store all key-value-pairs of the Newick data in an AttributeTree. More...
 
self_typeadd_nhx_attributes ()
 Add typical attributes of the NHX format, and set the appropriate delimiters. More...
 
self_typeassigner (std::string const &value)
 Set the assign symbol between a key and its value. More...
 
std::string assigner () const
 Get the currently set 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_typeoperator= (KeyedAttributeTreeNewickReaderPlugin const &)=default
 
self_typeoperator= (KeyedAttributeTreeNewickReaderPlugin &&)=default
 
self_typeprefix (std::string const &value)
 Set the prefix to look for in Newick comments. More...
 
std::string prefix () const
 Get the currently set prefix to look for in Newick comments. More...
 
void register_with (NewickReader &reader) const
 
self_typeseparator (std::string const &value)
 Set the separator between key-value-pairs. More...
 
std::string separator () const
 Get the currently set separator between key-value-pairs. More...
 
self_typeset_delimiters (std::string const &prefix, std::string const &separator, std::string const &assigner="=")
 Set the delimiters for key-value-pairs. More...
 
self_typeset_nhx_delimiters ()
 Set the delimiters to the format used by NHX. More...
 
self_typetrim (bool value)
 Set whether to trim keys and values before storing them in the Tree. More...
 
bool trim () const
 Get 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

virtual ~KeyedAttributeTreeNewickReaderPlugin ( )
virtualdefault

Member Function Documentation

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.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
keyKey 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.
targetTarget Tree element to store the data at. Either kNode or kEdge.

Definition at line 68 of file keyed_newick_reader.cpp.

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.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_keySource 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.
targetTarget Tree element to store the data at. Either kNode or kEdge.
target_keyTarget 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.

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_keySource 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.
targetTarget Tree element to store the data at. Either kNode or kEdge.
target_keyTarget key, used to store a value at the target Node or Edge.
default_valueDefault 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.

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;
auto tree = reader.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.

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.

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.

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.

void clear ( )

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

Definition at line 119 of file keyed_newick_reader.cpp.

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

Definition at line 150 of file keyed_newick_reader.cpp.

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

Definition at line 134 of file keyed_newick_reader.cpp.

self_type& operator= ( KeyedAttributeTreeNewickReaderPlugin const &  )
default
self_type& operator= ( KeyedAttributeTreeNewickReaderPlugin &&  )
default
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.

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.

void register_with ( NewickReader reader) const

Definition at line 166 of file keyed_newick_reader.cpp.

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.

std::string separator ( ) const
inline

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

Definition at line 335 of file keyed_newick_reader.hpp.

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.

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.

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.

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.

Member Typedef Documentation

Member Enumeration Documentation

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: