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

#include <genesis/tree/formats/newick/writer.hpp>

Inherited by PlacementTreeNewickWriter, and DefaultTreeNewickWriter.

Detailed Description

Write a Tree to Newick format.

This class supports to write a Tree into a Newick format representation, using

It understands the Newick format, but is agnostic of the actual data representation of TreeNode and TreeEdge data. This approach allows to store data in any wanted format. For example, bootstrap values could be stored as either Newick comments ("[0.4]") or as a second "branch length" value (":0.4"), depending on the user's needs.

In order to translate data from the Tree into a Newick format representation, a set of plugin functions is used, that need to be set before writing a Tree. Those functions are a form of intermediaries, which take tree data and turn them into the wanted Newick representation. It is possible to use lambdas for this, or any other function that can be stored in a std::function.

The following plugin points are provided:

For example, the DefaultTreeNewickWriterPlugin is a convenience class that provides such plugin functions. It translates from a DefaultTree with TreeNodes that contain names and TreeEdges that contain branch lengths into the standard Newick format. Using plugin classes like this additionally allows to use state for the plugin functions - that is, to use some settings for how to write data.

Furthermore, as we use vectors of plugin functions, it is possible (and often necessary) to register multiple such functions, which are then called one after another. This allows to e.g., first translate a branch length for an edge in one plugin function, and then translating a bootstrap value or edge color in another plugin function.

This whole approach is a bit tedious, but unfortunately the price for the flexibility of this class. In order to keep the standard use cases simple, we also provide classes like DefaultTreeNewickWriter, which hides the whole plugin system and allows simple writing of default trees to standard Newick.

Definition at line 99 of file tree/formats/newick/writer.hpp.

Public Member Functions

 NewickWriter ()=default
 
 NewickWriter (NewickWriter const &)=default
 
 NewickWriter (NewickWriter &&)=default
 
virtual ~NewickWriter ()=default
 
NewickWriteroperator= (NewickWriter const &)=default
 
NewickWriteroperator= (NewickWriter &&)=default
 
NewickWriterquotation_marks (char value)
 Set the type of quotation marks used for node names that contain special characters. More...
 
char quotation_marks () const
 Get the currently set type of quotation marks used for node names. More...
 
void to_file (Tree const &tree, std::string const &filename) const
 Writes the tree to a file in Newick format. More...
 
void to_string (Tree const &tree, std::string &ts) const
 Gives a Newick string representation of the tree. More...
 
std::string to_string (Tree const &tree) const
 Returns a Newick string representation of the tree. More...
 
NewickWriterwrite_comments (bool value)
 Set whether to write Newick comments (e.g., some forms of bootstrap values). More...
 
bool write_comments () const
 Get whether Newick comments (e.g., some forms of bootstrap values) are written. More...
 
NewickWriterwrite_names (bool value)
 Set whether to write Newick node names. More...
 
bool write_names () const
 Get whether Newick node names are written. More...
 
NewickWriterwrite_tags (bool value)
 Set whether to write Newick tags (e.g., for jplace files). More...
 
bool write_tags () const
 Get whether Newick tags (e.g., for jplace files) are written. More...
 
NewickWriterwrite_values (bool value)
 Set whether to write Newick values (e.g., branch lengths). More...
 
bool write_values () const
 Get whether Newick values (e.g., branch lengths) are written. More...
 

Public Types

using edge_to_element_function = std::function< void(TreeEdge const &edge, NewickBrokerElement &element) >
 Function type that translates from a TreeEdge to a NewickBrokerElement. More...
 
using finish_writing_function = std::function< void(Tree const &tree, NewickBroker &broker) >
 Function type that allows to do some finalizing work with the Tree and NewickBroker after the actual tree writing finished. More...
 
using node_to_element_function = std::function< void(TreeNode const &node, NewickBrokerElement &element) >
 Function type that translates from a TreeNode to a NewickBrokerElement. More...
 
using prepare_writing_function = std::function< void(Tree const &tree, NewickBroker &broker) >
 Function type that allows to do some preparatory work with the Tree and NewickBroker before the actual tree writing begins. More...
 

Public Attributes

std::vector
< edge_to_element_function
edge_to_element_plugins
 Collect all functions to be called for each TreeEdge in order to translate it to a Newick representation. More...
 
std::vector
< finish_writing_function
finish_writing_plugins
 Collect all functions to be called after finishing the actual tree writing. More...
 
std::vector
< node_to_element_function
node_to_element_plugins
 Collect all functions to be called for each TreeNode in order to translate it to a Newick representation. More...
 
std::vector
< prepare_writing_function
prepare_writing_plugins
 Collect all functions to be called before starting the actual tree writing. More...
 

Constructor & Destructor Documentation

NewickWriter ( )
default
virtual ~NewickWriter ( )
virtualdefault
NewickWriter ( NewickWriter const &  )
default
NewickWriter ( NewickWriter &&  )
default

Member Function Documentation

NewickWriter& operator= ( NewickWriter const &  )
default
NewickWriter& operator= ( NewickWriter &&  )
default
NewickWriter& quotation_marks ( char  value)
inline

Set the type of quotation marks used for node names that contain special characters.

According to http://evolution.genetics.washington.edu/phylip/newicktree.html,

"A name can be any string of printable characters except blanks, colons, semicolons, parentheses, and square brackets."

They forgot to mention commas in that list. One more reason to be suspicious of the Newick format. Anyway, whenever one of these characters (including commas) occurs in the name of a node (see NewickBrokerElement::name), the writer wraps the whole name in quotation markes. This is not officially in the standard, but common practice.

