Browse code

pass width to AnnotationFunction

jokergoo authored on 22/10/2018 12:26:03
Showing6 changed files

... ...
@@ -3,14 +3,13 @@
3 3
 # The AnnotationFunction Class
4 4
 #
5 5
 # == details
6
-# The heatmap annotation is basically graphics aligned to the heatmap columns
7
-# if it is column annotation or heatmap rows if it is row annotation, while
8
-# there is no restrictions for the graphic types, e.g. it can be heatmap-like
6
+# The heatmap annotation is basically graphics aligned to the heatmap columns or rows.
7
+# There is no restriction for the graphic types, e.g. it can be heatmap-like
9 8
 # annotation or points. Here the AnnotationFunction class is designed for
10 9
 # creating complex and flexible annotation graphics. As the main part of the class, it uses
11 10
 # a user-defined function to define the graphics. It also keeps information of
12 11
 # the size of the plotting regions of the annotation. And most importantly, it
13
-# allows subsetting of the annotation to draw a subset of the graphics, which
12
+# allows subsetting to the annotation to draw a subset of the graphics, which
14 13
 # is the base for the splitting of the annotations.
15 14
 #
16 15
 # See `AnnotationFunction` constructor for details.
... ...
@@ -108,96 +107,37 @@ anno_width_and_height = function(which, width = NULL, height = NULL,
108 107
 #        the width must be an absolute unit.
109 108
 #
110 109
 # == details
111
-# We use a normal R function defines how to draw the annotation graphics. As
112
-# expected, the main part of the AnnotationFunction class is this function.
113
-# The function defines how to draw at specific positions which correspond to
114
-# rows or columns in the heatmap. The function should have three arguments:
115
-# ``index``, ``k`` and ``n`` (the names of the arguments can be arbitory)
116
-# where ``k`` and ``n`` are optional. ``index`` corresponds to the indices of
117
-# rows or columns of the heatmap. The value of ``index`` is not necessarily to
118
-# be the whole row indices or column indices of the heatmap. It can be a
119
-# subset of the indices if the annotation is split into slices according to
120
-# the split of the heatmap. ``index`` is always reordered according to the
121
-# reordering of heatmap rows or columns (e.g. by clustering). So, ``index``
122
-# actually contains a list of row or column indices for the current slice
123
-# after row or column reordering.
124
-# 
125
-# As mentioned, annotation can be split into slices. ``k`` corresponds to the
126
-# current slice and ``n`` corresponds to the total number of slices. As you can image, 
127
-# when ``n > 1``, the annotation function will be executed for all ``k``s. The
128
-# information of ``k`` and ``n`` sometimes can be useful, for example, we want
129
-# to add axis ot the right side of a column annotation, if this column annotation
130
-# is split into several slices, the axis is only drawn when``k == n``.
131
-#
132
-# Since the function only allows ``index``, ``k`` and ``n``, the function
133
-# sometimes uses several external variables which can not be defined inside
134
-# the function, e.g. the data points for the annotation. These variables
135
-# should be imported into the AnnotationFunction class so that the function
136
-# can correctly find these variables (by ``var_import`` argument).
137
-#
138
-# One important feature for AnnotationFunction class is it can be subsetable.
139
-# To allow subsetting of the object, users need to define the rules for the
140
-# imported variables. The rules are simple function which
141
-# accpets the variable and indices, and returns the subset of the variable.
142
-# The subset rule functions implemented in this package are `subset_gp`,
143
-# `subset_matrix_by_row` and `subset_vector`. These three functions are enough
144
-# for most of the cases.
145
-#
146
-# In following, we defined three AnnotationFunction objects: 
147
-#
148
-# 1. It needs external variable and support subsetting
149
-#
150
-#	x = 1:10
151
-#	anno1 = AnnotationFunction(
152
-#		fun = function(index) {
153
-#			n = length(index)
154
-#			pushViewport(viewport())
155
-#			grid.points(1:n, x[index])
156
-#			popViewport()
157
-#		},
158
-#		var_imported = list(x = x),
159
-#		n = 10,
160
-#		subset_rule = list(x = subset_vector),
161
-#		subsetable = TRUE
162
-#	)
163
-#
164
-# 2. The data variable is defined inside the function and no need to import other variables.
165
-#
166
-#	anno2 = AnnotationFunction(
167
-#		fun = function(index) {
168
-#			x = 1:10
169
-#			n = length(index)
170
-#			pushViewport(viewport())
171
-#			grid.points(1:n, x[index])
172
-#			popViewport()
173
-#		},
174
-#		n = 10,
175
-#		subsetable = TRUE
176
-#	)
177
-#
178
-# 3. Only specify the function to the constructor. ``anno3`` is not subsettable.
179
-#
180
-#	anno3 = AnnotationFunction(
181
-#		fun = function(index) {
182
-#			x = 1:10
183
-#			n = length(index)
184
-#			pushViewport(viewport())
185
-#			grid.points(1:n, x[index])
186
-#			popViewport()
187
-#		}
188
-#	)
189
-#
190
-# As you can see from the examples, you need to push a viewport for graphics and finally pop the viewport.
191
-#
192
-# In the package, we have implemted quite a lot annotation function by `AnnotationFunction` constructor:
110
+# In the package, we have implemted quite a lot annotation functions by `AnnotationFunction` constructor:
193 111
 # `anno_empty`, `anno_image`, `anno_points`, `anno_lines`, `anno_barplot`, `anno_boxplot`, `anno_histogram`,
194 112
 # `anno_density`, `anno_joyplot`, `anno_horizon`, `anno_text` and `anno_mark`. These built-in annotation functions
195 113
 # support as both row annotations and column annotations and they are are all subsettable.
196 114
 #
197
-# == seealso
198 115
 # The build-in annotation functions are already enough for most of the analysis, nevertheless, if users
199 116
 # want to know more about how to construct the AnnotationFunction class manually, they can refer to
200
-# ComplexHeatmap Complete Reference ().
117
+# https://jokergoo.github.io/ComplexHeatmap-reference/book/heatmap-annotations.html#implement-new-annotation-functions.
118
+#
119
+# == value
120
+# A `AnnotationFunction-class` object which can be used in `HeatmapAnnotation`.
121
+#
122
+# == example
123
+# x = 1:10
124
+# anno1 = AnnotationFunction(
125
+#     fun = function(index, k, n) {
126
+#         n = length(index)
127
+#         pushViewport(viewport(xscale = c(0.5, n + 0.5), yscale = c(0, 10)))
128
+#         grid.rect()
129
+#         grid.points(1:n, x[index], default.units = "native")
130
+#         if(k == 1) grid.yaxis()
131
+#         popViewport()
132
+#     },
133
+#     var_import = list(x = x),
134
+#     n = 10,
135
+#     subsetable = TRUE,
136
+#     height = unit(2, "cm")
137
+# )
138
+# m = rbind(1:10, 11:20)
139
+# Heatmap(m, top_annotation = HeatmapAnnotation(foo = anno1))
140
+# Heatmap(m, top_annotation = HeatmapAnnotation(foo = anno1), column_km = 2)
201 141
 AnnotationFunction = function(fun, fun_name = "", which = c("column", "row"), 
202 142
 	var_import = list(), n = NA, data_scale = c(0, 1), subset_rule = list(), 
203 143
 	subsetable = length(subset_rule) > 0, show_name = TRUE, width = NULL, height = NULL) {
... ...
@@ -325,12 +265,12 @@ AnnotationFunction = function(fun, fun_name = "", which = c("column", "row"),
325 265
 # == param
326 266
 # -object The `AnnotationFunction-class` object.
327 267
 # -index Index of observations.
328
-# -k Current index of slice.
268
+# -k Current slice index.
329 269
 # -n Total number of slices.
330 270
 # -test Is it in test mode? The value can be logical or a text which is plotted as the title of plot.
331 271
 #
332 272
 # == detail
333
-# Normally it is called internally by the `SingleAnnotation` class.
273
+# Normally it is called internally by the `SingleAnnotation-class`.
334 274
 #
335 275
 # When ``test`` is set to ``TRUE``, the annotation graphic is directly drawn,
336 276
 # which is generally for testing purpose.
... ...
@@ -404,7 +344,7 @@ setMethod(f = "draw",
404 344
 # == detail 
405 345
 # In `AnnotationFunction-class`, there is an environment which
406 346
 # stores some external variables for the annotation function (specified by the
407
-# ``var_import`` argument by constructing the `AnnotationFunction-class`
347
+# ``var_import`` argument when constructing the `AnnotationFunction-class`
408 348
 # object. This `copy_all,AnnotationFunction-method` hard copies all the
409 349
 # variables into a new isolated environment.
410 350
 #
... ...
@@ -1,4 +1,3 @@
1
-# -anno_simple_size size of the simple annotation.# -anno_simple_size size of the simple annotation.# -anno_simple_size size of the simple annotation.
2 1
 
3 2
 # == title
4 3
 # Empty Annotation
... ...
@@ -35,6 +34,9 @@
35 34
 # == value
36 35
 # An annotation function which can be used in `HeatmapAnnotation`.
37 36
 #
37
+# == seealso
38
+# https://jokergoo.github.io/ComplexHeatmap-reference/book/heatmap-annotations.html#empty-annotation
39
+#
38 40
 # == examples
39 41
 # anno = anno_empty()
40 42
 # draw(anno, test = "anno_empty")
... ...
@@ -73,17 +75,23 @@ anno_empty = function(which = c("column", "row"), border = TRUE, width = NULL, h
73 75
 # Subset the Matrix by Rows
74 76
 #
75 77
 # == param
76
-# -x A matrix
78
+# -x A matrix.
77 79
 # -i The row indices.
78 80
 #
81
+# == details
82
+# Mainly used for constructing the `AnnotationFunction-class` object.
83
+#
79 84
 subset_matrix_by_row = function(x, i) x[i, , drop = FALSE]
80 85
 
81 86
 # == title
82 87
 # Subset the vector
83 88
 #
84 89
 # == param
85
-# -x A vector
86
-# -i The indices
90
+# -x A vector.
91
+# -i The indices.
92
+#
93
+# == details
94
+# Mainly used for constructing the `AnnotationFunction-class` object.
87 95
 #
88 96
 subset_vector = function(x, i) x[i]
89 97
 
... ...
@@ -124,6 +132,9 @@ subset_vector = function(x, i) x[i]
124 132
 # == value
125 133
 # An annotation function which can be used in `HeatmapAnnotation`.
126 134
 #
135
+# == seealso
136
+# https://jokergoo.github.io/ComplexHeatmap-reference/book/heatmap-annotations.html#simple-annotation-as-an-annotation-function
137
+#
127 138
 # == example
128 139
 # anno = anno_simple(1:10)
129 140
 # draw(anno, test = "a numeric vector")
... ...
@@ -329,6 +340,9 @@ anno_simple = function(x, col, na_col = "grey",
329 340
 # == value
330 341
 # An annotation function which can be used in `HeatmapAnnotation`.
331 342
 #
343
+# == seealso
344
+# https://jokergoo.github.io/ComplexHeatmap-reference/book/heatmap-annotations.html#image-annotation
345
+#
332 346
 # == example
333 347
 # # download the free icons from https://github.com/Keyamoon/IcoMoon-Free
334 348
 # \dontrun{
... ...
@@ -604,6 +618,9 @@ construct_axis_grob = function(axis_param, which, data_scale) {
604 618
 # == value
605 619
 # An annotation function which can be used in `HeatmapAnnotation`.
606 620
 #
621
+# == seealso
622
+# https://jokergoo.github.io/ComplexHeatmap-reference/book/heatmap-annotations.html#points-annotation
623
+#
607 624
 # == example
608 625
 # anno = anno_points(runif(10))
609 626
 # draw(anno, test = "anno_points")
... ...
@@ -781,6 +798,9 @@ update_anno_extend = function(anno, axis_grob, axis_param) {
781 798
 # == value
782 799
 # An annotation function which can be used in `HeatmapAnnotation`.
783 800
 #
801
+# == seealso
802
+# https://jokergoo.github.io/ComplexHeatmap-reference/book/heatmap-annotations.html#lines-annotation
803
+#
784 804
 # == example
785 805
 # anno = anno_lines(runif(10))
786 806
 # draw(anno, test = "anno_lines")
... ...
@@ -998,6 +1018,9 @@ anno_lines = function(x, which = c("column", "row"), border = TRUE, gp = gpar(),
998 1018
 # == value
999 1019
 # An annotation function which can be used in `HeatmapAnnotation`.
1000 1020
 #
1021
+# == seealso
1022
+# https://jokergoo.github.io/ComplexHeatmap-reference/book/heatmap-annotations.html#barplot_annotation
1023
+#
1001 1024
 # == example
1002 1025
 # anno = anno_barplot(1:10)
1003 1026
 # draw(anno, test = "a vector")
... ...
@@ -1168,6 +1191,9 @@ anno_barplot = function(x, baseline = 0, which = c("column", "row"), border = TR
1168 1191
 # == value
1169 1192
 # An annotation function which can be used in `HeatmapAnnotation`.
1170 1193
 #
1194
+# == seealso
1195
+# https://jokergoo.github.io/ComplexHeatmap-reference/book/heatmap-annotations.html#box-annotation
1196
+#
1171 1197
 # == example
1172 1198
 # set.seed(123)
1173 1199
 # m = matrix(rnorm(100), 10)
... ...
@@ -1364,6 +1390,9 @@ anno_boxplot = function(x, which = c("column", "row"), border = TRUE,
1364 1390
 # == value
1365 1391
 # An annotation function which can be used in `HeatmapAnnotation`.
1366 1392
 #
1393
+# == seealso
1394
+# https://jokergoo.github.io/ComplexHeatmap-reference/book/heatmap-annotations.html#histogram-annotation
1395
+#
1367 1396
 # == example
1368 1397
 # m = matrix(rnorm(1000), nc = 10)
1369 1398
 # anno = anno_histogram(t(m), which = "row")
... ...
@@ -1522,6 +1551,9 @@ anno_histogram = function(x, which = c("column", "row"), n_breaks = 11,
1522 1551
 # == value
1523 1552
 # An annotation function which can be used in `HeatmapAnnotation`.
1524 1553
 #
1554
+# == seealso
1555
+# https://jokergoo.github.io/ComplexHeatmap-reference/book/heatmap-annotations.html#density-annotation
1556
+#
1525 1557
 # == example
1526 1558
 # m = matrix(rnorm(100), 10)
1527 1559
 # anno = anno_density(m, which = "row")
... ...
@@ -1777,6 +1809,9 @@ anno_density = function(x, which = c("column", "row"),
1777 1809
 # == value
1778 1810
 # An annotation function which can be used in `HeatmapAnnotation`.
1779 1811
 #
1812
+# == seealso
1813
+# https://jokergoo.github.io/ComplexHeatmap-reference/book/heatmap-annotations.html#text-annotation
1814
+#
1780 1815
 # == example
1781 1816
 # anno = anno_text(month.name)
1782 1817
 # draw(anno, test = "month names")
... ...
@@ -1921,6 +1956,9 @@ anno_text = function(x, which = c("column", "row"), gp = gpar(),
1921 1956
 # == value
1922 1957
 # An annotation function which can be used in `HeatmapAnnotation`.
1923 1958
 #
1959
+# == seealso
1960
+# https://jokergoo.github.io/ComplexHeatmap-reference/book/heatmap-annotations.html#joyplot-annotation
1961
+#
1924 1962
 # == example
1925 1963
 # m = matrix(rnorm(1000), nc = 10)
1926 1964
 # lt = apply(m, 2, function(x) data.frame(density(x)[c("x", "y")]))
... ...
@@ -2111,6 +2149,9 @@ anno_joyplot = function(x, which = c("column", "row"), gp = gpar(fill = "#000000
2111 2149
 # == value
2112 2150
 # An annotation function which can be used in `HeatmapAnnotation`.
2113 2151
 #
2152
+# == seealso
2153
+# https://jokergoo.github.io/ComplexHeatmap-reference/book/heatmap-annotations.html#horizon-chart-annotation
2154
+#
2114 2155
 # == example
2115 2156
 # lt = lapply(1:20, function(x) cumprod(1 + runif(1000, -x/100, x/100)) - 1)
2116 2157
 # anno = anno_horizon(lt, which = "row")
... ...
@@ -2342,7 +2383,7 @@ split_vec_by_NA = function(x) {
2342 2383
 # Points as Row Annotation
2343 2384
 #
2344 2385
 # == param
2345
-# -... pass to `anno_points`
2386
+# -... pass to `anno_points`.
2346 2387
 #
2347 2388
 # == details
2348 2389
 # A wrapper of `anno_points` with pre-defined ``which`` to ``row``.
... ...
@@ -2350,11 +2391,11 @@ split_vec_by_NA = function(x) {
2350 2391
 # You can directly use `anno_points` for row annotation if you call it in `rowAnnotation`.
2351 2392
 #
2352 2393
 # == value
2353
-# See help page of `anno_points`
2394
+# See help page of `anno_points`.
2354 2395
 #
2355 2396
 row_anno_points = function(...) {
2356 2397
 	if(exists(".__under_SingleAnnotation__", envir = parent.frame())) {
2357
-		message_wrap("From this version of ComplexHeatmap, you can directly use `anno_points()` for row annotation if you call it in `rowAnnotation()`.")
2398
+		message_wrap("From version 1.99.0, you can directly use `anno_points()` for row annotation if you call it in `rowAnnotation()`.")
2358 2399
 	}
2359 2400
 	anno_points(..., which = "row")
2360 2401
 }
... ...
@@ -2364,7 +2405,7 @@ row_anno_points = function(...) {
2364 2405
 # Barplots as Row Annotation
2365 2406
 #
2366 2407
 # == param
2367
-# -... pass to `anno_barplot`
2408
+# -... pass to `anno_barplot`.
2368 2409
 #
2369 2410
 # == details
2370 2411
 # A wrapper of `anno_barplot` with pre-defined ``which`` to ``row``.
... ...
@@ -2372,11 +2413,11 @@ row_anno_points = function(...) {
2372 2413
 # You can directly use `anno_barplot` for row annotation if you call it in `rowAnnotation`.
2373 2414
 #
2374 2415
 # == value
2375
-# See help page of `anno_barplot`
2416
+# See help page of `anno_barplot`.
2376 2417
 #
2377 2418
 row_anno_barplot = function(...) {
2378 2419
 	if(exists(".__under_SingleAnnotation__", envir = parent.frame())) {
2379
-		message_wrap("From this version of ComplexHeatmap, you can directly use `anno_barplot()` for row annotation if you call it in `rowAnnotation()`.")
2420
+		message_wrap("From version 1.99.0, you can directly use `anno_barplot()` for row annotation if you call it in `rowAnnotation()`.")
2380 2421
 	}
2381 2422
 	anno_barplot(..., which = "row")
2382 2423
 }
... ...
@@ -2386,7 +2427,7 @@ row_anno_barplot = function(...) {
2386 2427
 # Boxplots as Row Annotation
2387 2428
 #
2388 2429
 # == param
2389
-# -... pass to `anno_boxplot`
2430
+# -... pass to `anno_boxplot`.
2390 2431
 #
2391 2432
 # == details
2392 2433
 # A wrapper of `anno_boxplot` with pre-defined ``which`` to ``row``.
... ...
@@ -2394,11 +2435,11 @@ row_anno_barplot = function(...) {
2394 2435
 # You can directly use `anno_boxplot` for row annotation if you call it in `rowAnnotation`.
2395 2436
 #
2396 2437
 # == value
2397
-# See help page of `anno_boxplot`
2438
+# See help page of `anno_boxplot`.
2398 2439
 #
2399 2440
 row_anno_boxplot = function(...) {
2400 2441
 	if(exists(".__under_SingleAnnotation__", envir = parent.frame())) {
2401
-		message_wrap("From this version of ComplexHeatmap, you can directly use `anno_boxplot()` for row annotation if you call it in `rowAnnotation()`.")
2442
+		message_wrap("From version 1.99.0, you can directly use `anno_boxplot()` for row annotation if you call it in `rowAnnotation()`.")
2402 2443
 	}
2403 2444
 	anno_boxplot(..., which = "row")
2404 2445
 }
... ...
@@ -2407,7 +2448,7 @@ row_anno_boxplot = function(...) {
2407 2448
 # Histograms as Row Annotation
2408 2449
 #
2409 2450
 # == param
2410
-# -... pass to `anno_histogram`
2451
+# -... pass to `anno_histogram`.
2411 2452
 #
2412 2453
 # == details
2413 2454
 # A wrapper of `anno_histogram` with pre-defined ``which`` to ``row``.
... ...
@@ -2415,11 +2456,11 @@ row_anno_boxplot = function(...) {
2415 2456
 # You can directly use `anno_histogram` for row annotation if you call it in `rowAnnotation`.
2416 2457
 #
2417 2458
 # == value
2418
-# See help page of `anno_histogram`
2459
+# See help page of `anno_histogram`.
2419 2460
 #
2420 2461
 row_anno_histogram = function(...) {
2421 2462
 	if(exists(".__under_SingleAnnotation__", envir = parent.frame())) {
2422
-		message_wrap("From this version of ComplexHeatmap, you can directly use `anno_histogram()` for row annotation if you call it in `rowAnnotation()`.")
2463
+		message_wrap("From version 1.99.0, you can directly use `anno_histogram()` for row annotation if you call it in `rowAnnotation()`.")
2423 2464
 	}
2424 2465
 	anno_histogram(..., which = "row")
2425 2466
 }
... ...
@@ -2428,7 +2469,7 @@ row_anno_histogram = function(...) {
2428 2469
 # Density as Row Annotation
2429 2470
 #
2430 2471
 # == param
2431
-# -... pass to `anno_density`
2472
+# -... pass to `anno_density`.
2432 2473
 #
2433 2474
 # == details
2434 2475
 # A wrapper of `anno_density` with pre-defined ``which`` to ``row``.
... ...
@@ -2436,11 +2477,11 @@ row_anno_histogram = function(...) {
2436 2477
 # You can directly use `anno_density` for row annotation if you call it in `rowAnnotation`.
2437 2478
 #
2438 2479
 # == value
2439
-# See help page of `anno_density`
2480
+# See help page of `anno_density`.
2440 2481
 #
2441 2482
 row_anno_density = function(...) {
2442 2483
 	if(exists(".__under_SingleAnnotation__", envir = parent.frame())) {
2443
-		message_wrap("From this version of ComplexHeatmap, you can directly use `anno_density()` for row annotation if you call it in `rowAnnotation()`.")
2484
+		message_wrap("From version 1.99.0, you can directly use `anno_density()` for row annotation if you call it in `rowAnnotation()`.")
2444 2485
 	}
2445 2486
 	anno_density(..., which = "row")
2446 2487
 }
... ...
@@ -2449,7 +2490,7 @@ row_anno_density = function(...) {
2449 2490
 # Text as Row Annotation
2450 2491
 #
2451 2492
 # == param
2452
-# -... pass to `anno_text`
2493
+# -... pass to `anno_text`.
2453 2494
 #
2454 2495
 # == details
2455 2496
 # A wrapper of `anno_text` with pre-defined ``which`` to ``row``.
... ...
@@ -2457,11 +2498,11 @@ row_anno_density = function(...) {
2457 2498
 # You can directly use `anno_text` for row annotation if you call it in `rowAnnotation`.
2458 2499
 #
2459 2500
 # == value
2460
-# See help page of `anno_text`
2501
+# See help page of `anno_text`.
2461 2502
 #
2462 2503
 row_anno_text = function(...) {
2463 2504
 	if(exists(".__under_SingleAnnotation__", envir = parent.frame())) {
2464
-		message_wrap("From this version of ComplexHeatmap, you can directly use `anno_text()` for row annotation if you call it in `rowAnnotation()`.")
2505
+		message_wrap("From version 1.99.0, you can directly use `anno_text()` for row annotation if you call it in `rowAnnotation()`.")
2465 2506
 	}
2466 2507
 	anno_text(..., which = "row")
2467 2508
 }
... ...
@@ -2492,6 +2533,9 @@ row_anno_text = function(...) {
2492 2533
 # == value
2493 2534
 # An annotation function which can be used in `HeatmapAnnotation`.
2494 2535
 #
2536
+# == seealso
2537
+# https://jokergoo.github.io/ComplexHeatmap-reference/book/heatmap-annotations.html#mark-annotation
2538
+#
2495 2539
 # == example
2496 2540
 # anno = anno_mark(at = c(1:4, 20, 60, 97:100), labels = month.name[1:10], which = "row")
2497 2541
 # draw(anno, index = 1:100, test = "anno_mark")
... ...
@@ -2663,7 +2707,7 @@ anno_link = function(...) {
2663 2707
 # Label Markers as Row Annotation
2664 2708
 #
2665 2709
 # == param
2666
-# -... pass to `anno_link`
2710
+# -... pass to `anno_link`.
2667 2711
 #
2668 2712
 # == details
2669 2713
 # A wrapper of `anno_link` with pre-defined ``which`` to ``row``.
... ...
@@ -2671,11 +2715,11 @@ anno_link = function(...) {
2671 2715
 # You can directly use `anno_link` for row annotation if you call it in `rowAnnotation`.
2672 2716
 #
2673 2717
 # == value
2674
-# See help page of `anno_link`
2718
+# See help page of `anno_link`.
2675 2719
 #
2676 2720
 row_anno_link = function(...) {
2677 2721
 	if(exists(".__under_SingleAnnotation__", envir = parent.frame())) {
2678
-		message_wrap("From this version of ComplexHeatmap, you can directly use `anno_mark()` for row annotation if you call it in `rowAnnotation()`.")
2722
+		message_wrap("From version 1.99.0, you can directly use `anno_mark()` for row annotation if you call it in `rowAnnotation()`.")
2679 2723
 	}
2680 2724
 	anno_link(..., which = "row")
2681 2725
 }
... ...
@@ -2708,6 +2752,12 @@ row_anno_link = function(...) {
2708 2752
 # In the barplot, the color schema is used as the same as the heatmap, while for the boxplot, the color needs
2709 2753
 # to be controlled by ``gp``.
2710 2754
 #
2755
+# == value
2756
+# An annotation function which can be used in `HeatmapAnnotation`.
2757
+#
2758
+# == seealso
2759
+# https://jokergoo.github.io/ComplexHeatmap-reference/book/heatmap-annotations.html#summary-annotation
2760
+#
2711 2761
 # == example
2712 2762
 # ha = HeatmapAnnotation(summary = anno_summary(height = unit(4, "cm")))
2713 2763
 # v = sample(letters[1:2], 50, replace = TRUE)
... ...
@@ -2851,14 +2901,31 @@ anno_summary = function(which = c("column", "row"), border = TRUE, bar_width = 0
2851 2901
 # Block annotation
2852 2902
 #
2853 2903
 # == param
2854
-# -gp Graphic parameters
2855
-# -labels
2856
-# -labels_gp
2857
-# -labels_rot
2858
-# -which
2859
-# -width
2860
-# -height
2904
+# -gp Graphic parameters.
2905
+# -labels Labels put on blocks.
2906
+# -labels_gp Graphic parameters for labels.
2907
+# -labels_rot Rotation for labels.
2908
+# -which Is it a row annotation or a column annotation?
2909
+# -width Width of the annotation. The value should be an absolute unit. Width is not allowed to be set for column annotation.
2910
+# -height Height of the annotation. The value should be an absolute unit. Height is not allowed to be set for row annotation.
2861 2911
 #
2912
+# == details
2913
+# The block annotation is used for representing slices. The length of all arguments should be 1 or the number of slices.
2914
+#
2915
+# == value
2916
+# An annotation function which can be used in `HeatmapAnnotation`.
2917
+#
2918
+# == seealso
2919
+# https://jokergoo.github.io/ComplexHeatmap-reference/book/heatmap-annotations.html#block-annotation
2920
+#
2921
+# == example
2922
+# Heatmap(matrix(rnorm(100), 10), 
2923
+#     top_annotation = HeatmapAnnotation(foo = anno_block(gp = gpar(fill = 2:4),
2924
+#         labels = c("group1", "group2", "group3"), labels_gp = gpar(col = "white"))),
2925
+#     column_km = 3,
2926
+#     left_annotation = rowAnnotation(foo = anno_block(gp = gpar(fill = 2:4),
2927
+#         labels = c("group1", "group2", "group3"), labels_gp = gpar(col = "white"))),
2928
+#     row_km = 3)
2862 2929
 anno_block = function(gp = gpar(), labels = NULL, labels_gp = gpar(), labels_rot = ifelse(which == "row", 90, 0),
2863 2930
 	which = c("column", "row"), width = NULL, height = NULL) {
2864 2931
 
... ...
@@ -375,7 +375,9 @@ HeatmapAnnotation = function(...,
375 375
     } else if(which == "row") {
376 376
 
377 377
 		anno_size = do.call("unit.c", lapply(anno_list, width))
378
-		width = sum(anno_size) + sum(gap) - gap[n_total_anno]
378
+		if(is.null(width)) {
379
+			width = sum(anno_size) + sum(gap) - gap[n_total_anno]
380
+		}
379 381
     	
380 382
     	if(is.null(height)) {
381 383
     		height = unit(1, "npc")
... ...
@@ -234,7 +234,7 @@ SingleAnnotation = function(name, value, col, fun,
234 234
 
235 235
             if(!fun@show_name) show_name = fun@show_name
236 236
         } else {
237
-            fun = AnnotationFunction(fun = fun)
237
+            fun = AnnotationFunction(fun = fun, which = which)
238 238
             anno_fun_extend = fun@extended
239 239
             if(verbose) qqcat("@{name}: annotation is a user-defined function\n")
240 240
         }
... ...
@@ -10,22 +10,23 @@
10 10
 # -ylab Label on y-axis.
11 11
 # -column_title Title of the heatmap.
12 12
 # -title Same as ``column_title``.
13
-# -ylim Ranges on the y-axis. By default the range is between 1th quantile and 99th quantile of the data.
13
+# -ylim Ranges on the y-axis.
14 14
 # -range Same as ``ylim``.
15
-# -title_gp = gpar(fontsize = 14),
16
-# -ylab_gp = gpar(fontsize = 12),
17
-# -tick_label_gp = gpar(fontsize = 10),
18
-# -quantile_gp = gpar(fontsize = 10),
19
-# -column_order column_order
15
+# -title_gp Graphic parameters for title.
16
+# -ylab_gp Graphic parameters for y-labels.
17
+# -tick_label_gp Graphic parameters for y-ticks.
18
+# -quantile_gp Graphic parameters for the quantiles.
19
+# -column_order Order of columns.
20 20
 # -column_names_side Pass to `Heatmap`.
21 21
 # -show_column_names Pass to `Heatmap`.
22 22
 # -column_names_max_height Pass to `Heatmap`.
23 23
 # -column_names_gp Pass to `Heatmap`.
24 24
 # -column_names_rot Pass to `Heatmap`.
25
-# -cluster_columns Whether cluster columns (here clustered by density values)? Normally we don't cluster columns.
26
-# -clustering_distance_columns
27
-# -clustering_method_columns
28
-# -... pass to `Heatmap`.
25
+# -cluster_columns Whether cluster columns?
26
+# -clustering_distance_columns There is a specific distance method ``ks`` which is the Kolmogorov-Smirnov statistic between two distributions.
27
+#          For other methods, the distance is calculated on the density matrix.
28
+# -clustering_method_columns Pass to `Heatmap`.
29
+# -... Pass to `Heatmap`.
29 30
 #
30 31
 # == details
31 32
 # To visualize data distribution in a matrix or in a list, we normally use
... ...
@@ -34,12 +35,13 @@
34 35
 # huge number of columns in ``data`` to visualize.
35 36
 #
36 37
 # The density matrix is generated with 500 rows ranging between the maximun
37
-# and minimal values in all densities. The density values in each row are
38
-# linearly intepolated between the two density values at the two nearest
39
-# bounds.
38
+# and minimal values in all densities. 
40 39
 #
41 40
 # == value
42
-# A `HeatmapList-class` object with only one heatmap, but it can only add other heatmaps/annotations vertically.
41
+# A `Heatmap-class` object. It can oly add other heatmaps/annotations vertically.
42
+#
43
+# == seealso
44
+# https://jokergoo.github.io/ComplexHeatmap-reference/book/other-high-level-plots.html#density-heatmap
43 45
 #
44 46
 # == author
45 47
 # Zuguang Gu <z.gu@dkfz.de>
... ...
@@ -89,7 +91,7 @@ densityHeatmap = function(data,
89 91
 		if(any(c("row_km", "row_split", "split", "km") %in% names(arg_list))) {
90 92
 			stop_wrap("density heatmaps do not allow row splitting.")
91 93
 		}
92
-		if(grepl("row", names(arg_list))) {
94
+		if(any(grepl("row", names(arg_list)))) {
93 95
 			stop_wrap("density heatmaps do not allow to set rows.")
94 96
 		}
95 97
 	}
... ...
@@ -3,8 +3,9 @@
3 3
 # The Class for Legends
4 4
 #
5 5
 # == details
6
-# This is a very simple class for legends that it only has one slot which is the real `grid::grob` of the legends.
7
-# more information of the legends grob.
6
+# This is a very simple class for legends that it only has one slot which is the real `grid::grob` of the legends. 
7
+#
8
+# Construct a single legend by `Legend` and a group of legends by `packLegend`.
8 9
 # 
9 10
 # == example
10 11
 # lgd = Legend(at = 1:4)
... ...
@@ -22,7 +23,7 @@ Legends = setClass("Legends",
22 23
 # Constructor method for Legends class
23 24
 #
24 25
 # == param
25
-# -... arguments
26
+# -... arguments.
26 27
 #
27 28
 # == details
28 29
 # There is no public constructor method for the `Legends-class`.
... ...
@@ -73,11 +74,14 @@ Legends = function(...) {
73 74
 #     horizontal legend.
74 75
 #
75 76
 # == details
76
-# The ``Legend`` function supports very flexible legend settings. Please go to ...
77
+# Most of the argument can also be set in ``heatmap_legend_param`` argument in `Heatmap` or ``annotation_legend_param``
78
+# argument in `HeatmapAnnotation` to configure legend styles for heatmap and annotations.
77 79
 #
78 80
 # == seealso
79 81
 # `packLegend` packs multiple legends into one `Legends-class` object.
80 82
 #
83
+# See examples of configuring legends: https://jokergoo.github.io/ComplexHeatmap-reference/book/legends.html
84
+#
81 85
 # == value
82 86
 # A `Legends-class` object.
83 87
 #
... ...
@@ -741,13 +745,16 @@ horizontal_continuous_legend_body = function(at, labels = at, col_fun,
741 745
 # -column_gap Vertical gaps between legends.
742 746
 # -direction The direction to arrange legends.
743 747
 # -max_width The maximal width of the total packed legends. It only works for horizontal arrangement.
744
-#           If the total width of the legends exceeds it, the legends will be arranged into several rows.
748
+#           If the total width of the legends exceeds it, the legends will be arranged into multiple rows.
745 749
 # -max_height Similar as ``max_width``, but for the vertical arrangment of legends.
746 750
 # -list The list of legends can be specified as a list.
747 751
 #
748 752
 # == value
749 753
 # A `Legends-class` object.
750 754
 #
755
+# == seealso
756
+# https://jokergoo.github.io/ComplexHeatmap-reference/book/legends.html#a-list-of-legends
757
+#
751 758
 # == example
752 759
 # require(circlize)
753 760
 # col_fun = colorRamp2(c(0, 0.5, 1), c("blue", "white", "red"))
... ...
@@ -1012,6 +1019,8 @@ valid_just = function(just) {
1012 1019
 # -test Only used for testing.
1013 1020
 #
1014 1021
 # == details
1022
+# In the legend grob, there should always be a viewport attached which is like a wrapper of 
1023
+# all the graphic elements in a legend.
1015 1024
 # If in the ``object``, there is already a viewport attached, it will modify the ``x``, ``y``
1016 1025
 # and ``valid.just`` of the viewport. If there is not viewport attached, a viewport
1017 1026
 # with specified ``x``, ``y`` and ``valid.just`` is created and attached.
... ...
@@ -1023,6 +1032,11 @@ valid_just = function(just) {
1023 1032
 # == example
1024 1033
 # lgd = Legend(at = 1:4, title = "foo")
1025 1034
 # draw(lgd, x = unit(0, "npc"), y = unit(0, "npc"), just = c("left", "bottom"))
1035
+#
1036
+# # and a similar version of grid.draw
1037
+# pushViewport(viewport(x = unit(0, "npc"), y = unit(0, "npc"), just = c("left", "bottom")))
1038
+# grid.draw(lgd)
1039
+# popViewport()
1026 1040
 setMethod(f = "draw",
1027 1041
 	signature = "Legends",
1028 1042
 	definition = function(object, x = unit(0.5, "npc"), y = unit(0.5, "npc"), just = "centre", test = FALSE) {
... ...
@@ -1058,6 +1072,11 @@ setMethod(f = "draw",
1058 1072
 # == details
1059 1073
 # This function is actually an S3 method of the ``Legends`` class for the `grid::grid.draw`
1060 1074
 # general method. It applies `grid::grid.draw` on the ``grob`` slot of the object.
1075
+#
1076
+# == example
1077
+# pushViewport(viewport(x = unit(0, "npc"), y = unit(0, "npc"), just = c("left", "bottom")))
1078
+# grid.draw(lgd)
1079
+# popViewport()
1061 1080
 grid.draw.Legends = function(x, recording = TRUE) {
1062 1081
 	grid.draw(x@grob, recording =  recording)
1063 1082
 }
... ...
@@ -1066,7 +1085,7 @@ grid.draw.Legends = function(x, recording = TRUE) {
1066 1085
 # Grob width for legend_body
1067 1086
 #
1068 1087
 # == param
1069
-# -x legend body
1088
+# -x A legend_body object.
1070 1089
 #
1071 1090
 widthDetails.legend_body = function(x) {
1072 1091
 	attr(x, "width")
... ...
@@ -1076,7 +1095,7 @@ widthDetails.legend_body = function(x) {
1076 1095
 # Grob height for legend_body
1077 1096
 #
1078 1097
 # == param
1079
-# -x legend body
1098
+# -x A legend_body object.
1080 1099
 #
1081 1100
 heightDetails.legend_body = function(x) {
1082 1101
 	attr(x, "height")
... ...
@@ -1086,7 +1105,7 @@ heightDetails.legend_body = function(x) {
1086 1105
 # Grob width for packed_legends
1087 1106
 #
1088 1107
 # == param
1089
-# -x legend body
1108
+# -x A legend object.
1090 1109
 #
1091 1110
 widthDetails.legend = function(x) {
1092 1111
 	attr(x, "width")
... ...
@@ -1096,7 +1115,7 @@ widthDetails.legend = function(x) {
1096 1115
 # Grob height for packed_legends
1097 1116
 #
1098 1117
 # == param
1099
-# -x legend body
1118
+# -x A legend object.
1100 1119
 #
1101 1120
 heightDetails.legend = function(x) {
1102 1121
 	attr(x, "height")
... ...
@@ -1106,7 +1125,7 @@ heightDetails.legend = function(x) {
1106 1125
 # Grob width for packed_legends
1107 1126
 #
1108 1127
 # == param
1109
-# -x legend body
1128
+# -x A packed_legends object.
1110 1129
 #
1111 1130
 widthDetails.packed_legends = function(x) {
1112 1131
 	attr(x, "width")
... ...
@@ -1116,7 +1135,7 @@ widthDetails.packed_legends = function(x) {
1116 1135
 # Grob height for packed_legends
1117 1136
 #
1118 1137
 # == param
1119
-# -x legend body
1138
+# -x A packed_legends object.
1120 1139
 #
1121 1140
 heightDetails.packed_legends = function(x) {
1122 1141
 	attr(x, "height")