A library for working with phylogenetic and population genetic data.
v0.27.0
NewickWriter Class Reference

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

Inherited by PlacementTreeNewickWriter, CommonTreeNewickWriter, and SimpleNewickTreeNewickWriter.

Detailed Description

Write a Tree to Newick format.

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

Tree tree;
CommonTreeNewickWriter().write( tree, utils::to_file( "path/to/file.newick" ));

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 CommonTreeNewickWriterPlugin is a convenience class that provides such plugin functions. It translates from a CommonTree 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 CommonTreeNewickWriter, which hides the whole plugin system and allows simple writing of default trees to standard Newick.

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

Public Member Functions

 NewickWriter ()=default
 
 NewickWriter (NewickWriter &&)=default
 
 NewickWriter (NewickWriter const &)=default
 
virtual ~NewickWriter ()=default
 
bool force_quotation_marks () const
 Get whether all names are wrapped in quotation marks. 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...
 
size_t line_length () const
 Get the currently set approximate maximal line length. More...
 
NewickWriterline_length (size_t value)
 Set the approximate maximal line length to use when writing Newick trees. More...
 
NewickWriteroperator= (NewickWriter &&)=default
 
NewickWriteroperator= (NewickWriter const &)=default
 
char quotation_mark () const
 Get the currently set type of quotation marks used for node names. More...
 
NewickWriterquotation_mark (char value)
 Set the type of quotation marks used for node names that contain special characters. More...
 
std::string to_string (Tree const &tree) const
 Shorthand to write a Tree to Newick format and return it is a string. More...
 
bool trailing_new_line () const
 Get the current setting for whether a new line char \n is written to the end of each tree. More...
 
NewickWritertrailing_new_line (bool value)
 Set whether to write a new line char \n at the end of each tree. More...
 
NewickBroker tree_to_broker (Tree const &tree) const
 Transform the information of the tree into a NewickBroker object. More...
 
void write (NewickBroker const &broker, std::shared_ptr< utils::BaseOutputTarget > target) const
 Write a NewickBroker to an output target, in Newick format. More...
 
void write (Tree const &tree, std::shared_ptr< utils::BaseOutputTarget > target) const
 Write a Tree to an output target, using the Newick format. More...
 
void write (TreeSet const &tree_set, std::shared_ptr< utils::BaseOutputTarget > target, bool with_names=false) const
 Write all Trees in a TreeSet to an output target, using the Newick format. More...
 
bool write_comments () const
 Get whether Newick comments (e.g., some forms of bootstrap values) are written. More...
 
NewickWriterwrite_comments (bool value)
 Set whether to write Newick comments (e.g., some forms of bootstrap values). More...
 
bool write_names () const
 Get whether Newick node names are written. More...
 
NewickWriterwrite_names (bool value)
 Set whether to write Newick node names. More...
 
bool write_tags () const
 Get whether Newick tags (e.g., for jplace files) are written. More...
 
NewickWriterwrite_tags (bool value)
 Set whether to write Newick tags (e.g., for jplace files). More...
 
bool write_values () const
 Get whether Newick values (e.g., branch lengths) are written. More...
 
NewickWriterwrite_values (bool value)
 Set whether to write Newick values (e.g., branch lengths). 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_functionedge_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_functionfinish_writing_plugins
 Collect all functions to be called after finishing the actual tree writing. More...
 
std::vector< node_to_element_functionnode_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_functionprepare_writing_plugins
 Collect all functions to be called before starting the actual tree writing. More...
 

Constructor & Destructor Documentation

◆ NewickWriter() [1/3]

NewickWriter ( )
default

◆ ~NewickWriter()

virtual ~NewickWriter ( )
virtualdefault

◆ NewickWriter() [2/3]

NewickWriter ( NewickWriter const &  )
default

◆ NewickWriter() [3/3]

NewickWriter ( NewickWriter &&  )
default

Member Function Documentation

◆ force_quotation_marks() [1/2]

bool force_quotation_marks ( ) const
inline

Get whether all names are wrapped in quotation marks.

See also
force_quotation_marks( bool )

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

◆ force_quotation_marks() [2/2]

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 parsers. See also quotation_mark( char ) to set the type of quotation mark.

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

◆ line_length() [1/2]

size_t line_length ( ) const
inline

Get the currently set approximate maximal line length.

Default is 0, which means, all is written in one long line.

See also
line_length( size_t )

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

◆ line_length() [2/2]

NewickWriter& line_length ( size_t  value)
inline

