R: Set (/update) features to a dendrogram

set {dendextend} | R Documentation

## 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 class '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 class 'dendlist'
    set(dend, ..., which)

    ## S3 method for class '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.

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

- leaves_cex - set the leaves' point size (assign_values_to_leaves_nodePar)

- leaves_col - set the leaves' point color (assign_values_to_leaves_nodePar)

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

### Value

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

### See Also

labels<-.dendrogram, labels_colors<-, hang.dendrogram, color_branches, assign_values_to_leaves_nodePar, assign_values_to_branches_edgePar, remove_branches_edgePar, remove_leaves_nodePar, noded_with_condition, branches_attr_by_labels, branches_attr_by_lists, dendrogram

### Examples

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

    ## End(Not run)

[Package dendextend version 1.8.0 Index]