set: Set (/update) features to a dendrogram

Description

a master function for updating various attributes and features of dendrogram objects.

Usage

set(dend, ...)
# S3 method for dendrogram
set(
  dend,
  what = c("labels", "labels_colors", "labels_cex", "labels_to_character", "leaves_pch",
    "leaves_cex", "leaves_col", "nodes_pch", "nodes_cex", "nodes_col", "hang_leaves",
    "rank_branches", "branches_k_color", "branches_k_lty", "branches_col", "branches_lwd",
    "branches_lty", "by_labels_branches_col", "by_labels_branches_lwd",
    "by_labels_branches_lty", "by_lists_branches_col", "by_lists_branches_lwd",
    "by_lists_branches_lty", "highlight_branches_col", "highlight_branches_lwd",
    "clear_branches", "clear_leaves"),
  value,
  order_value = FALSE,
  ...
)
# S3 method for dendlist
set(dend, ..., which)
# S3 method for data.table
set(...)

Arguments

dend

a tree (dendrogram, or dendlist)

...

passed to the specific function for more options.

what

a character indicating what is the property of the tree that should be set/updated. (see the usage and the example section for the different options)

value

an object with the value to set in the dendrogram tree. (the type of the value depends on the "what")

order_value

logical. Default is FALSE. If TRUE, it means the order of the value is in the order of the data which produced the hclust or dendrogram - and will reorder the value to conform with the order of the labels in the dendrogram.

which

an integer vector indicating, in the case "dend" is a dendlist, on which of the trees should the modification be performed. If missing - the change will be performed on all of dends in the dendlist.

Value

An updated dendrogram (or dendlist), with some change to the parameters of it

Details

This is a wrapper function for many of the main tasks we might wish to perform on a dendrogram before plotting.

The options of by_labels_branches_col, by_labels_branches_lwd, by_labels_branches_lty have extra parameters: type, attr, TF_value, and by_lists_branches_col, by_lists_branches_lwd, by_lists_branches_lty have extra parameters: attr, TF_value. You can read more about them here: branches_attr_by_labels and branches_attr_by_lists

The "what" parameter" can accept the following options:

labels - set the labels (labels<-.dendrogram)
labels_colors - set the labels' colors (color_labels)
labels_cex - set the labels' size (assign_values_to_leaves_nodePar)
labels_to_character - set the labels' to be characters
leaves_pch - set the leaves' point type (assign_values_to_leaves_nodePar). A leave is the terminal node of the tree.
leaves_cex - set the leaves' point size (assign_values_to_leaves_nodePar). For using this you MUST also set leaves_pch, a good value to use is 19.
leaves_col - set the leaves' point color (assign_values_to_leaves_nodePar). For using this you MUST also set leaves_pch, a good value to use is 19.
nodes_pch - set the nodes' point type (assign_values_to_nodes_nodePar)
nodes_cex - set the nodes' point size (assign_values_to_nodes_nodePar)
nodes_col - set the nodes' point color (assign_values_to_nodes_nodePar)
hang_leaves - hang the leaves (hang.dendrogram)
branches_k_color - color the branches (color_branches), a k parameter needs to be supplied.
branches_k_lty - updates the lwd of the branches (similar to branches_k_color), a k parameter needs to be supplied.
branches_col - set the color of branches (assign_values_to_branches_edgePar)
branches_lwd - set the line width of branches (assign_values_to_branches_edgePar)
branches_lty - set the line type of branches (assign_values_to_branches_edgePar)
by_labels_branches_col - set the color of branches with specific labels (branches_attr_by_labels)
by_labels_branches_lwd - set the line width of branches with specific labels (branches_attr_by_labels)
by_labels_branches_lty - set the line type of branches with specific labels (branches_attr_by_labels)
by_lists_branches_col - set the color of branches from the root of the tree down to (possibly inner) nodes with specified members (branches_attr_by_lists)
by_lists_branches_lwd - set the line width of branches from the root of the tree down to (possibly inner) nodes with specified members (branches_attr_by_lists)
by_lists_branches_lty - set the line type of branches from the root of the tree down to (possibly inner) nodes with specified members (branches_attr_by_lists)
highlight_branches_col - highlight branches color based on branches' heights (highlight_branches_col)
highlight_branches_lwd - highlight branches line-width based on branches' heights (highlight_branches_lwd)
clear_branches - clear branches' attributes (remove_branches_edgePar)
clear_leaves - clear leaves' attributes (remove_branches_edgePar)

Examples

Run this code

# NOT RUN {
# }
# NOT RUN {
set.seed(23235)
ss <- sample(1:150, 10)

# Getting the dend object
dend <- iris[ss, -5] %>%
  dist() %>%
  hclust() %>%
  as.dendrogram()
dend %>% plot()

dend %>% labels()
dend %>%
  set("labels", 1:10) %>%
  labels()
dend %>%
  set("labels", 1:10) %>%
  plot()
dend %>%
  set("labels_color") %>%
  plot()
dend %>%
  set("labels_col", c(1, 2)) %>%
  plot() # Works also with partial matching :)
dend %>%
  set("labels_cex", c(1, 1.2)) %>%
  plot()
dend %>%
  set("leaves_pch", NA) %>%
  plot()
dend %>%
  set("leaves_pch", c(1:5)) %>%
  plot()
dend %>%
  set("leaves_pch", c(19, 19, NA)) %>%
  set("leaves_cex", c(1, 2)) %>%
  plot()