Remark: When using a DefaultTreeNewickWriterPlugin (or a DefaultTreeNewickWriter, as it internally uses the plugin), you can use its setting replace_name_spaces() in order to replace any spaces in node nams into underscores.

This function sets the kind of quotation marks used for wrapping such names. Default are double quotation marks ('"'), which seem to be understood by many other programs that work with Newick trees.

We currently do not support a function to deactivate quotation marks - they are used whenever necessary, for safety reasons. Otherwise, we'd end up with invalid trees anyway. Thus, in order to get a Newick tree without any quotation marks, make sure that your node names do not contain any of the listed characters.

Lastly, if write_tags() is true, names with curly braces in them ('{}') are also wrapped in quotation marks, as those are used for tags.

Definition at line 247 of file tree/formats/newick/writer.hpp.

char quotation_marks ( ) const
inline

Get the currently set type of quotation marks used for node names.

See quotation_marks( char ) for details.

Definition at line 258 of file tree/formats/newick/writer.hpp.

void to_file ( Tree const &  tree,
std::string const &  filename 
) const

Writes the tree to a file in Newick format.

If the file cannot be written to, the function throws an exception. Also, by default, if the file already exists, an exception is thrown. See Options::allow_file_overwriting() to change this behaviour.

Definition at line 58 of file tree/formats/newick/writer.cpp.

void to_string ( Tree const &  tree,
std::string &  ts 
) const

Gives a Newick string representation of the tree.

Definition at line 66 of file tree/formats/newick/writer.cpp.

std::string to_string ( Tree const &  tree) const

Returns a Newick string representation of the tree.

Definition at line 72 of file tree/formats/newick/writer.cpp.

NewickWriter& write_comments ( bool  value)
inline

Set whether to write Newick comments (e.g., some forms of bootstrap values).

Default is true. This setting can be used to override any comments that might be set by a plugin.

Definition at line 313 of file tree/formats/newick/writer.hpp.

bool write_comments ( ) const
inline

Get whether Newick comments (e.g., some forms of bootstrap values) are written.

See Also
write_comments( bool )

Definition at line 324 of file tree/formats/newick/writer.hpp.

NewickWriter& write_names ( bool  value)
inline

Set whether to write Newick node names.

Default is true. This setting can be used to override any names that might be set by a plugin.

Definition at line 269 of file tree/formats/newick/writer.hpp.

bool write_names ( ) const
inline

Get whether Newick node names are written.

See Also
write_names( bool )

Definition at line 280 of file tree/formats/newick/writer.hpp.

NewickWriter& write_tags ( bool  value)
inline

Set whether to write Newick tags (e.g., for jplace files).

Default is true. This setting can be used to override any tags that might be set by a plugin. See NewickReader::enable_tags( bool ) for details on the inofficial Newick tags extension.

Definition at line 336 of file tree/formats/newick/writer.hpp.

bool write_tags ( ) const
inline

Get whether Newick tags (e.g., for jplace files) are written.

See Also
write_tags( bool )

Definition at line 347 of file tree/formats/newick/writer.hpp.

NewickWriter& write_values ( bool  value)
inline

Set whether to write Newick values (e.g., branch lengths).

Default is true. This setting can be used to override any values that might be set by a plugin.

Definition at line 291 of file tree/formats/newick/writer.hpp.

bool write_values ( ) const
inline

Get whether Newick values (e.g., branch lengths) are written.

See Also
write_values( bool )

Definition at line 302 of file tree/formats/newick/writer.hpp.

Member Typedef Documentation

using edge_to_element_function = std::function< void( TreeEdge const& edge, NewickBrokerElement& element ) >

Function type that translates from a TreeEdge to a NewickBrokerElement.

This is called for each TreeEdge while writing the Tree to Newick and is used to transfer data from the edge into a suitable representation in the Newick format.

Definition at line 146 of file tree/formats/newick/writer.hpp.

using finish_writing_function = std::function< void( Tree const& tree, NewickBroker& broker ) >

Function type that allows to do some finalizing work with the Tree and NewickBroker after the actual tree writing finished.

This can for example be used for some cleanup.

Definition at line 126 of file tree/formats/newick/writer.hpp.

using node_to_element_function = std::function< void( TreeNode const& node, NewickBrokerElement& element ) >

Function type that translates from a TreeNode to a NewickBrokerElement.

This is called for each TreeNode while writing the Tree to Newick and is used to transfer data from the node into a suitable representation in the Newick format.

Definition at line 136 of file tree/formats/newick/writer.hpp.

using prepare_writing_function = std::function< void( Tree const& tree, NewickBroker& broker ) >

Function type that allows to do some preparatory work with the Tree and NewickBroker before the actual tree writing begins.

This is for example useful if a certain kind of value for the nodes depends on other nodes. Using this function, such data can be collected and then used when writing the nodes.

Definition at line 116 of file tree/formats/newick/writer.hpp.

Member Data Documentation

std::vector<edge_to_element_function> edge_to_element_plugins

Collect all functions to be called for each TreeEdge in order to translate it to a Newick representation.

Definition at line 209 of file tree/formats/newick/writer.hpp.

std::vector<finish_writing_function> finish_writing_plugins

Collect all functions to be called after finishing the actual tree writing.

Definition at line 197 of file tree/formats/newick/writer.hpp.

std::vector<node_to_element_function> node_to_element_plugins

Collect all functions to be called for each TreeNode in order to translate it to a Newick representation.

Definition at line 203 of file tree/formats/newick/writer.hpp.

std::vector<prepare_writing_function> prepare_writing_plugins

Collect all functions to be called before starting the actual tree writing.

Definition at line 192 of file tree/formats/newick/writer.hpp.


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