#include <genesis/tree/formats/newick/writer.hpp>
Inherited by PlacementTreeNewickWriter, CommonTreeNewickWriter, and SimpleNewickTreeNewickWriter.
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... | |
|
default |
|
virtualdefault |
|
default |
|
default |
|
inline |
Get whether all names are wrapped in quotation marks.
Definition at line 295 of file tree/formats/newick/writer.hpp.
|
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.
|
inline |
Get the currently set approximate maximal line length.
Default is 0, which means, all is written in one long line.
Definition at line 324 of file tree/formats/newick/writer.hpp.
|
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.
|
default |
|
default |
|
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.
|
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.
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.
|
inline |
Get the current setting for whether a new line char \n
is written to the end of each tree.
Definition at line 349 of file tree/formats/newick/writer.hpp.
|
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.
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.
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.
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.
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.
|
inline |
Get whether Newick comments (e.g., some forms of bootstrap values) are written.
Definition at line 415 of file tree/formats/newick/writer.hpp.
|
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.
|
inline |
Get whether Newick node names are written.
Definition at line 371 of file tree/formats/newick/writer.hpp.
|
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.
|
inline |
Get whether Newick tags (e.g., for jplace
files) are written.
Definition at line 438 of file tree/formats/newick/writer.hpp.
|
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.
|
inline |
Get whether Newick values (e.g., branch lengths) are written.
Definition at line 393 of file tree/formats/newick/writer.hpp.
|
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.
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.
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.
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.
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.
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.
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.
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.
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.