#include <tree.h>

Public Types
enum	TreeSearchType { FAST_TREE_SEARCH , NORMAL_TREE_SEARCH , EXHAUSTIVE_TREE_SEARCH , UNKNOWN_TREE_SEARCH }

enum	TreeType { BIN_TREE , MUL_TREE , UNKNOWN_TREE }

Public Member Functions
	Tree (Alignment aln, Model model, std::istream &tree_stream, const bool fixed_blengths=false, std::unique_ptr< cmaple::Params > &&params=nullptr)
	Constructor from a stream of a (bifurcating or multifurcating) tree (with/without branch lengths in NEWICK format), which may or may not contain all taxa in the alignment. Model parameters (if not fixed) will be estimated according to the input tree and the alignment.

	Tree (Alignment aln, Model model, const std::string &tree_filename="", const bool fixed_blengths=false, std::unique_ptr< cmaple::Params > &&params=nullptr)
	Constructor from an optional (bifurcating or multifurcating) tree (with/without branch lengths in NEWICK format), which may or may not contain all taxa in the alignment. If users specify an input tree, model parameters (if not fixed) will be estimated according to that tree and the alignment.

	~Tree ()

void	load (std::istream &tree_stream, const bool fixed_blengths=false)
	Load a tree from a stream of a (bifurcating or multifurcating) tree (with/without branch lengths) in NEWICK format, which may or may not contain all taxa in the alignment. Model parameters (if not fixed) will be estimated according to the input tree and the alignment.

void	load (const std::string &tree_filename, const bool fixed_blengths=false)
	Load a tree from a (bifurcating or multifurcating) tree (with/without branch lengths) in NEWICK format, which may or may not contain all taxa in the alignment. Model parameters (if not fixed) will be estimated according to the input tree and the alignment.

void	changeAln (Alignment *aln)
	Change the alignment.

void	changeModel (Model *model)
	Change the substitution model.

void	doPlacement (std::ostream &out_stream=std::cout)
	Do placement (using stepwise addition) to build an initial tree. Model parameters (if not fixed) will be estimated during the placement process.

void	applySPR (const TreeSearchType tree_search_type, const bool shallow_tree_search, std::ostream &out_stream=std::cout)
	Apply SPR moves to optimize the tree.

void	optimizeBranch (std::ostream &out_stream=std::cout)
	Optimize the branch lengths of the tree.

void	infer (const TreeSearchType tree_search_type=NORMAL_TREE_SEARCH, const bool shallow_tree_search=false, std::ostream &out_stream=std::cout)
	Infer a maximum likelihood tree by executing doPlacement(), applySPR(), and optimizeBranch()

RealNumType	computeLh ()
	Compute the log likelihood of the current tree, which may or may not contain all taxa in the alignment.

void	computeBranchSupport (const int num_threads=1, const int num_replicates=1000, const double epsilon=0.1, const bool allow_replacing_ML_tree=true, std::ostream &out_stream=std::cout)
	Compute branch supports (aLRT-SH) of the current tree, which may or may not contain all taxa in the alignment.

std::string	exportNewick (const TreeType tree_type=BIN_TREE, const bool show_branch_supports=true)
	Export the phylogenetic tree to a string in NEWICK format.

Detailed Description

The structure of a phylogenetic tree

Member Enumeration Documentation

◆ TreeSearchType

enum cmaple::Tree::TreeSearchType

Types of tree search

Enumerator
FAST_TREE_SEARCH	No tree search (placement only)
NORMAL_TREE_SEARCH	Consider pruning branches only at newly-added nodes when seeking SPR moves
EXHAUSTIVE_TREE_SEARCH	Consider all nodes when seeking SPR moves
UNKNOWN_TREE_SEARCH	Unknown (not specified)

◆ TreeType

enum cmaple::Tree::TreeType

Types of trees

Enumerator
BIN_TREE	Binary tree
MUL_TREE	Multifurcating tree
UNKNOWN_TREE	Unknown tree type

Constructor & Destructor Documentation

◆ Tree() [1/2]

cmaple::Tree::Tree	(	Alignment *	aln,
		Model *	model,
		std::istream &	tree_stream,
		const bool	fixed_blengths = `false`,
		std::unique_ptr< cmaple::Params > &&	params = `nullptr`
	)

Constructor from a stream of a (bifurcating or multifurcating) tree (with/without branch lengths in NEWICK format), which may or may not contain all taxa in the alignment. Model parameters (if not fixed) will be estimated according to the input tree and the alignment.

Parameters

[in]	aln	An alignment
[in]	model	A substitution model
[in]	tree_stream	A stream of an input tree
[in]	fixed_blengths	TRUE to keep the input branch lengths unchanged (optional)
[in]	params	an instance of Params which stores all program parameters (optional). Users can build an instance of Params and specify several parameters by using ParamsBuilder

Exceptions