Set the approximate maximal line length to use when writing Newick trees.

Some large trees become hard to inspect in the resulting Newick file if the whole tree is written in just one long line. Also, some tools might not be able to handle such long lines properly. Hence, setting this option to a value other than 0 (default, which means, all is written in one line) leads to the writer inserting line breaks at the next possible character after the value line length has been reached. Hence, lines can be longer than the given value. Also, be aware that some other tools might not be able to read trees that are spread across several lines. Newick is messy.

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

◆ operator=() [1/2]

NewickWriter& operator= ( NewickWriter &&  )
default

◆ operator=() [2/2]

NewickWriter& operator= ( NewickWriter const &  )
default

◆ quotation_mark() [1/2]

char quotation_mark ( ) const
inline

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

See quotation_mark( char ) for details.

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

◆ quotation_mark() [2/2]

NewickWriter& quotation_mark ( 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 CommonTreeNewickWriterPlugin (or a CommonTreeNewickWriter, 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. Common 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 256 of file tree/formats/newick/writer.hpp.

◆ to_string()

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

Shorthand to write a Tree to Newick format and return it is a string.

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

◆ trailing_new_line() [1/2]

bool trailing_new_line ( ) const
inline

Get the current setting for whether a new line char \n is written to the end of each tree.

See also
trailing_new_line( bool )

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

◆ trailing_new_line() [2/2]

NewickWriter& trailing_new_line ( bool  value)
inline

Set whether to write a new line char \n at the end of each tree.

By default, this is set to true, meaning that each tree is finished with a \n char, which is usually desirable when writing to Newick files or the like. However, in cases where the Newick string itself is used in some other format (e.g., jplace or nexus), this might not be wanted. Hence, we allow to disable the new line.

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

◆ tree_to_broker()

NewickBroker tree_to_broker ( Tree const &  tree) const

Transform the information of the tree into a NewickBroker object.

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

◆ write() [1/3]

void write ( NewickBroker const &  broker,
std::shared_ptr< utils::BaseOutputTarget target 
) const

Write a NewickBroker to an output target, in Newick format.

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

◆ write() [2/3]

void write ( Tree const &  tree,
std::shared_ptr< utils::BaseOutputTarget target 
) const

Write a Tree to an output target, using the Newick format.

See the output target convenience functions utils::to_file(), utils::to_stream(), and utils::to_string() for examples of how to obtain a suitable output target.

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

◆ write() [3/3]

void write ( TreeSet const &  tree_set,
std::shared_ptr< utils::BaseOutputTarget target,
bool  with_names = false 
) const

Write all Trees in a TreeSet to an output target, using the Newick format.

Trees are separated from each other by semicolons and new line characters. If with_names is set to true, each tree is preprended by its name as stored in the TreeSet, in the format

name = (<newick tree>);

See the output target convenience functions utils::to_file(), utils::to_stream(), and utils::to_string() for examples of how to obtain a suitable output target.

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

◆ write_comments() [1/2]

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 411 of file tree/formats/newick/writer.hpp.

◆ write_comments() [2/2]

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 400 of file tree/formats/newick/writer.hpp.

◆ write_names() [1/2]

bool write_names ( ) const
inline

Get whether Newick node names are written.

See also
write_names( bool )

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

◆ write_names() [2/2]

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 356 of file tree/formats/newick/writer.hpp.

◆ write_tags() [1/2]

bool write_tags ( ) const
inline

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

See also
write_tags( bool )

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

◆ write_tags() [2/2]

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 423 of file tree/formats/newick/writer.hpp.

◆ write_values() [1/2]

bool write_values ( ) const
inline

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

See also
write_values( bool )

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

◆ write_values() [2/2]

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 378 of file tree/formats/newick/writer.hpp.

Member Typedef Documentation

◆ edge_to_element_function

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 149 of file tree/formats/newick/writer.hpp.

◆ finish_writing_function

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 129 of file tree/formats/newick/writer.hpp.

◆ node_to_element_function

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 139 of file tree/formats/newick/writer.hpp.

◆ prepare_writing_function

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 119 of file tree/formats/newick/writer.hpp.

Member Data Documentation

◆ edge_to_element_plugins

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 218 of file tree/formats/newick/writer.hpp.

◆ finish_writing_plugins

std::vector<finish_writing_function> finish_writing_plugins

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

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

◆ node_to_element_plugins

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 212 of file tree/formats/newick/writer.hpp.

◆ prepare_writing_plugins

std::vector<prepare_writing_function> prepare_writing_plugins

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

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


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