plotPhylo3D {treeDbalance}

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 = FALSE)

addPhylo3D(tree, offset = c(0, 0, 0), show_node_enum = FALSE)

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
)

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

A boolean value (default FALSE). If true, each node of the visualized phylo3D object is marked with its number. This helps to identify specific nodes and edges.

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.

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

Author(s)

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 = FALSE)
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)