#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...

NewickWriter &	force_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...

NewickWriter &	line_length (size_t value)
	Set the approximate maximal line length to use when writing Newick trees. More...

NewickWriter &	operator= (NewickWriter &&)=default

NewickWriter &	operator= (NewickWriter const &)=default

char	quotation_mark () const
	Get the currently set type of quotation marks used for node names. More...

NewickWriter &	quotation_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...

NewickWriter &	trailing_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...

NewickWriter &	write_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...

NewickWriter &	write_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...

NewickWriter &	write_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...

NewickWriter &	write_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_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() [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 295 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 284 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 324 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 311 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 271 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_invalid_chars() 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 260 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 94 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 349 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 337 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 105 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 144 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 60 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 65 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 415 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 404 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 371 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 360 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 438 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 427 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 393 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 382 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 222 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 210 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 216 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 205 of file tree/formats/newick/writer.hpp.

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

Detailed Description

Public Member Functions

Public Types

Public Attributes

Constructor & Destructor Documentation

◆ NewickWriter() [1/3]

◆ ~NewickWriter()

◆ NewickWriter() [2/3]

◆ NewickWriter() [3/3]

Member Function Documentation

◆ force_quotation_marks() [1/2]

◆ force_quotation_marks() [2/2]

◆ line_length() [1/2]

◆ line_length() [2/2]

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ quotation_mark() [1/2]

◆ quotation_mark() [2/2]

◆ to_string()

◆ trailing_new_line() [1/2]

◆ trailing_new_line() [2/2]

◆ tree_to_broker()

◆ write() [1/3]

◆ write() [2/3]

◆ write() [3/3]

◆ write_comments() [1/2]

◆ write_comments() [2/2]

◆ write_names() [1/2]

◆ write_names() [2/2]

◆ write_tags() [1/2]

◆ write_tags() [2/2]

◆ write_values() [1/2]

◆ write_values() [2/2]

Member Typedef Documentation

◆ edge_to_element_function

◆ finish_writing_function

◆ node_to_element_function

◆ prepare_writing_function

Member Data Documentation

◆ edge_to_element_plugins

◆ finish_writing_plugins

◆ node_to_element_plugins

◆ prepare_writing_plugins