dend %>%
  set("leaves_pch", c(19, 19, NA)) %>%
  set("leaves_cex", c(1, 2)) %>%
  set("leaves_col", c(1, 1, 2, 2)) %>%
  plot()
dend %>%
  set("hang") %>%
  plot()

dend %>%
  set("branches_k_col") %>%
  plot()
dend %>%
  set("branches_k_col", c(1, 2)) %>%
  plot()
dend %>%
  set("branches_k_col", c(1, 2, 3), k = 3) %>%
  plot()
dend %>%
  set("branches_k_col", k = 3) %>%
  plot()

dend %>%
  set("branches_k_lty", k = 3) %>%
  plot()
dend %>%
  set("branches_k_col", k = 3) %>%
  set("branches_k_lty", k = 3) %>%
  plot()

dend %>%
  set("branches_col", c(1, 2, 1, 2, NA)) %>%
  plot()
dend %>%
  set("branches_lwd", c(2, 1, 2)) %>%
  plot()
dend %>%
  set("branches_lty", c(1, 2, 1)) %>%
  plot()

#    clears all of the things added to the leaves
dend %>%
  set("labels_color", c(19, 19, NA)) %>%
  set("leaves_pch", c(19, 19, NA)) %>% # plot
  set("clear_leaves") %>% # remove all of what was done until this point
  plot()
# Different order
dend %>%
  set("leaves_pch", c(19, 19, NA)) %>%
  set("labels_color", c(19, 19, NA)) %>%
  set("clear_leaves") %>%
  plot()


# doing this without chaining (%>%) will NOT be fun:
dend %>%
  set("labels", 1:10) %>%
  set("labels_color") %>%
  set("branches_col", c(1, 2, 1, 2, NA)) %>%
  set("branches_lwd", c(2, 1, 2)) %>%
  set("branches_lty", c(1, 2, 1)) %>%
  set("hang") %>%
  plot()

par(mfrow = c(1, 3))
dend %>%
  set("highlight_branches_col") %>%
  plot()
dend %>%
  set("highlight_branches_lwd") %>%
  plot()
dend %>%
  set("highlight_branches_col") %>%
  set("highlight_branches_lwd") %>%
  plot()
par(mfrow = c(1, 1))

#----------------------------
# Examples for: by_labels_branches_col, by_labels_branches_lwd, by_labels_branches_lty

old_labels <- labels(dend)
dend %>%
  set("labels", seq_len(nleaves(dend))) %>%
  set("by_labels_branches_col", c(1:4, 7)) %>%
  set("by_labels_branches_lwd", c(1:4, 7)) %>%
  set("by_labels_branches_lty", c(1:4, 7)) %>%
  set("labels", old_labels) %>%
  plot()

dend %>%
  set("labels", seq_len(nleaves(dend))) %>%
  set("by_labels_branches_col", c(1:4, 7), type = "any", TF_values = c(4, 2)) %>%
  set("by_labels_branches_lwd", c(1:4, 7), type = "all", TF_values = c(4, 1)) %>%
  set("by_labels_branches_lty", c(1:4, 7), TF_values = c(4, 1)) %>%
  plot()

#---- using order_value
# This is probably not what you want, since cutree
# returns clusters in the order of the original data:
dend %>%
  set("labels_colors", cutree(dend, k = 3)) %>%
  plot()
# The way to fix it, is to use order_value = TRUE
# so that value is assumed to be in the order of the data:
dend %>%
  set("labels_colors", cutree(dend, k = 3), order_value = TRUE) %>%
  plot()


#----------------------------
# Example for: by_lists_branches_col, by_lists_branches_lwd, by_lists_branches_lty

L <- list(c("109", "123", "126", "145"), "29", c("59", "67", "97"))
dend %>%
  set("by_lists_branches_col", L, TF_value = "blue") %>%
  set("by_lists_branches_lwd", L, TF_value = 4) %>%
  set("by_lists_branches_lty", L, TF_value = 3) %>%
  plot()


#----------------------------
# A few dendlist examples:
dendlist(dend, dend) %>%
  set("hang") %>%
  plot()
dendlist(dend, dend) %>%
  set("branches_k_col", k = 3) %>%
  plot()
dendlist(dend, dend) %>%
  set("labels_col", c(1, 2)) %>%
  plot()

dendlist(dend, dend) %>%
  set("hang") %>%
  set("labels_col", c(1, 2), which = 1) %>%
  set("branches_k_col", k = 3, which = 2) %>%
  set("labels_cex", 1.2) %>%
  plot()


#----------------------------
# example of modifying the dendrogram in a heatmap:

library(gplots)
data(mtcars)
x <- as.matrix(mtcars)
rc <- rainbow(nrow(x), start = 0, end = .3)
cc <- rainbow(ncol(x), start = 0, end = .3)

##
##' demonstrate the effect of row and column dendrogram options
##
Rowv_dend <- x %>%
  dist() %>%
  hclust() %>%
  as.dendrogram() %>%
  set("branches_k", k = 3) %>%
  set("branches_lwd", 2) %>%
  ladderize() # rotate_DendSer
Colv_dend <- t(x) %>%
  dist() %>%
  hclust() %>%
  as.dendrogram() %>%
  set("branches_k", k = 3) %>%
  set("branches_lwd", 2) %>%
  ladderize() # rotate_DendSer
heatmap.2(x, Rowv = Rowv_dend, Colv = Colv_dend)
# }

Run the code above in your browser using DataLab