std::invalid_argument	If any of the following situation occurs. the sequence type is unsupported (neither DNA (for nucleotide data) nor AA (for protein data)) the alignment is empty the model is unknown/unsupported the tree is in an incorrect format
std::logic_error	if any of the following situations occur. any taxa in the tree (if specified) is not found in the alignment unexpected values/behaviors found during the operations
std::bad_alloc	if failing to allocate memory to store the tree

◆ Tree() [2/2]

cmaple::Tree::Tree	(	Alignment *	aln,
		Model *	model,
		const std::string &	tree_filename = `""`,
		const bool	fixed_blengths = `false`,
		std::unique_ptr< cmaple::Params > &&	params = `nullptr`
	)

Constructor from an optional (bifurcating or multifurcating) tree (with/without branch lengths in NEWICK format), which may or may not contain all taxa in the alignment. If users specify an input tree, model parameters (if not fixed) will be estimated according to that tree and the alignment.

Parameters

[in]	aln	An alignment
[in]	model	A substitution model
[in]	tree_filename	Name of a tree file (optinal)
[in]	fixed_blengths	TRUE to keep the input branch lengths unchanged (optional)
[in]	params	an instance of Params which stores all program parameters (optional). Users can build an instance of Params and specify several parameters by using ParamsBuilder

Exceptions

std::invalid_argument	If any of the following situation occurs. the sequence type is unsupported (neither DNA (for nucleotide data) nor AA (for protein data)) the alignment is empty the model is unknown/unsupported the tree (if specified) is in an incorrect format
ios::failure	if the tree file (if specified) is not found
std::logic_error	if any of the following situations occur. any taxa in the tree (if specified) is not found in the alignment unexpected values/behaviors found during the operations
std::bad_alloc	if failing to allocate memory to store the tree

◆ ~Tree()

cmaple::Tree::~Tree ( )

Destructor

Member Function Documentation

◆ load() [1/2]

void cmaple::Tree::load	(	std::istream &	tree_stream,
		const bool	fixed_blengths = `false`
	)

Load a tree from a stream of a (bifurcating or multifurcating) tree (with/without branch lengths) in NEWICK format, which may or may not contain all taxa in the alignment. Model parameters (if not fixed) will be estimated according to the input tree and the alignment.

Parameters

[in]	tree_stream	A stream of an input tree
[in]	fixed_blengths	TRUE to keep the input branch lengths unchanged (optional)

Exceptions

std::invalid_argument	if the tree is empty or in an incorrect format
std::logic_error	if any of the following situations occur. the attached substitution model is unknown/unsupported any taxa in the tree is not found in the alignment unexpected values/behaviors found during the operations
std::bad_alloc	if failing to allocate memory to store the tree

◆ load() [2/2]

void cmaple::Tree::load	(	const std::string &	tree_filename,
		const bool	fixed_blengths = `false`
	)

Load a tree from a (bifurcating or multifurcating) tree (with/without branch lengths) in NEWICK format, which may or may not contain all taxa in the alignment. Model parameters (if not fixed) will be estimated according to the input tree and the alignment.

Parameters

[in]	tree_filename	Name of a tree file
[in]	fixed_blengths	TRUE to keep the input branch lengths unchanged (optional)

Exceptions

std::invalid_argument	if the tree is empty or in an incorrect format
ios::failure	if the tree file is not found
std::logic_error	if any of the following situations occur. the attached substitution model is unknown/unsupported any taxa in the tree is not found in the alignment unexpected values/behaviors found during the operations
std::bad_alloc	if failing to allocate memory to store the tree

◆ changeAln()

void cmaple::Tree::changeAln ( Alignment * aln )

Change the alignment.

Parameters

[in] aln An alignment

Exceptions

std::invalid_argument	If the alignment is empty
std::logic_error	if any of the following situations occur. any taxa in the tree is not found in the new alignment the sequence type of the new alignment is different from the old one unexpected values/behaviors found during the operations

◆ changeModel()

void cmaple::Tree::changeModel ( Model * model )

Change the substitution model.

Parameters

[in] model A substitution model

Exceptions

std::invalid_argument	if the model is unknown/unsupported
std::logic_error	if any of the following situations occur. the sequence type of the new model is different from the old one unexpected values/behaviors found during the operations

◆ doPlacement()

void cmaple::Tree::doPlacement ( std::ostream & out_stream = std::cout )

Do placement (using stepwise addition) to build an initial tree. Model parameters (if not fixed) will be estimated during the placement process.

If users didn't supply an input tree or supplied an incomplete tree (which doesn't contain all the taxa in the alignment) when initializing the tree (by Tree() constructor), this function will add new taxa (which are not existed in the input tree) from the alignment to the tree.
If users already supplied a complete tree, this function does nothing.

Parameters

[out] out_stream The output message stream (optional)

Exceptions

std::logic_error

if any of the following situations occur.

the attached substitution model is unknown/unsupported
unexpected values/behaviors found during the operations

◆ applySPR()

void cmaple::Tree::applySPR	(	const TreeSearchType	tree_search_type,
		const bool	shallow_tree_search,
		std::ostream &	out_stream = `std::cout`
	)

Apply SPR moves to optimize the tree.

