deleted file mode 100755

@@ -1,216 +0,0 @@

-<!--

-%\VignetteEngine{knitr}

-%\VignetteIndexEntry{6. Heatmap Decoration}

-

-Heatmap Decoration

-========================================

-

-**Author**: Zuguang Gu ( z.gu@dkfz.de )

-

-**Date**: `r Sys.Date()`

-

-

-```{r global_settings, echo = FALSE, message = FALSE}

-library(markdown)

-options(markdown.HTML.options = c(options('markdown.HTML.options')[[1]], "toc"))

-

-library(knitr)

-knitr::opts_chunk$set(

-    error = FALSE,

-    tidy  = FALSE,

-    message = FALSE,

-    fig.align = "center",

-    fig.width = 5,

-    fig.height = 5)

-options(markdown.HTML.stylesheet = "custom.css")

-

-options(width = 100)

-```

-

-Each components of the heatmap/heatmap list has a name (unique id). You can go to any viewport 

-to add graphics in by specifying the heatmap/annotation name.

-

-First generate a figure that almost contains all types of heatmap components.

-

-```{r access_components, fig.width = 10, fig.height = 7, echo = 1:13}

-library(ComplexHeatmap)

-

-mat = matrix(rnorm(80, 2), 8, 10)

-mat = rbind(mat, matrix(rnorm(40, -2), 4, 10))

-rownames(mat) = paste0("R", 1:12)

-colnames(mat) = paste0("C", 1:10)

-

-ha_column1 = HeatmapAnnotation(points = anno_points(rnorm(10)))

-ht1 = Heatmap(mat, name = "ht1", km = 2, row_title = "Heatmap 1", column_title = "Heatmap 1", 

-    top_annotation = ha_column1)

-

-ha_column2 = HeatmapAnnotation(df = data.frame(type = c(rep("a", 5), rep("b", 5))),

-    col = list(type = c("a" = "red", "b" = "blue")))

-ht2 = Heatmap(mat, name = "ht2", row_title = "Heatmap 2", column_title = "Heatmap 2",

-    bottom_annotation = ha_column2)

-

-ht_list = ht1 + ht2 + rowAnnotation(bar = row_anno_barplot(rowMeans(mat)))

-draw(ht_list, row_title = "Heatmap list", column_title = "Heatmap list", 

-    heatmap_legend_side = "right", annotation_legend_side = "left")

-

-library(GetoptLong)

-seekViewport("global"); grid.rect(gp = gpar(fill = NA, col = "red"))

-seekViewport("global_column_title"); grid.rect(gp = gpar(fill = NA, col = "red"))

-seekViewport("global_row_title"); grid.rect(gp = gpar(fill = NA, col = "red"))

-seekViewport("main_heatmap_list"); grid.rect(gp = gpar(fill = NA, col = "red"))

-for(heatmap_name in c("ht1", "ht2")) {

-    seekViewport(qq("heatmap_@{heatmap_name}")); grid.rect(gp = gpar(fill = NA, col = "red"))

-    for(i in 1:2) {

-        seekViewport(qq("@{heatmap_name}_heatmap_body_@{i}")); grid.rect(gp = gpar(fill = NA, col = "red"))

-        seekViewport(qq("@{heatmap_name}_row_names_@{i}")); grid.rect(gp = gpar(fill = NA, col = "red"))

-    }

-        

-    seekViewport(qq("@{heatmap_name}_column_title")); grid.rect(gp = gpar(fill = NA, col = "red"))

-    seekViewport(qq("@{heatmap_name}_dend_column")); grid.rect(gp = gpar(fill = NA, col = "red"))

-    seekViewport(qq("@{heatmap_name}_column_names")); grid.rect(gp = gpar(fill = NA, col = "red"))

-    seekViewport(qq("legend_@{heatmap_name}")); grid.rect(gp = gpar(fill = NA, col = "red"))

-}

-seekViewport(qq("ht1_dend_row_2")); grid.rect(gp = gpar(fill = NA, col = "red"))

-seekViewport(qq("ht1_dend_row_1")); grid.rect(gp = gpar(fill = NA, col = "red"))

-seekViewport(qq("ht1_row_title_1")); grid.rect(gp = gpar(fill = NA, col = "red"))

-seekViewport(qq("ht1_row_title_2")); grid.rect(gp = gpar(fill = NA, col = "red"))

-

-

-for(annotation_name in c("points", "type")) {

-    seekViewport(qq("annotation_@{annotation_name}")); grid.rect(gp = gpar(fill = NA, col = "red"))

-}

-seekViewport(qq("annotation_bar_1")); grid.rect(gp = gpar(fill = NA, col = "red"))

-seekViewport(qq("annotation_bar_2")); grid.rect(gp = gpar(fill = NA, col = "red"))

-

-seekViewport(qq("legend_type")); grid.rect(gp = gpar(fill = NA, col = "red"))

-seekViewport(qq("legend_ht1")); grid.rect(gp = gpar(fill = NA, col = "red"))

-seekViewport(qq("legend_ht2")); grid.rect(gp = gpar(fill = NA, col = "red"))

-

-seekViewport("heatmap_legend"); grid.rect(gp = gpar(fill = NA, col = "red"))

-seekViewport("annotation_legend"); grid.rect(gp = gpar(fill = NA, col = "red"))

-```

