treeDbalance (version 1.2.0)

plotPhylo3D: Plot a phylo3D object

Description

plotPhylo3D - Plots a phylo3D object using functions of the package 'rgl'.

addPhylo3D - This function plots a phylo3D object without any coordinate axis or adds the tree to an existing plot (e.g., for plotPhylo3D).

plotImbalPhylo3D - Plots a phylo3D object using functions of the package 'rgl'. Moreover, it uses either brightness or a color scale to indicate the imbalance.
Edge sections are shown darker or red with higher degree of imbalance and brighter or cyan if they are balanced. This function does not use the parameter edge.color
Attention: Edges of type 'bud' or 'leaf' will always be depicted as balanced, because they should represent leaf edges that are by definition always balanced.

addImbalPhylo3D - This function plots a phylo3D object without any coordinate axis or adds the tree to an existing plot (e.g., for plotImbalPhylo3D). Moreover, it uses either brightness or a color scale to indicate the imbalance.
Edge sections are shown darker or red with higher degree of imbalance and brighter or cyan if they are balanced. This function does not use the parameter edge.color.
Attention: Edges of type 'bud' or 'leaf' will always be depicted as balanced because they should represent leaf edges that are always balanced.

Usage

plotPhylo3D(tree, show_node_enum = NULL)
addPhylo3D(tree, offset = c(0, 0, 0), show_node_enum = NULL)
plotImbalPhylo3D(
  tree,
  imbal_type,
  max.seclen,
  color.imbal = TRUE,
  show.gradient = FALSE
)
addImbalPhylo3D(
  tree,
  offset = c(0, 0, 0),
  imbal_type,
  max.seclen,
  color.imbal = TRUE,
  show.gradient = FALSE
)

Value

plotPhylo3D No return value, called for side effects (plotting).

addPhylo3D No return value, called for side effects (plotting).

plotImbalPhylo3D No return value, called for side effects (plotting).

addImbalPhylo3D No return value, called for side effects (plotting).

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.
Optional: Add attribute 'edge.type' and/or 'edge.color' (character vectors e.g., c("d","b","l","l") and c("red","blue", "red", "gray30")) to the pylo3D object to plot the edges differently.
The \(i\)-th entry of 'edge.type' has to contain the type of the \(i\)-th edge. The following types are available: "d"= default cylinder, "b" = bud, and "l"=leaf. If 'edge.type' is not given, every edge is by default visualized as a cylinder.
Similar for the attribute 'edge.color'. If it is not given, every edge is depicted as "gray30" by default.
Furthermore, the attribute 'edge.diam' can also be added optionally to set the edge diameters. Otherwise, the edge diameters will be calculated based on the edge lengths and the edge weights (treated as volume).

show_node_enum

Character (vector) that specifies which node numbers should be depicted (none by default, NULL). This helps to identify specific nodes and edges. Available are the following options (can be combined, e.g. c("leaf_numbers","inner_numbers").
Use "leaf_numbers" to display the number of each leaf.
Use "leaf_labels" to display the label of each leaf.
Use "inner_numbers" to display the number of each interior node.

offset

Numeric vector of length 3, contains 3D coordinates by which the phylo object should be shifted (default = c(0,0,0), i.e., no shift).

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

max.seclen

Numeric value >0 that specifies the maximal section length.

color.imbal

Boolean value (default TRUE). If true, colors are used to depict the imbalance. Otherwise, a grayscale image is produced.

show.gradient

Boolean value (default FALSE). If true the color or grayscale gradient is depicted.

Author

Sophie Kersting

Examples

tree <- list(
  edge = matrix(c(1, 2, 2, 3), byrow = TRUE, ncol = 2),
  tip.label = "", Nnode = 2,
  node.coord = matrix(c(0, 0, 0, 1, 2, 2, 3, 1, 3),
    byrow = TRUE,
    ncol = 3
  ),
  edge.weight = c(0.5, 0.25), edge.type = c("d", "l")
)
class(tree) <- "phylo3D"
# Alternatively try: tree <- treeDbalance::example3Dtrees$bean09
plotPhylo3D(tree, show_node_enum = "leaf_numbers")
addPhylo3D(tree, offset = c(1, 1, 0))
plotImbalPhylo3D(tree,
  imbal_type = "mu", max.seclen = 0.5, color.imbal = TRUE,
  show.gradient = FALSE
)
addImbalPhylo3D(tree,
  imbal_type = "mu", offset = c(1, 0, 0), max.seclen = 0.5,
  color.imbal = FALSE, show.gradient = FALSE
)