treeDbalance (version 1.2.0)

combined3DIndex: Calculation of combined 3D imbalance indices

Description

combined3DIndex - Calculates either the pure root imbalance value with regard to a specified vertical axis or the combined 3D imbalance index value of a 3D tree in phylo3D format. The latter is a weighted mean of the integral-based 3D imbalance index value (i.e., A_Index, alpha_Index, M_Index, or mu_Index with edge length or edge weight based weighting) as well as the root imbalance value.

Usage

combined3DIndex(
  tree,
  imbal_type,
  weight = "edge_weight",
  root_weight_factor = 1,
  vertical_axis = c(0, 0, 1)
)

Value

combined3DIndex Numeric value in the interval between 0 (included) and 1 (excluded). A value near 1 indicates a higher degree and near 0 a lower degree of asymmetry.

Arguments

tree

A rooted tree in phylo3D format (no special node enumeration required, except that nodes are numbered from 1 to |V| = the total number of nodes). There must be at least 2 nodes, i.e., one edge. The attributes 'node.coord' and 'edge.weight' are strictly required.

imbal_type

Specifies which node imbalance measurement should be used. Available are:
"A" - centroid angle
"alpha" - minimal centroid angle
"M" - expanded relative centroid distance
"mu" - relative centroid distance

weight

Specifies how the node imbalance values should be weighted. Available weighting methods are:
"edge_weight" (default) -> Imbalance with regards to the total edge weight.
"edge_length" -> Imbalance with regards to the total edge length.

root_weight_factor

Numeric value >0 (default 1), which specifies the weight of the root imbalance value in the weighted mean. For example, a weight of 1 means that both the imbalance index value of the whole tree as well as the root imbalance value contribute equally, i.e., the unweighted mean of the two values is returned. For a larger value, the influence of the root imbalance value increases.
If the weight is set to infinity (Inf), then the pure root imbalance value is returned.

vertical_axis

Numeric vector of length 3 (default (0,0,1)), which specifies the given vertical axis for the given tree model. For example, use the default (0,0,1) for models that grow straight upwards (e.g., trees) and (0,0,-1) for models that grow downwards (e.g., roots). The vector (0,0,0) is not allowed.

Author

Sophie Kersting

Examples

tree <- treeDbalance::extendPhylo(treeDbalance::example3Dtrees$bean09)
combined3DIndex(tree,
  imbal_type = "A", weight = "edge_weight",
  root_weight_factor = 2, vertical_axis = c(0, 0, 1)
)
combined3DIndex(tree,
  imbal_type = "A", root_weight_factor = Inf,
  vertical_axis = c(0, 0, 1)
)