A toolkit for working with phylogenetic data.
v0.19.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"-like 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 101 of file tree/formats/newick/writer.hpp.

Public Member Functions

 NewickWriter ()=default
 
 NewickWriter (NewickWriter const &)=default
 
 NewickWriter (NewickWriter &&)=default
 
virtual ~NewickWriter ()=default
 
void broker_to_file (NewickBroker const &broker, std::string const &filename) const
 Writes a NewickBroker to a file in Newick format. More...
 
void broker_to_stream (NewickBroker const &broker, std::ostream &os) const
 Write a NewickBroker to a stream, in Newick format. More...
 
void broker_to_string (NewickBroker const &broker, std::string &ts) const
 Gives a Newick string representation of the tree. More...
 
std::string broker_to_string (NewickBroker const &broker) const
 Returns a Newick string representation of the tree. More...
 
NewickWriterforce_quotation_marks (bool value)
 If set to true, all names are wrapped in quotation marks, regardless of whether the name contains any characters that need to be wrapped. More...
 
bool force_quotation_marks () const
 Get whether all names are wrapped in quotation marks. More...
 
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_stream (Tree const &tree, std::ostream &os) const
 Write a Tree to a stream, 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...
 
NewickBroker tree_to_broker (Tree const &tree) const
 Transform the information of the tree into a NewickBroker object. 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

void broker_to_file ( NewickBroker const &  broker,
std::string const &  filename 
) const

Writes a NewickBroker to a file in Newick format.

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

void broker_to_stream ( NewickBroker const &  broker,
std::ostream &  os 
) const

Write a NewickBroker to a stream, in Newick format.

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

void broker_to_string ( NewickBroker const &  broker,
std::string &  ts 
) const

Gives a Newick string representation of the tree.

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

std::string broker_to_string ( NewickBroker const &  broker) const

Returns a Newick string representation of the tree.

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

NewickWriter& force_quotation_marks ( bool  value)
inline

If set to true, all names are wrapped in quotation marks, regardless of whether the name contains any characters that need to be wrapped.

Default is false. This setting can be used to ensure that all names have quotation marks, which is a requirement for certain other parser. See also quotation_marks( char ) to set the type of quotation mark.

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

bool force_quotation_marks ( ) const
inline

Get whether all names are wrapped in quotation marks.

See Also
force_quotation_marks( bool )

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

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 254 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 265 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 64 of file tree/formats/newick/writer.cpp.

void to_stream ( Tree const &  tree,
std::ostream &  os 
) const

Write a Tree to a stream, in Newick format.

Definition at line 59 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 72 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 80 of file tree/formats/newick/writer.cpp.

NewickBroker tree_to_broker ( Tree const &  tree) const

Transform the information of the tree into a NewickBroker object.

Definition at line 91 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 344 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 355 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 300 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 311 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 367 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 378 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 322 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 333 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 148 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 128 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 138 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 118 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 216 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 204 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 210 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 199 of file tree/formats/newick/writer.hpp.


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