Parameters

[in]	tree_search_type	A type of tree search
[in]	shallow_tree_search	TRUE to enable a shallow tree search before a deeper tree search
[out]	out_stream	The output message stream (optional)

Exceptions

std::logic_error

if any of the following situations occur.

the tree is empty
the attached substitution model is unknown/unsupported
unexpected values/behaviors found during the operations

◆ optimizeBranch()

void cmaple::Tree::optimizeBranch ( std::ostream & out_stream = std::cout )

Optimize the branch lengths of the tree.

Parameters

[out] out_stream The output message stream (optional)

Exceptions

std::logic_error

if any of the following situations occur.

the tree is empty
the attached substitution model is unknown/unsupported
unexpected values/behaviors found during the operations

◆ infer()

void cmaple::Tree::infer	(	const TreeSearchType	tree_search_type = `NORMAL_TREE_SEARCH`,
		const bool	shallow_tree_search = `false`,
		std::ostream &	out_stream = `std::cout`
	)

Infer a maximum likelihood tree by executing doPlacement(), applySPR(), and optimizeBranch()

If users didn't supply an input tree or supplied an incomplete tree (which doesn't contain all the taxa in the alignment) when initializing the tree (by Tree() constructor), this function:
- performs placement (i.e., adding missing taxa from the alignment to the tree)
- applies a NORMAL tree search (which does SPR moves only on newly-added nodes)
- optimizes all branch lengths
If users already supplied a complete tree, this function, by default, does neither placement nor tree search, but it optimizes all branch lengths. If users want to keep the branch lengths fixed, they should set fixed_blengths = true when initializing the tree (by Tree() constructor);
If users want to use the input (complete/incomplete) tree as a starting tree to perform placement (for an incomplete tree), then consider SPR moves on all nodes, and optimize branch lengths, they can set tree_search_type = EXHAUSTIVE

Parameters

[in]	tree_search_type	A type of tree search (optional)
[in]	shallow_tree_search	TRUE to enable a shallow tree search before a deeper tree search (optional)
[out]	out_stream	The output message stream (optional)

Exceptions

std::invalid_argument	if tree_search_type is unknown
std::logic_error	if any of the following situations occur. the attached substitution model is unknown/unsupported unexpected values/behaviors found during the operations

◆ computeLh()

RealNumType cmaple::Tree::computeLh ( )

Compute the log likelihood of the current tree, which may or may not contain all taxa in the alignment.

Returns: The log likelihood of the current tree

Exceptions

std::logic_error

if any of the following situations occur.

the tree is empty
the attached substitution model is unknown/unsupported
unexpected values/behaviors found during the operations

◆ computeBranchSupport()

void cmaple::Tree::computeBranchSupport	(	const int	num_threads = `1`,
		const int	num_replicates = `1000`,
		const double	epsilon = `0.1`,
		const bool	allow_replacing_ML_tree = `true`,
		std::ostream &	out_stream = `std::cout`
	)

Compute branch supports (aLRT-SH) of the current tree, which may or may not contain all taxa in the alignment.

Parameters

[in]	num_threads	The number of threads (optional)
[in]	num_replicates	A positive number of replicates (optional)
[in]	epsilon	A positive epsilon (optional), which is used to avoid rounding effects, when the best and second best NNI trees have nearly identical site log-likelihood values (see Guindon et al., 2010)
[in]	allow_replacing_ML_tree	TRUE to allow replacing the ML tree by a higher likelihood tree found when computing branch supports (optional)
[out]	out_stream	The output message stream (optional)

Exceptions

std::invalid_argument	if any of the following situations occur. num_threads < 0 or num_threads > the number of CPU cores num_replicates <= 0 epsilon < 0
std::logic_error	if any of the following situations occur. the tree is empty the attached substitution model is unknown/unsupported unexpected values/behaviors found during the operations

◆ exportNewick()

std::string cmaple::Tree::exportNewick	(	const TreeType	tree_type = `BIN_TREE`,
		const bool	show_branch_supports = `true`
	)

Export the phylogenetic tree to a string in NEWICK format.

Parameters

[in]	tree_type	The type of the output tree (optional): BIN_TREE (bifurcating tree), MUL_TREE (multifurcating tree)
[in]	show_branch_supports	TRUE to output the branch supports (aLRT-SH values)

Returns: A tree string in NEWICK format

Exceptions

std::invalid_argument

if any of the following situations occur.

tree_type is unknown

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

tree/tree.h

Public Types

Public Member Functions

Detailed Description

Member Enumeration Documentation

◆ TreeSearchType

◆ TreeType

Constructor & Destructor Documentation

◆ Tree() [1/2]

◆ Tree() [2/2]

◆ ~Tree()

Member Function Documentation

◆ load() [1/2]

◆ load() [2/2]

◆ changeAln()

◆ changeModel()

◆ doPlacement()

◆ applySPR()

◆ optimizeBranch()

◆ infer()

◆ computeLh()

◆ computeBranchSupport()

◆ exportNewick()