Browse code

add anno_zoom()

Zuguang Gu authored on 12/12/2018 22:17:01
Showing4 changed files

... ...
@@ -3099,13 +3099,21 @@ anno_block = function(gp = gpar(), labels = NULL, labels_gp = gpar(), labels_rot
3099 3099
 # Zoom annotation
3100 3100
 #
3101 3101
 # == param
3102
-# -align_to
3103
-# -panel_fun
3102
+# -align_to It defines how the boxes correspond to the rows or the columns in the heatmap.
3103
+#    If the value is a list of indices, each box corresponds to the rows or columns with indices
3104
+#    in one vector in the list. If the value is a categorical variable (e.g. a factor or a character vector)
3105
+#    that has the same length as the rows or columns in the heatmap, each box corresponds to the rows/columns
3106
+#    in each level in the categorical variable.
3107
+# -panel_fun A self-defined function that defines how to draw graphics in the box. The function must have
3108
+#     a ``index`` argument which is the indices for the rows/columns that the box corresponds to. It can 
3109
+#     have second argument ``nm`` which is the "name" of the selected part in the heatmap. The corresponding
3110
+#     value for ``nm`` comes from ``align_to`` if it is specified as a categorical variable or a list with names.
3104 3111
 # -which Whether it is a column annotation or a row annotation?
3105 3112
 # -side Side of the boxes If it is a column annotation, valid values are "top" and "bottom";
3106 3113
 #       If it is a row annotation, valid values are "left" and "right".
3107
-# -size
3108
-# -gap
3114
+# -size The size of boxes. It can be pure numeric that they are treated as relative fractions of the total
3115
+#      height/width of the heatmap. The value of ``size`` can also be absolute units.
3116
+# -gap Gaps between boxes.
3109 3117
 # -link_gp Graphic settings for the segments.
3110 3118
 # -link_width Width of the segments.
3111 3119
 # -link_height Similar as ``link_width``, used for column annotation.
... ...
@@ -3116,7 +3124,26 @@ anno_block = function(gp = gpar(), labels = NULL, labels_gp = gpar(), labels_rot
3116 3124
 # -height Height of the annotation. The value should be an absolute unit. Height is not allowed to be set for row annotation.
3117 3125
 #
3118 3126
 # == details
3127
+# `anno_zoom` creates several plotting regions (boxes) which can be corresponded to subsets of rows/columns in the
3128
+# heatmap.
3119 3129
 #
3130
+# == value
3131
+# An annotation function which can be used in `HeatmapAnnotation`.
3132
+#
3133
+# == seealso
3134
+# https://jokergoo.github.io/ComplexHeatmap-reference/book/heatmap-annotations.html#zoom-annotation
3135
+#
3136
+# == example
3137
+# m = matrix(rnorm(100*10), nrow = 100)
3138
+# hc = hclust(dist(m))
3139
+# fa2 = cutree(hc, k = 4)
3140
+# panel_fun = function(index, nm) {
3141
+# 	grid.rect()
3142
+# 	grid.text(nm)
3143
+# }
3144
+# anno = anno_zoom(align_to = fa2, which = "row", panel_fun = panel_fun, 
3145
+# 	gap = unit(1, "cm"))
3146
+# Heatmap(m, cluster_rows = hc, right_annotation = rowAnnotation(foo = anno))
3120 3147
 anno_zoom = function(align_to, panel_fun = function(index, nm = NULL) { grid.rect() }, 
3121 3148
 	which = c("column", "row"), side = ifelse(which == "column", "top", "right"),
3122 3149
 	size = NULL, gap = unit(1, "mm"), 
... ...
@@ -3203,6 +3230,7 @@ anno_zoom = function(align_to, panel_fun = function(index, nm = NULL) { grid.rec
3203 3230
 		n_boxes = length(align_to)
3204 3231
 		if(length(gap) == 1) gap = rep(gap, n_boxes)
3205 3232
 		if(is.null(size)) size = nrl
3233
+		if(length(size) == 1) size = rep(size, length(align_to))
3206 3234
 		if(length(size) != length(align_to)) {
3207 3235
 			stop_wrap("Length of `size` should be the same as the number of groups of indices.")
3208 3236
 		}
... ...
@@ -3353,6 +3381,7 @@ anno_zoom = function(align_to, panel_fun = function(index, nm = NULL) { grid.rec
3353 3381
 		n_boxes = length(align_to)
3354 3382
 		if(length(gap) == 1) gap = rep(gap, n_boxes)
3355 3383
 		if(is.null(size)) size = nrl
3384
+		if(length(size) == 1) size = rep(size, length(align_to))
3356 3385
 		if(length(size) != length(align_to)) {
3357 3386
 			stop_wrap("Length of `size` should be the same as the number of groups of indices.")
3358 3387
 		}
... ...
@@ -15,12 +15,12 @@ anno_zoom(align_to, panel_fun = function(index, nm = NULL) { grid.rect() },
15 15
 }
16 16
 \arguments{
17 17
 
18
-  \item{align_to}{-align_to}
19
-  \item{panel_fun}{-panel_fun}
18
+  \item{align_to}{It defines how the boxes correspond to the rows or the columns in the heatmap. If the value is a list of indices, each box corresponds to the rows or columns with indices in one vector in the list. If the value is a categorical variable (e.g. a factor or a character vector) that has the same length as the rows or columns in the heatmap, each box corresponds to the rows/columns in each level in the categorical variable.}
19
+  \item{panel_fun}{A self-defined function that defines how to draw graphics in the box. The function must have a \code{index} argument which is the indices for the rows/columns that the box corresponds to. It can  have second argument \code{nm} which is the "name" of the selected part in the heatmap. The corresponding value for \code{nm} comes from \code{align_to} if it is specified as a categorical variable or a list with names.}
20 20
   \item{which}{Whether it is a column annotation or a row annotation?}
21 21
   \item{side}{Side of the boxes If it is a column annotation, valid values are "top" and "bottom"; If it is a row annotation, valid values are "left" and "right".}
22
-  \item{size}{-size}
23
-  \item{gap}{-gap}
22
+  \item{size}{The size of boxes. It can be pure numeric that they are treated as relative fractions of the total height/width of the heatmap. The value of \code{size} can also be absolute units.}
23
+  \item{gap}{Gaps between boxes.}
24 24
   \item{link_gp}{Graphic settings for the segments.}
25 25
   \item{link_width}{Width of the segments.}
26 26
   \item{link_height}{Similar as \code{link_width}, used for column annotation.}
... ...
@@ -30,10 +30,24 @@ anno_zoom(align_to, panel_fun = function(index, nm = NULL) { grid.rect() },
30 30
 
31 31
 }
32 32
 \details{
33
-
33
+\code{\link{anno_zoom}} creates several plotting regions (boxes) which can be corresponded to subsets of rows/columns in the
34
+heatmap.
35
+}
36
+\value{
37
+An annotation function which can be used in \code{\link{HeatmapAnnotation}}.
38
+}
39
+\seealso{
40
+\url{https://jokergoo.github.io/ComplexHeatmap-reference/book/heatmap-annotations.html#zoom-annotation}
34 41
 }
35 42
 \examples{
36
-# There is no example
37
-NULL
38
-
43
+m = matrix(rnorm(100*10), nrow = 100)
44
+hc = hclust(dist(m))
45
+fa2 = cutree(hc, k = 4)
46
+panel_fun = function(index, nm) {
47
+	grid.rect()
48
+	grid.text(nm)
49
+}
50
+anno = anno_zoom(align_to = fa2, which = "row", panel_fun = panel_fun, 
51
+	gap = unit(1, "cm"))
52
+Heatmap(m, cluster_rows = hc, right_annotation = rowAnnotation(foo = anno))
39 53
 }
... ...
@@ -17,4 +17,5 @@ default_get_type(x)
17 17
 \examples{
18 18
 # There is no example
19 19
 NULL
20
+
20 21
 }
... ...
@@ -387,6 +387,14 @@ anno = anno_zoom(align_to = fa, which = "row", panel_fun = panel_fun,
387 387
 	size = unit(c(2, 20, 40), "cm"))
388 388
 draw(anno, index = 1:100, test = "anno_zoom, big size")
389 389
 
390
+anno = anno_zoom(align_to = fa, which = "row", panel_fun = panel_fun,
391
+	size = 1:3, gap = unit(1, "cm"))
392
+draw(anno, index = 1:100, test = "anno_zoom, size set as relative values, gap")
393
+
394
+anno = anno_zoom(align_to = fa, which = "row", panel_fun = panel_fun,
395
+	size = unit(1:3, "cm"), gap = unit(1, "cm"))
396
+draw(anno, index = 1:100, test = "anno_zoom, size set as absolute values, gap")
397
+
390 398
 
391 399
 anno = anno_zoom(align_to = fa, which = "row", panel_fun = panel_fun,
392 400
 	size = unit(1:3, "cm"), side = "left")
... ...
@@ -426,6 +434,8 @@ Heatmap(m, cluster_rows = hc, right_annotation = rowAnnotation(foo = anno))
426 434
 Heatmap(m, cluster_rows = hc, right_annotation = rowAnnotation(foo = anno), row_split = 2)
427 435
 
428 436
 
437
+anno = anno_zoom(align_to = fa2, which = "row", panel_fun = panel_fun, size = unit(1:4, "cm"))
438
+Heatmap(m, cluster_rows = hc, right_annotation = rowAnnotation(foo = anno))
429 439
 
430 440
 
431 441