-

-The components (viewports) that have names are:

-

-- `global`: the viewport which contains the whole figure.

-- `global_column_title`: the viewport which contains column title for the heatmap list.

-- `global_row_title`: the viewport which contains row title for the heatmap list.

-- `main_heatmap_list`: the viewport which contains a list of heatmaps and row annotations.

-- `heatmap_@{heatmap_name}`: the viewport which contains a single heatmap

-- `annotation_@{annotation_name}`: the viewport which contains an annotation on columns.

-- `annotation_@{annotation_name}_@{i}`: for row annotations

-- `@{heatmap_name}_heatmap_body_@{i}`: the heatmap body.

-- `@{heatmap_name}_column_title`: column title for a single heatmap.

-- `@{heatmap_name}_row_title_@{i}`: since a heatmap body may be splitted into several parts. `@{i}` is the index of the row slice.

-- `@{heatmap_name}_dend_row_@{i}`: dendrogram for ith row slice.

-- `@{heatmap_name}_dend_column`: dendrogram on columns

-- `@{heatmap_name}_row_names_@{i}`: the viewport which contains row names.

-- `@{heatmap_name}_column_names`: the viewport which contains column names.

-- `heatmap_legend`: the viewport which contains all heatmap legends.

-- `legend_@{heatmap_name}`: the viewport which contains a single heatmap legend.

-- `annotation_legend`: the viewport which contains all annotation legends.

-- `legend_@{annotation_name}`: the viewport which contains a single annotation legend.

-

-## decorate_* functions

-

-Basically, you can go to these components by `seekViewport()`, but to hide the details that is too low-level,

-**ComplexHeatmap** package provides `decorate_*` family functions which makes it easy to add graphics into different components.

-

-Following code add annotation names, mark one grid in the heatmap and seperate the first column clusters with two rectangles.

-

-```{r components, fig.width = 10, fig.height = 7}

-ht_list = draw(ht_list, row_title = "Heatmap list", column_title = "Heatmap list", 

-    heatmap_legend_side = "right", annotation_legend_side = "left")

-decorate_annotation("points", {

-    grid.text("points", unit(0, "npc") - unit(2, "mm"), 0.5, 

-        default.units = "npc", just = "right")

-})

-

-decorate_heatmap_body("ht1", {

-    grid.text("outlier", 1.5/10, 2.5/4, default.units = "npc")

-    grid.lines(c(0.5, 0.5), c(0, 1), gp = gpar(lty = 2, lwd = 2))

-}, slice = 2)

-

-decorate_column_dend("ht1", {

-    tree = column_dend(ht_list)$ht1

-    ind = cutree(as.hclust(tree), k = 2)[order.dendrogram(tree)]

-

-    first_index = function(l) which(l)[1]

-    last_index = function(l) { x = which(l); x[length(x)] }

-    x1 = c(first_index(ind == 1), first_index(ind == 2)) - 1

-    x2 = c(last_index(ind == 1), last_index(ind == 2))

-    grid.rect(x = x1/length(ind), width = (x2 - x1)/length(ind), just = "left",

-        default.units = "npc", gp = gpar(fill = c("#FF000040", "#00FF0040"), col = NA))

-})

-

-decorate_row_names("ht2", {

-    grid.rect(gp = gpar(fill = "#FF000040"))

-}, slice = 2)

-

-decorate_row_title("ht1", {

-    grid.rect(gp = gpar(fill = "#00FF0040"))

-}, slice = 1)

-

-decorate_annotation("points", {

-    grid.lines(c(0, 1), unit(c(0, 0), "native"), gp = gpar(col = "red"))

-})

-```

-

-For annotations which are created by `anno_points()`, `anno_barplot()` and `anno_boxplot()`, "native" unit

-can be used in the decoration code.

-

-## Add annotation names

-

-By default, annotation names are not plotted along with the heatmap annotations. The reason is

-if annotation names is plotted, they will located in the area of other heatmap components which

-would makes the adjustment of the heatmap layout difficult. `HeatmapAnnotation()` provides a 

-not-so-perfect [solution](s4.heatmap_annotation.html#toc_11) for adding annotation names, however, since you can go to any component 

-in the heatmap list by its name, actually it is not difficult to add annotation names manually.

-

-Following code add annotation names on the both sides of the column annotations. The drawback is

-since there is no specific component designed for annotation names, if the annotation name is too long,

-it will be exceeding the figure region (but this problem can be solved by some tricks, see the 

-[**Examples**](s9.examples.html) vignette).

-

-```{r annotation_title}

-df = data.frame(type1 = c(rep("a", 5), rep("b", 5)),

-                type2 = c(rep("A", 3), rep("B", 7)))

-ha = HeatmapAnnotation(df, col = list(type1 = c("a" = "red", "b" = "blue"),

-                                      type2 = c("A" = "green", "B" = "orange")))

-Heatmap(mat, name = "ht", top_annotation = ha)

-for(an in colnames(df)) {

-    decorate_annotation(an, {

-        # annotation names on the right

-        grid.text(an, unit(1, "npc") + unit(2, "mm"), 0.5, default.units = "npc", just = "left")

-        # annotation names on the left

-        grid.text(an, unit(0, "npc") - unit(2, "mm"), 0.5, default.units = "npc", just = "right")

-    })

-}

-```

-

-## Visualize distributions

-

-With heatmap decorations, actually you can design new graphics based on heatmaps. Following is an example:

-

-To visualize distribution of columns in a matrix or in a list, sometimes we use boxplot or beanplot.

-Here we can also use colors to map to the density values and visualize distribution of values

-in each column (or each list element) through a heatmap. Sometimes it can give you a more clear

-image of your data.

-

-Here the package has a `densityHeatmap()` function, the usage is quite straightforward:

-

-```{r, density}

-matrix = matrix(rnorm(100), 10); colnames(matrix) = letters[1:10]

-ha = HeatmapAnnotation(df = data.frame(anno = rep(c("A", "B"), each = 5)),

-    col = list(anno = c("A" = "green", "B" = "orange")),

-    points = anno_points(runif(10)))

-densityHeatmap(matrix, anno = ha)

-```

-

-## Session info

-

-```{r}

-sessionInfo()

-```

new file mode 100755

@@ -0,0 +1,216 @@

+<!--

+%\VignetteEngine{knitr}

+%\VignetteIndexEntry{6. Heatmap Decoration}

+-->

+

+Heatmap Decoration

+========================================

+

+**Author**: Zuguang Gu ( z.gu@dkfz.de )

+

+**Date**: `r Sys.Date()`

+

+-------------------------------------------------------------

+

+```{r global_settings, echo = FALSE, message = FALSE}

+library(markdown)

+options(markdown.HTML.options = c(options('markdown.HTML.options')[[1]], "toc"))

+

+library(knitr)

+knitr::opts_chunk$set(

+    error = FALSE,

+    tidy  = FALSE,

+    message = FALSE,

+    fig.align = "center",

+    fig.width = 5,

+    fig.height = 5)

+options(markdown.HTML.stylesheet = "custom.css")

+

+options(width = 100)

+```

+

+Each components of the heatmap/heatmap list has a name (unique id). You can go to any viewport 

+to add graphics in by specifying the heatmap/annotation name.

+

+First generate a figure that almost contains all types of heatmap components.

+

+```{r access_components, fig.width = 10, fig.height = 7, echo = 1:13}

+library(ComplexHeatmap)

+

+mat = matrix(rnorm(80, 2), 8, 10)

+mat = rbind(mat, matrix(rnorm(40, -2), 4, 10))

+rownames(mat) = paste0("R", 1:12)

+colnames(mat) = paste0("C", 1:10)

+

+ha_column1 = HeatmapAnnotation(points = anno_points(rnorm(10)))

+ht1 = Heatmap(mat, name = "ht1", km = 2, row_title = "Heatmap 1", column_title = "Heatmap 1", 

+    top_annotation = ha_column1)

+

+ha_column2 = HeatmapAnnotation(df = data.frame(type = c(rep("a", 5), rep("b", 5))),

+    col = list(type = c("a" = "red", "b" = "blue")))

+ht2 = Heatmap(mat, name = "ht2", row_title = "Heatmap 2", column_title = "Heatmap 2",

+    bottom_annotation = ha_column2)

+

+ht_list = ht1 + ht2 + rowAnnotation(bar = row_anno_barplot(rowMeans(mat)))

+draw(ht_list, row_title = "Heatmap list", column_title = "Heatmap list", 

+    heatmap_legend_side = "right", annotation_legend_side = "left")

+

+library(GetoptLong)

+seekViewport("global"); grid.rect(gp = gpar(fill = NA, col = "red"))

+seekViewport("global_column_title"); grid.rect(gp = gpar(fill = NA, col = "red"))

+seekViewport("global_row_title"); grid.rect(gp = gpar(fill = NA, col = "red"))

+seekViewport("main_heatmap_list"); grid.rect(gp = gpar(fill = NA, col = "red"))

+for(heatmap_name in c("ht1", "ht2")) {

+    seekViewport(qq("heatmap_@{heatmap_name}")); grid.rect(gp = gpar(fill = NA, col = "red"))

+    for(i in 1:2) {

+        seekViewport(qq("@{heatmap_name}_heatmap_body_@{i}")); grid.rect(gp = gpar(fill = NA, col = "red"))

+        seekViewport(qq("@{heatmap_name}_row_names_@{i}")); grid.rect(gp = gpar(fill = NA, col = "red"))

+    }

+        

+    seekViewport(qq("@{heatmap_name}_column_title")); grid.rect(gp = gpar(fill = NA, col = "red"))

+    seekViewport(qq("@{heatmap_name}_dend_column")); grid.rect(gp = gpar(fill = NA, col = "red"))

+    seekViewport(qq("@{heatmap_name}_column_names")); grid.rect(gp = gpar(fill = NA, col = "red"))

+    seekViewport(qq("legend_@{heatmap_name}")); grid.rect(gp = gpar(fill = NA, col = "red"))

+}

+seekViewport(qq("ht1_dend_row_2")); grid.rect(gp = gpar(fill = NA, col = "red"))

+seekViewport(qq("ht1_dend_row_1")); grid.rect(gp = gpar(fill = NA, col = "red"))

+seekViewport(qq("ht1_row_title_1")); grid.rect(gp = gpar(fill = NA, col = "red"))

+seekViewport(qq("ht1_row_title_2")); grid.rect(gp = gpar(fill = NA, col = "red"))

+

+

+for(annotation_name in c("points", "type")) {

+    seekViewport(qq("annotation_@{annotation_name}")); grid.rect(gp = gpar(fill = NA, col = "red"))

+}

+seekViewport(qq("annotation_bar_1")); grid.rect(gp = gpar(fill = NA, col = "red"))

+seekViewport(qq("annotation_bar_2")); grid.rect(gp = gpar(fill = NA, col = "red"))

+

+seekViewport(qq("legend_type")); grid.rect(gp = gpar(fill = NA, col = "red"))

+seekViewport(qq("legend_ht1")); grid.rect(gp = gpar(fill = NA, col = "red"))

+seekViewport(qq("legend_ht2")); grid.rect(gp = gpar(fill = NA, col = "red"))

+

+seekViewport("heatmap_legend"); grid.rect(gp = gpar(fill = NA, col = "red"))

+seekViewport("annotation_legend"); grid.rect(gp = gpar(fill = NA, col = "red"))

+```

+

+The components (viewports) that have names are:

+

+- `global`: the viewport which contains the whole figure.

+- `global_column_title`: the viewport which contains column title for the heatmap list.

+- `global_row_title`: the viewport which contains row title for the heatmap list.

+- `main_heatmap_list`: the viewport which contains a list of heatmaps and row annotations.

+- `heatmap_@{heatmap_name}`: the viewport which contains a single heatmap

+- `annotation_@{annotation_name}`: the viewport which contains an annotation on columns.

+- `annotation_@{annotation_name}_@{i}`: for row annotations

+- `@{heatmap_name}_heatmap_body_@{i}`: the heatmap body.

+- `@{heatmap_name}_column_title`: column title for a single heatmap.

+- `@{heatmap_name}_row_title_@{i}`: since a heatmap body may be splitted into several parts. `@{i}` is the index of the row slice.

+- `@{heatmap_name}_dend_row_@{i}`: dendrogram for ith row slice.

+- `@{heatmap_name}_dend_column`: dendrogram on columns

+- `@{heatmap_name}_row_names_@{i}`: the viewport which contains row names.

+- `@{heatmap_name}_column_names`: the viewport which contains column names.

+- `heatmap_legend`: the viewport which contains all heatmap legends.

+- `legend_@{heatmap_name}`: the viewport which contains a single heatmap legend.

+- `annotation_legend`: the viewport which contains all annotation legends.

+- `legend_@{annotation_name}`: the viewport which contains a single annotation legend.

+

+## decorate_* functions

+

+Basically, you can go to these components by `seekViewport()`, but to hide the details that is too low-level,

+**ComplexHeatmap** package provides `decorate_*` family functions which makes it easy to add graphics into different components.

+

+Following code add annotation names, mark one grid in the heatmap and seperate the first column clusters with two rectangles.

+

+```{r components, fig.width = 10, fig.height = 7}

+ht_list = draw(ht_list, row_title = "Heatmap list", column_title = "Heatmap list", 

+    heatmap_legend_side = "right", annotation_legend_side = "left")

+decorate_annotation("points", {

+    grid.text("points", unit(0, "npc") - unit(2, "mm"), 0.5, 

+        default.units = "npc", just = "right")

+})

+

+decorate_heatmap_body("ht1", {

+    grid.text("outlier", 1.5/10, 2.5/4, default.units = "npc")

+    grid.lines(c(0.5, 0.5), c(0, 1), gp = gpar(lty = 2, lwd = 2))

+}, slice = 2)

+

+decorate_column_dend("ht1", {

+    tree = column_dend(ht_list)$ht1

+    ind = cutree(as.hclust(tree), k = 2)[order.dendrogram(tree)]

+

+    first_index = function(l) which(l)[1]

+    last_index = function(l) { x = which(l); x[length(x)] }

+    x1 = c(first_index(ind == 1), first_index(ind == 2)) - 1

+    x2 = c(last_index(ind == 1), last_index(ind == 2))

+    grid.rect(x = x1/length(ind), width = (x2 - x1)/length(ind), just = "left",

+        default.units = "npc", gp = gpar(fill = c("#FF000040", "#00FF0040"), col = NA))

+})

+

+decorate_row_names("ht2", {

+    grid.rect(gp = gpar(fill = "#FF000040"))

+}, slice = 2)

+

+decorate_row_title("ht1", {

+    grid.rect(gp = gpar(fill = "#00FF0040"))

+}, slice = 1)

+

+decorate_annotation("points", {

+    grid.lines(c(0, 1), unit(c(0, 0), "native"), gp = gpar(col = "red"))

+})

+```

+

+For annotations which are created by `anno_points()`, `anno_barplot()` and `anno_boxplot()`, "native" unit

+can be used in the decoration code.

+

+## Add annotation names

+

+By default, annotation names are not plotted along with the heatmap annotations. The reason is

+if annotation names is plotted, they will located in the area of other heatmap components which

+would makes the adjustment of the heatmap layout difficult. `HeatmapAnnotation()` provides a 

+not-so-perfect [solution](s4.heatmap_annotation.html#toc_11) for adding annotation names, however, since you can go to any component 

+in the heatmap list by its name, actually it is not difficult to add annotation names manually.

+

+Following code add annotation names on the both sides of the column annotations. The drawback is

+since there is no specific component designed for annotation names, if the annotation name is too long,

+it will be exceeding the figure region (but this problem can be solved by some tricks, see the 

+[**Examples**](s9.examples.html) vignette).

+

+```{r annotation_title}

+df = data.frame(type1 = c(rep("a", 5), rep("b", 5)),

+                type2 = c(rep("A", 3), rep("B", 7)))

+ha = HeatmapAnnotation(df, col = list(type1 = c("a" = "red", "b" = "blue"),

+                                      type2 = c("A" = "green", "B" = "orange")))

+Heatmap(mat, name = "ht", top_annotation = ha)

+for(an in colnames(df)) {

+    decorate_annotation(an, {

+        # annotation names on the right

+        grid.text(an, unit(1, "npc") + unit(2, "mm"), 0.5, default.units = "npc", just = "left")

+        # annotation names on the left

+        grid.text(an, unit(0, "npc") - unit(2, "mm"), 0.5, default.units = "npc", just = "right")

+    })

+}

+```

+

+## Visualize distributions

+

+With heatmap decorations, actually you can design new graphics based on heatmaps. Following is an example:

+

+To visualize distribution of columns in a matrix or in a list, sometimes we use boxplot or beanplot.

+Here we can also use colors to map to the density values and visualize distribution of values

+in each column (or each list element) through a heatmap. Sometimes it can give you a more clear

+image of your data.

+

+Here the package has a `densityHeatmap()` function, the usage is quite straightforward:

+

+```{r, density}

+matrix = matrix(rnorm(100), 10); colnames(matrix) = letters[1:10]

+ha = HeatmapAnnotation(df = data.frame(anno = rep(c("A", "B"), each = 5)),

+    col = list(anno = c("A" = "green", "B" = "orange")),

+    points = anno_points(runif(10)))

+densityHeatmap(matrix, anno = ha)

+```

+

+## Session info

+

+```{r}

+sessionInfo()

+```