Browse code

a backup push

Zuguang Gu authored on 18/09/2018 10:40:29
Showing1 changed files
1 1
deleted file mode 100755
... ...
@@ -1,639 +0,0 @@
1
-<!--
2
-%\VignetteEngine{knitr}
3
-%\VignetteIndexEntry{2. Making a single heatmap}
4
-
5
-Making A Single Heatmap
6
-========================================
7
-
8
-**Author**: Zuguang Gu ( z.gu@dkfz.de )
9
-
10
-**Date**: `r Sys.Date()`
11
-
12
-
13
-```{r global_settings, echo = FALSE, message = FALSE}
14
-library(markdown)
15
-options(markdown.HTML.options = c(options('markdown.HTML.options')[[1]], "toc"))
16
-
17
-library(knitr)
18
-knitr::opts_chunk$set(
19
-    error = FALSE,
20
-    tidy  = FALSE,
21
-    message = FALSE,
22
-    fig.align = "center",
23
-    fig.width = 5,
24
-    fig.height = 5)
25
-options(markdown.HTML.stylesheet = "custom.css")
26
-
27
-options(width = 100)
28
-```
29
-
30
-A single heatmap is mostly used for a quick view of the data. It is a special case of 
31
-a heatmap list which only contains one heatmap. Compare to available tools, **ComplexHeatmap** package provides a more flexible
32
-way to support visualization of a single heatmap. In following examples, we will demonstrate
33
-how to set parameters to visualize a single heatmap.
34
-
35
-First let's load packages and generate a random matrix:
36
-
37
-```{r data}
38
-library(ComplexHeatmap)
39
-library(circlize)
40
-
41
-set.seed(123)
42
-
43
-mat = cbind(rbind(matrix(rnorm(16, -1), 4), matrix(rnorm(32, 1), 8)),
44
-            rbind(matrix(rnorm(24, 1), 4), matrix(rnorm(48, -1), 8)))
45
-
46
-# permute the rows and columns
47
-mat = mat[sample(nrow(mat), nrow(mat)), sample(ncol(mat), ncol(mat))]
48
-
49
-rownames(mat) = paste0("R", 1:12)
50
-colnames(mat) = paste0("C", 1:10)
51
-```
52
-
53
-Plot the heatmap with default settings. The default style of the heatmap is quite the same
54
-as those generated by other similar heatmap functions.
55
-
56
-```{r default}
57
-Heatmap(mat)
58
-```
59
-
60
-## Colors
61
-
62
-In most cases, the heatmap visualizes a matrix with continuous values.
63
-In this case, user should provide a color mapping function. A color mapping function
64
-should accept a vector of values and return a vector of corresponding colors. The `colorRamp2()` from
65
-the **circlize** package is helpful for generating such functions. The two arguments for `colorRamp2()`
66
-is a vector of breaks values and corresponding colors. Currently `colorRamp2()` linearly interpolates
67
-colors in every interval through LAB color space.
68
-
69
-In following example, values between -3 and 3 are 
70
-linearly interpolated to obtain corresponding colors, values larger than 3 are all mapped to red and values less than -3 are
71
-all mapped to green (so the color mapping function demonstrated here is robust to outliers).
72
-
73
-```{r color_fun}
74
-mat2 = mat
75
-mat2[1, 1] = 100000
76
-Heatmap(mat2, col = colorRamp2(c(-3, 0, 3), c("green", "white", "red")), 
77
-    cluster_rows = FALSE, cluster_columns = FALSE)
78
-```
79
-
80
-If the matrix is continuous, you can also provide a vector of colors and colors will be interpolated according to the 'k'th quantile.
81
-But remember this method is not robust to outliers.
82
-
83
-```{r color_vector}
84
-Heatmap(mat, col = rev(rainbow(10)))
85
-```
86
-
87
-If the matrix contains discrete values (either numeric or character), colors should be specified as
88
-a named vector to make it possible for the mapping from discrete values to colors. If there is no name
89
-for the color, the order of colors corresponds to the order of `unique(mat)`.
90
-
91
-```{r discrete_matrix}
92
-discrete_mat = matrix(sample(1:4, 100, replace = TRUE), 10, 10)
93
-colors = structure(circlize::rand_color(4), names = c("1", "2", "3", "4"))
94
-Heatmap(discrete_mat, col = colors)
95
-```
96
-
97
-Or a character matrix:
98
-
99
-```{r discrete_character_matrix}
100
-discrete_mat = matrix(sample(letters[1:4], 100, replace = TRUE), 10, 10)
101
-colors = structure(circlize::rand_color(4), names = letters[1:4])
102
-Heatmap(discrete_mat, col = colors)
103
-```
104
-
105
-As you see, for the numeric matrix (no matter it is continuous mapping or discrete mapping), 
106
-by default clustering is applied on both dimensions while
107
-for character matrix, clustering is suppressed.
108
-
109
-``NA`` is allowed in the heatmap. You can control the color of `NA` by `na_col` argument. 
110
-The matrix which contains `NA` can also be clustered by `Heatmap()` (since `dist()` accepts `NA` values)
111
-and clustering a matrix with `NA` values by "pearson", "spearman" or "kendall" method gives warning messages.
112
-
113
-```{r na_value}
114
-mat_with_na = mat
115
-mat_with_na[sample(c(TRUE, FALSE), nrow(mat)*ncol(mat), replace = TRUE, prob = c(1, 9))] = NA
116
-Heatmap(mat_with_na, na_col = "orange", clustering_distance_rows = "pearson")
117
-```
118
-
119
-Color space is important for interpolating colors. By default, colors are linearly interpolated in [LAB color space](https://en.wikipedia.org/wiki/Lab_color_space), but you can select the color space in `colorRamp2()` function. Compare following two plots
120
-(`+` operation on two heatmaps will be introduced in [**Making a list of heatmaps**](s3.a_list_of_heatmaps.html) vignette):
121
-
122
-```{r, fig.width = 10}
123
-f1 = colorRamp2(seq(min(mat), max(mat), length = 3), c("blue", "#EEEEEE", "red"))
124
-f2 = colorRamp2(seq(min(mat), max(mat), length = 3), c("blue", "#EEEEEE", "red"), space = "RGB")
125
-Heatmap(mat, col = f1, column_title = "LAB color space") +
126
-Heatmap(mat, col = f2, column_title = "RGB color space")
127
-```
128
-
129
-On following figure, corresponding values change evenly on the folded axis, you can see how colors change under different
130
-color spaces (the plot is made by **HilbertCurve** package). Choosing a proper color space is a little bit 
131
-subjective and it depends on specific data and color theme.
132
-Sometimes you need to try several color spaces to determine one which can best reveal potential structure of your data.
133
-
134
-
135
-```{r, fig.width = 14, fig.height = 14/5, echo = FALSE, message = FALSE}
136
-suppressPackageStartupMessages(library(HilbertCurve))
137
-space = c("RGB", "LAB", "XYZ", "sRGB", "LUV")
138
-pushViewport(viewport(layout = grid.layout(nr = 1, nc = length(space))))
139
-for(i in seq_along(space)) {
140
-    pushViewport(viewport(layout.pos.row = 1, layout.pos.col = i))
141
-    hc = HilbertCurve(1, 100, level = 4, newpage = FALSE, title = space[i])
142
-    ir = IRanges(start = 1:99, end = 2:100)
143
-    f = colorRamp2(c(-1, 0, 1), c("green", "black", "red"), space = space[i])
144
-    col = f(seq(-1, 1, length = 100))
145
-    hc_points(hc, ir, np = 3, gp = gpar(col = col, fill = col))
146
-    upViewport()
147
-}
148
-upViewport()
149
-grid.newpage()
150
-pushViewport(viewport(layout = grid.layout(nr = 1, nc = length(space))))
151
-for(i in seq_along(space)) {
152
-    pushViewport(viewport(layout.pos.row = 1, layout.pos.col = i))
153
-    hc = HilbertCurve(1, 100, level = 4, newpage = FALSE, title = space[i])
154
-    ir = IRanges(start = 1:99, end = 2:100)
155
-    f = colorRamp2(c(-1, 0, 1), c("blue", "white", "red"), space = space[i])
156
-    col = f(seq(-1, 1, length = 100))
157
-    hc_points(hc, ir, np = 3, gp = gpar(col = col, fill = col))
158
-    upViewport()
159
-}
160
-upViewport()
161
-
162
-```
163
-
164
-## Titles
165
-
166
-The name of the heatmap by default is used as the title of the heatmap legend.
167
-The name also plays as a unique id if you plot more than one heatmaps together.
168
-Later we can use this name to go to the corresponding heatmap to add more graphics 
169
-(see [**Heatmap Decoration**](s6.heatmap_decoration.html) vignette).
170
-
171
-```{r with_matrix_name}
172
-Heatmap(mat, name = "foo")
173
-```
174
-
175
-The title of the heatmap legend can be modified by `heatmap_legend_param` 
176
-(see [**Heatmap and Annotation Legends**](s5.legend.html) vignette
177
-for more control on the legend).
178
-
179
-```{r heatmap_legend_title}
180
-Heatmap(mat, heatmap_legend_param = list(title = "legend"))
181
-```
182
-
183
-You can set heatmap titles to be put either by the rows or by the columns. Note at a same time
184
-you can only put e.g. column title either on the top or at the bottom of the heatmap.
185
-The graphic parameters can be set by `row_title_gp` and `column_title_gp` respectively.
186
-Please remember you should use `gpar()` to specify graphic parameters.
187
-
188
-```{r row_column_title}
189
-Heatmap(mat, name = "foo", column_title = "I am a column title", 
190
-    row_title = "I am a row title")
191
-Heatmap(mat, name = "foo", column_title = "I am a column title at the bottom", 
192
-    column_title_side = "bottom")
193
-Heatmap(mat, name = "foo", column_title = "I am a big column title", 
194
-    column_title_gp = gpar(fontsize = 20, fontface = "bold"))
195
-```
196
-
197
-Rotations for titles can be set by `row_title_rot` and `column_title_rot`, but only horizontal and vertical 
198
-rotations are allowed.
199
-
200
-```{r title_rotation}
201
-Heatmap(mat, name = "foo", row_title = "row title", row_title_rot = 0)
202
-```
203
-
204
-## Clustering
205
-
206
-Clustering may be the key feature of the heatmap visualization. In **ComplexHeatmap** package,
207
-clustering is supported with high flexibility. You can specify the 
208
-clustering either by a pre-defined method (e.g. "eulidean" or "pearson"), or by a distance function, or by a object that already
209
-contains clustering, or directly by a clustering function. It is also possible to render 
210
-your dendrograms with different colors and styles for different branches for better revealing
211
-structures of your data.
212
-
213
-First there are general settings for the clustering, e.g. whether do or show dendrograms, side
214
-of the dendrograms and size of the dendrograms.
215
-
216
-```{r cluster_basic}
217
-Heatmap(mat, name = "foo", cluster_rows = FALSE)
218
-Heatmap(mat, name = "foo", show_column_dend = FALSE)
219
-Heatmap(mat, name = "foo", row_dend_side = "right")
220
-Heatmap(mat, name = "foo", column_dend_height = unit(2, "cm"))
221
-```
222
-
223
-There are three ways to specify distance metric for clustering:
224
-
225
-- specify distance as a pre-defined option. The valid values are the supported methods
226
-  in `dist()` function and within `pearson`, `spearman` and `kendall`. `NA` values are ignored
227
-  for pre-defined clustering but with giving warnings (see example in **Colors** section).
228
-- a self-defined function which calculates distance from a matrix. The function should
229
-  only contain one argument. Please note for clustering on columns, the matrix will be transposed
230
-  automatically.
231
-- a self-defined function which calculates distance from two vectors. The function should
232
-  only contain two arguments.
233
-
234
-```{r cluster_distance}
235
-Heatmap(mat, name = "foo", clustering_distance_rows = "pearson")
236
-Heatmap(mat, name = "foo", clustering_distance_rows = function(m) dist(m))
237
-Heatmap(mat, name = "foo", clustering_distance_rows = function(x, y) 1 - cor(x, y))
238
-```
239
-
240
-Based on this feature, we can apply clustering which is robust to outliers based on the pair-wise distance.
241
-
242
-```{r cluster_distance_advanced}
243
-mat_with_outliers = mat
244
-for(i in  1:10) mat_with_outliers[i, i] = 1000
245
-robust_dist = function(x, y) {
246
-    qx = quantile(x, c(0.1, 0.9))
247
-    qy = quantile(y, c(0.1, 0.9))
248
-    l = x > qx[1] & x < qx[2] & y > qy[1] & y < qy[2]
249
-    x = x[l]
250
-    y = y[l]
251
-    sqrt(sum((x - y)^2))
252
-}
253
-Heatmap(mat_with_outliers, name = "foo", 
254
-    col = colorRamp2(c(-3, 0, 3), c("green", "white", "red")),
255
-    clustering_distance_rows = robust_dist,
256
-    clustering_distance_columns = robust_dist)
257
-```
258
-
259
-If possible distance method provided, you can also cluster a character matrix.
260
-`cell_fun` argument will be explained in later section.
261
-
262
-```{r cluster_character_matrix}
263
-mat_letters = matrix(sample(letters[1:4], 100, replace = TRUE), 10)
264
-# distance in th ASCII table
265
-dist_letters = function(x, y) {
266
-    x = strtoi(charToRaw(paste(x, collapse = "")), base = 16)
267
-    y = strtoi(charToRaw(paste(y, collapse = "")), base = 16)
268
-    sqrt(sum((x - y)^2))
269
-}
270
-Heatmap(mat_letters, name = "foo", col = structure(2:5, names = letters[1:4]),
271
-    clustering_distance_rows = dist_letters, clustering_distance_columns = dist_letters,
272
-    cell_fun = function(j, i, x, y, w, h, col) {
273
-        grid.text(mat_letters[i, j], x, y)
274
-    })
275
-```
276
-
277
-Method to make hierarchical clustering can be specified by `clustering_method_rows` and
278
-`clustering_method_columns`. Possible methods are those supported in `hclust()` function.
279
-
280
-```{r cluster_method}
281
-Heatmap(mat, name = "foo", clustering_method_rows = "single")
282
-```
283
-
284
-By default, clustering is performed by `hclust()`. But you can also utilize clustering results
285
-which are generated by other methods by specifying `cluster_rows` or `cluster_columns` to a 
286
-`hclust` or `dendrogram` object. In following examples, we use `diana()` and `agnes()` methods
287
-which are from the **cluster** package to perform clusterings.
288
-
289
-```{r cluster_object}
290
-library(cluster)
291
-Heatmap(mat, name = "foo", cluster_rows = as.dendrogram(diana(mat)),
292
-   cluster_columns = as.dendrogram(agnes(t(mat))))
293
-```
294
-
295
-In the native `heatmap()` function, dendrograms on row and on column are reordered to let features with larger different
296
-separated more from each other, By default the reordering for the dendrograms are turned on by `Heatmap()` as well. 
297
-
298
-Besides the default reordering method, you can first generate a dendrogram and apply other reordering
299
-method and then send the reordered dendrogram to `cluster_rows` argument. 
300
-
301
-Compare following three plots:
302
-
303
-```{r cluster_dendsort, fig.width = 14}
304
-pushViewport(viewport(layout = grid.layout(nr = 1, nc = 3)))
305
-pushViewport(viewport(layout.pos.row = 1, layout.pos.col = 1))
306
-draw(Heatmap(mat, name = "foo", row_dend_reorder = FALSE, column_title = "no reordering"), newpage = FALSE)
307
-upViewport()
308
-
309
-pushViewport(viewport(layout.pos.row = 1, layout.pos.col = 2))
310
-draw(Heatmap(mat, name = "foo", row_dend_reorder = TRUE, column_title = "applied reordering"), newpage = FALSE)
311
-upViewport()
312
-
313
-library(dendsort)
314
-dend = dendsort(hclust(dist(mat)))
315
-pushViewport(viewport(layout.pos.row = 1, layout.pos.col = 3))
316
-draw(Heatmap(mat, name = "foo", cluster_rows = dend, row_dend_reorder = FALSE, 
317
-    column_title = "reordering by dendsort"), newpage = FALSE)
318
-upViewport(2)
319
-```
320
-
321
-You can render your `dendrogram` object by the **dendextend** package and make a more customized
322
-visualization of the dendrogram. 
323
-
324
-```{r cluster_dendextend}
325
-library(dendextend)
326
-dend = hclust(dist(mat))
327
-dend = color_branches(dend, k = 2)
328
-Heatmap(mat, name = "foo", cluster_rows = dend)
329
-```
330
-
331
-More generally, `cluster_rows` and `cluster_columns` can be functions which calculate the clusterings.
332
-The input argument for the self-defined function should be a matrix and returned value should be a `hclust` or `dendrogram`
333
-object. Please note, when `cluster_rows` is executed internally, the argument `m` is the input `mat` itself
334
-while `m` is the transpose of `mat` when executing `cluster_columns`.
335
-
336
-```{r cluster_function}
337
-Heatmap(mat, name = "foo", cluster_rows = function(m) as.dendrogram(diana(m)),
338
-    cluster_columns = function(m) as.dendrogram(agnes(m)))
339
-```
340
-
341
-`fastcluster::hclust` implements a faster version of `hclust`. We can re-define `cluster_rows` and `cluster_columns`
342
-to use the faster version of `hclust`. But note `fastcluster::hclust` only speed up the calculation of the cluster while not the
343
-calculation of distance matrix.
344
-
345
-```{r}
346
-# code not run when building the vignette
347
-Heatmap(mat, name = "foo", cluster_rows = function(m) fastcluster::hclust(dist(m)),
348
-    cluster_columns = function(m) fastcluster::hclust(dist(m))) # for column cluster, m will be automatically transposed
349
-```
350
-
351
-To make it more convinient to use the faster version of `hclust` (assuming you have many heatmaps to be concatenated), it can
352
-be set as a global option:
353
-
354
-```{r}
355
-# code not run when building the vignette
356
-ht_global_opt(fast_hclust = TRUE)
357
-# now hclust from fastcluster package is used in all heatmaps
358
-Heatmap(mat, name = "foo")
359
-```
360
-
361
-Clustering can help to adjust order in rows and in columns. But you can still set the order manually by `row_order`
362
-and `column_order`. Note you need to turn off clustering
363
-if you want to set order manually. `row_order` and `column_order` can also be set according to matrix row names and column names if they exist.
364
-
365
-```{r manual_order}
366
-Heatmap(mat, name = "foo", cluster_rows = FALSE, cluster_columns = FALSE, 
367
-    row_order = 12:1, column_order = 10:1)
368
-```
369
-
370
-Note `row_dend_reorder` and `row_order` are different. `row_dend_reorder` is applied on the dendrogram. Because for any node in the
371
-dendrogram, rotating two leaves gives an identical dendrogram. Thus, reordering the dendrogram by automatically rotating sub-dendrogram
372
-at every node will help to separate elements with more difference to be farther from each other. While `row_order` is
373
-applied on the matrix and dendrograms are suppressed.
374
-
375
-## Dimension names
376
-
377
-Side, visibility and graphic parameters for dimension names can be set as follows.
378
-
379
-```{r dimension_name}
380
-Heatmap(mat, name = "foo", row_names_side = "left", row_dend_side = "right", 
381
-    column_names_side = "top", column_dend_side = "bottom")
382
-Heatmap(mat, name = "foo", show_row_names = FALSE)
383
-Heatmap(mat, name = "foo", row_names_gp = gpar(fontsize = 20))
384
-Heatmap(mat, name = "foo", row_names_gp = gpar(col = c(rep("red", 4), rep("blue", 8))))
385
-```
386
-
387
-Currently, rotations for column names and row names are not supported (or maybe in the future versions). Because
388
-after the text rotation, the dimension names will go inside other heatmap components
389
-which will mess up the heatmap layout. However, as will be introduced in [**Heatmap Annotation**](s4.heatmap_annotation.html)
390
-vignette, text rotation is allowed in the heatmap annotations. Thus, users can provide a row annotation
391
-or column annotation which only contains rotated text to simulate rotated row/column names (You will see the 
392
-example in the [**Heatmap Annotation**](s4.heatmap_annotation.html) vignette).
393
-
394
-## Split heatmap by rows
395
-
396
-A heatmap can be split by rows. This will enhance the visualization of group separation in the heatmap.
397
-The `km` argument with a value larger than 1 means applying a k-means clustering on rows and clustering
398
-is applied on every k-means cluster.
399
-
400
-```{r k_means}
401
-Heatmap(mat, name = "foo", km = 2)
402
-```
403
-
404
-More generally, `split` can be set to a vector or a data frame in which different combination of levels
405
-split the rows of the heatmap. Actually, k-means clustering just generates a vector of row classes and appends
406
-`split` with one additional column. The combined row titles for each row slice can be controlled by `combined_name_fun` argument.
407
-The order of each slice can be controlled by `levels` of each variable in `split`.
408
-
409
-```{r split}
410
-Heatmap(mat, name = "foo", split = rep(c("A", "B"), 6))
411
-Heatmap(mat, name = "foo", split = data.frame(rep(c("A", "B"), 6), rep(c("C", "D"), each = 6)))
412
-Heatmap(mat, name = "foo", split = data.frame(rep(c("A", "B"), 6), rep(c("C", "D"), each = 6)), 
413
-    combined_name_fun = function(x) paste(x, collapse = "\n"))
414
-Heatmap(mat, name = "foo", km = 2, split = factor(rep(c("A", "B"), 6), levels = c("B", "A")), 
415
-    combined_name_fun = function(x) paste(x, collapse = "\n"))
416
-Heatmap(mat, name = "foo", km = 2, split = rep(c("A", "B"), 6), combined_name_fun = NULL)
417
-```
418
-
419
-If you are not happy with the default k-means partitioning method, it is easy to use other partitioning methods
420
-by just assigning the partitioning vector to `split`.
421
-
422
-```{r pam}
423
-pa = pam(mat, k = 3)
424
-Heatmap(mat, name = "foo", split = paste0("pam", pa$clustering))
425
-```
426
-
427
-If ``row_order`` is set, in each slice, rows are still ordered.
428
-
429
-```{r split_row_order}
430
-Heatmap(mat, name = "foo", row_order = 12:1, cluster_rows = FALSE, km = 2)
431
-```
432
-
433
-Height of gaps between row slices can be controlled by `gap` (a single unit or a vector of units).
434
-
435
-```{r split_gap}
436
-Heatmap(mat, name = "foo", split = paste0("pam", pa$clustering), gap = unit(5, "mm"))
437
-```
438
-
439
-Character matrix can only be split by `split` argument.
440
-
441
-```{r split_discrete_matrix}
442
-Heatmap(discrete_mat, name = "foo", col = 1:4,
443
-    split = rep(letters[1:2], each = 5))
444
-```
445
-
446
-When split is applied on rows, graphic parameters for row title and row names can be specified as same
447
-length as number of row slices.
448
-
449
-```{r split_graphical_parameter}
450
-Heatmap(mat, name = "foo", km = 2, row_title_gp = gpar(col = c("red", "blue"), font = 1:2),
451
-    row_names_gp = gpar(col = c("green", "orange"), fontsize = c(10, 14)))
452
-```
453
-
454
-Users may already have a dendrogram for rows
455
-and they want to split rows by splitting the dendrogram into k sub trees. In this case,
456
-`split` can be specified as a single number:
457
-
458
-```{r split_dendrogram}
459
-dend = hclust(dist(mat))
460
-dend = color_branches(dend, k = 2)
461
-Heatmap(mat, name = "foo", cluster_rows = dend, split = 2)
462
-```
463
-
464
-Or they just split rows by specifying `split` as an integer. Note it is different from by `km`.
465
-If `km` is set, k-means clustering is applied first and clustering is applied to every k-mean cluster;
466
-while if `split` is an integer, clustering is applied to the whole matrix and later split by `cutree()`.
467
-
468
-```{r}
469
-Heatmap(mat, name = "foo", split = 2)
470
-```
471
-
472
-## Self define the heatmap body
473
-
474
-`rect_gp` argument provides basic graphic settings for the heatmap body (note `fill` parameter is disabled).
475
-
476
-```{r rect_gp}
477
-Heatmap(mat, name = "foo", rect_gp = gpar(col = "green", lty = 2, lwd = 2))
478
-```
479
-
480
-The heatmap body can be self-defined. By default the heatmap body is composed by an array of rectangles (it is called cells here)
481
-with different filled colors. If `type` in `rect_gp` is set to `none`, the array for cells is initialized but
482
-no graphics are put in. Then, users can define their own graphic function by `cell_fun`. `cell_fun` is applied
483
-on every cell in the heatmap and provides following information on the 'current' cell:
484
-
485
-- `j`: column index in the matrix. Column index corresponds to the x-direction in the viewport, 
486
-  that's why `j` is put as the first argument.
487
-- `i`: row index in the matrix.
488
-- `x`: x coordinate of middle point of the cell which is measured in the viewport of the heatmap body.
489
-- `y`: y coordinate of middle point of the cell which is measured in the viewport of the heatmap body.
490
-- `width`: width of the cell.
491
-- `height`: height of the cell.
492
-- `fill`: color of the cell.
493
-
494
-The most common use is to add numeric values to the heatmap:
495
-
496
-```{r}
497
-Heatmap(mat, name = "foo", cell_fun = function(j, i, x, y, width, height, fill) {
498
-    grid.text(sprintf("%.1f", mat[i, j]), x, y, gp = gpar(fontsize = 10))
499
-})
500
-```
501
-
502
-In following example, we make a heatmap which shows correlation matrix similar as the **corrplot** package:
503
-
504
-```{r cell_fun, fig.width = 6.5, fig.height = 6}
505
-cor_mat = cor(mat)
506
-od = hclust(dist(cor_mat))$order
507
-cor_mat = cor_mat[od, od]
508
-nm = rownames(cor_mat)
509
-col_fun = circlize::colorRamp2(c(-1, 0, 1), c("green", "white", "red"))
510
-# `col = col_fun` here is used to generate the legend
511
-Heatmap(cor_mat, name = "correlation", col = col_fun, rect_gp = gpar(type = "none"), 
512
-    cell_fun = function(j, i, x, y, width, height, fill) {
513
-        grid.rect(x = x, y = y, width = width, height = height, gp = gpar(col = "grey", fill = NA))
514
-        if(i == j) {
515
-            grid.text(nm[i], x = x, y = y)
516
-        } else if(i > j) {
517
-            grid.circle(x = x, y = y, r = abs(cor_mat[i, j])/2 * min(unit.c(width, height)), 
518
-                gp = gpar(fill = col_fun(cor_mat[i, j]), col = NA))
519
-        } else {
520
-            grid.text(sprintf("%.1f", cor_mat[i, j]), x, y, gp = gpar(fontsize = 8))
521
-        }
522
-    }, cluster_rows = FALSE, cluster_columns = FALSE,
523
-    show_row_names = FALSE, show_column_names = FALSE)
524
-```
525
-
526
-Note `cell_fun` is applied to every cell through a `for` loop, so it will be a little bit slow
527
-for large matrix.
528
-
529
-One last example is to visualize a [GO game](https://en.wikipedia.org/wiki/Go_(game)). The input data takes
530
-records of moves in the game.
531
-
532
-```{r}
533
-str = "B[cp];W[pq];B[dc];W[qd];B[eq];W[od];B[de];W[jc];B[qk];W[qn]
534
-;B[qh];W[ck];B[ci];W[cn];B[hc];W[je];B[jq];W[df];B[ee];W[cf]
535
-;B[ei];W[bc];B[ce];W[be];B[bd];W[cd];B[bf];W[ad];B[bg];W[cc]
536
-;B[eb];W[db];B[ec];W[lq];B[nq];W[jp];B[iq];W[kq];B[pp];W[op]
537
-;B[po];W[oq];B[rp];W[ql];B[oo];W[no];B[pl];W[pm];B[np];W[qq]
538
-;B[om];W[ol];B[pk];W[qp];B[on];W[rm];B[mo];W[nr];B[rl];W[rk]
539
-;B[qm];W[dp];B[dq];W[ql];B[or];W[mp];B[nn];W[mq];B[qm];W[bp]
540
-;B[co];W[ql];B[no];W[pr];B[qm];W[dd];B[pn];W[ed];B[bo];W[eg]
541
-;B[ef];W[dg];B[ge];W[gh];B[gf];W[gg];B[ek];W[ig];B[fd];W[en]
542
-;B[bn];W[ip];B[dm];W[ff];B[cb];W[fe];B[hp];W[ho];B[hq];W[el]
543
-;B[dl];W[fk];B[ej];W[fp];B[go];W[hn];B[fo];W[em];B[dn];W[eo]
544
-;B[gp];W[ib];B[gc];W[pg];B[qg];W[ng];B[qc];W[re];B[pf];W[of]
545
-;B[rc];W[ob];B[ph];W[qo];B[rn];W[mi];B[og];W[oe];B[qe];W[rd]
546
-;B[rf];W[pd];B[gm];W[gl];B[fm];W[fl];B[lj];W[mj];B[lk];W[ro]
547
-;B[hl];W[hk];B[ik];W[dk];B[bi];W[di];B[dj];W[dh];B[hj];W[gj]
548
-;B[li];W[lh];B[kh];W[lg];B[jn];W[do];B[cl];W[ij];B[gk];W[bl]
549
-;B[cm];W[hk];B[jk];W[lo];B[hi];W[hm];B[gk];W[bm];B[cn];W[hk]
550
-;B[il];W[cq];B[bq];W[ii];B[sm];W[jo];B[kn];W[fq];B[ep];W[cj]
551
-;B[bk];W[er];B[cr];W[gr];B[gk];W[fj];B[ko];W[kp];B[hr];W[jr]
552
-;B[nh];W[mh];B[mk];W[bb];B[da];W[jh];B[ic];W[id];B[hb];W[jb]
553
-;B[oj];W[fn];B[fs];W[fr];B[gs];W[es];B[hs];W[gn];B[kr];W[is]
554
-;B[dr];W[fi];B[bj];W[hd];B[gd];W[ln];B[lm];W[oi];B[oh];W[ni]
555
-;B[pi];W[ki];B[kj];W[ji];B[so];W[rq];B[if];W[jf];B[hh];W[hf]
556
-;B[he];W[ie];B[hg];W[ba];B[ca];W[sp];B[im];W[sn];B[rm];W[pe]
557
-;B[qf];W[if];B[hk];W[nj];B[nk];W[lr];B[mn];W[af];B[ag];W[ch]
558
-;B[bh];W[lp];B[ia];W[ja];B[ha];W[sf];B[sg];W[se];B[eh];W[fh]
559
-;B[in];W[ih];B[ae];W[so];B[af]"
560
-```
561
-
562
-Then we convert it into a matrix:
563
-
564
-```{r}
565
-str = gsub("\\n", "", str)
566
-step = strsplit(str, ";")[[1]]
567
-type = gsub("(B|W).*", "\\1", step)
568
-row = gsub("(B|W)\\[(.).\\]", "\\2", step)
569
-column = gsub("(B|W)\\[.(.)\\]", "\\2", step)
570
-
571
-mat = matrix(nrow = 19, ncol = 19)
572
-rownames(mat) = letters[1:19]
573
-colnames(mat) = letters[1:19]
574
-for(i in seq_along(row)) {
575
-    mat[row[i], column[i]] = type[i]
576
-}
577
-mat
578
-```
579
-
580
-Black and white stones are put based on the values in the matrix:
581
-
582
-```{r, fig.width = 8, fig.height = 8}
583
-Heatmap(mat, name = "go", rect_gp = gpar(type = "none"),
584
-    cell_fun = function(j, i, x, y, w, h, col) {
585
-        grid.rect(x, y, w, h, gp = gpar(fill = "#dcb35c", col = NA))
586
-        if(i == 1) {
587
-            grid.segments(x, y-h*0.5, x, y)
588
-        } else if(i == nrow(mat)) {
589
-            grid.segments(x, y, x, y+h*0.5)
590
-        } else {
591
-            grid.segments(x, y-h*0.5, x, y+h*0.5)
592
-        }
593
-        if(j == 1) {
594
-            grid.segments(x, y, x+w*0.5, y)        
595
-        } else if(j == ncol(mat)) {
596
-            grid.segments(x-w*0.5, y, x, y)
597
-        } else {
598
-            grid.segments(x-w*0.5, y, x+w*0.5, y)
599
-        }
600
-
601
-        if(i %in% c(4, 10, 16) & j %in% c(4, 10, 16)) {
602
-            grid.points(x, y, pch = 16, size = unit(2, "mm"))
603
-        }
604
-                
605
-        r = min(unit.c(w, h))*0.45
606
-        if(is.na(mat[i, j])) {
607
-        } else if(mat[i, j] == "W") {
608
-            grid.circle(x, y, r, gp = gpar(fill = "white", col = "white"))
609
-        } else if(mat[i, j] == "B") {
610
-            grid.circle(x, y, r, gp = gpar(fill = "black", col = "black"))
611
-        }
612
-    },
613
-    col = c("B" = "black", "W" = "white"),
614
-    show_row_names = FALSE, show_column_names = FALSE,
615
-    column_title = "One famous GO game",
616
-    heatmap_legend_param = list(title = "Player", at = c("B", "W"), 
617
-        labels = c("player1", "player2"), grid_border = "black")
618
-)
619
-```
620
-
621
-## Set heatmap body as raster image
622
-
623
-Saving plots in PDF format is kind of best parctice to preserve the quality. However,
624
-when there are too many rows (say, > 10000), the output PDF file size would be huge and it takes
625
-time and memory to read the plot. On the other hand, details of the huge matrix will not be seen
626
-in limited size of PDF file. Rendering heatmaps as raster images will effectively reduce
627
-the file size. In `Heatmap()` function, there are four options which control how to generate
628
-the raster image: `use_raster`, `raster_device`, `raster_quality`, `raster_device_param`. 
629
-
630
-You can choose graphic device (`png`, `jpeg` and `tiff`) by `raster_device`, control the quality of the raster image by `raster_quality`,
631
-and pass further parameters for a specific device by `raster_device_param`. [Check this web page for better demonstrations.](http://zuguang.de/blog/html/d3aa6e2b289514ecddded64a467d1961.html)
632
-
633
-## Session info
634
-
635
-```{r}
636
-sessionInfo()
637
-```
Browse code

add an example in vignette

Zuguang Gu authored on 09/02/2017 10:03:53
Showing1 changed files
... ...
@@ -493,6 +493,14 @@ on every cell in the heatmap and provides following information on the 'current'
493 493
 - `height`: height of the cell.
494 494
 - `fill`: color of the cell.
495 495
 
496
+The most common use is to add numeric values to the heatmap:
497
+
498
+```{r}
499
+Heatmap(mat, name = "foo", cell_fun = function(j, i, x, y, width, height, fill) {
500
+    grid.text(sprintf("%.1f", mat[i, j]), x, y, gp = gpar(fontsize = 10))
501
+})
502
+```
503
+
496 504
 In following example, we make a heatmap which shows correlation matrix similar as the **corrplot** package:
497 505
 
498 506
 ```{r cell_fun, fig.width = 6.5, fig.height = 6}
Browse code

HeatmapAnnotation() can directly add annotation names

Zuguang Gu authored on 14/06/2016 14:00:31
Showing1 changed files
... ...
@@ -196,7 +196,7 @@ Heatmap(mat, name = "foo", column_title = "I am a big column title",
196 196
     column_title_gp = gpar(fontsize = 20, fontface = "bold"))
197 197
 ```
198 198
 
199
-Roatations for titles can be set by `row_title_rot` and `column_title_rot`, but only horizontal and vertical 
199
+Rotations for titles can be set by `row_title_rot` and `column_title_rot`, but only horizontal and vertical 
200 200
 rotations are allowed.
201 201
 
202 202
 ```{r title_rotation}
... ...
@@ -212,7 +212,7 @@ contains clustering, or directly by a clustering function. It is also possible t
212 212
 your dendrograms with different colors and styles for different branches for better revealing
213 213
 structures of your data.
214 214
 
215
-First there are general settings for the clustering, e.g. whether show dendrograms, side
215
+First there are general settings for the clustering, e.g. whether do or show dendrograms, side
216 216
 of the dendrograms and size of the dendrograms.
217 217
 
218 218
 ```{r cluster_basic}
... ...
@@ -263,6 +263,7 @@ If possible distance method provided, you can also cluster a character matrix.
263 263
 
264 264
 ```{r cluster_character_matrix}
265 265
 mat_letters = matrix(sample(letters[1:4], 100, replace = TRUE), 10)
266
+# distance in th ASCII table
266 267
 dist_letters = function(x, y) {
267 268
     x = strtoi(charToRaw(paste(x, collapse = "")), base = 16)
268 269
     y = strtoi(charToRaw(paste(y, collapse = "")), base = 16)
... ...
@@ -294,8 +295,7 @@ Heatmap(mat, name = "foo", cluster_rows = as.dendrogram(diana(mat)),
294 295
 ```
295 296
 
296 297
 In the native `heatmap()` function, dendrograms on row and on column are reordered to let features with larger different
297
-separated more from each other, but according to my experience, the default reordering can not always give nice visualization.
298
-So by default the reordering for the dendrograms are turned off for `Heatmap()` function. 
298
+separated more from each other, By default the reordering for the dendrograms are turned on by `Heatmap()` as well. 
299 299
 
300 300
 Besides the default reordering method, you can first generate a dendrogram and apply other reordering
301 301
 method and then send the reordered dendrogram to `cluster_rows` argument. 
... ...
@@ -340,6 +340,26 @@ Heatmap(mat, name = "foo", cluster_rows = function(m) as.dendrogram(diana(m)),
340 340
     cluster_columns = function(m) as.dendrogram(agnes(m)))
341 341
 ```
342 342
 
343
+`fastcluster::hclust` implements a faster version of `hclust`. We can re-define `cluster_rows` and `cluster_columns`
344
+to use the faster version of `hclust`. But note `fastcluster::hclust` only speed up the calculation of the cluster while not the
345
+calculation of distance matrix.
346
+
347
+```{r}
348
+# code not run when building the vignette
349
+Heatmap(mat, name = "foo", cluster_rows = function(m) fastcluster::hclust(dist(m)),
350
+    cluster_columns = function(m) fastcluster::hclust(dist(m))) # for column cluster, m will be automatically transposed
351
+```
352
+
353
+To make it more convinient to use the faster version of `hclust` (assuming you have many heatmaps to be concatenated), it can
354
+be set as a global option:
355
+
356
+```{r}
357
+# code not run when building the vignette
358
+ht_global_opt(fast_hclust = TRUE)
359
+# now hclust from fastcluster package is used in all heatmaps
360
+Heatmap(mat, name = "foo")
361
+```
362
+
343 363
 Clustering can help to adjust order in rows and in columns. But you can still set the order manually by `row_order`
344 364
 and `column_order`. Note you need to turn off clustering
345 365
 if you want to set order manually. `row_order` and `column_order` can also be set according to matrix row names and column names if they exist.
... ...
@@ -438,6 +458,8 @@ and they want to split rows by splitting the dendrogram into k sub trees. In thi
438 458
 `split` can be specified as a single number:
439 459
 
440 460
 ```{r split_dendrogram}
461
+dend = hclust(dist(mat))
462
+dend = color_branches(dend, k = 2)
441 463
 Heatmap(mat, name = "foo", cluster_rows = dend, split = 2)
442 464
 ```
443 465
 
... ...
@@ -600,7 +622,7 @@ the file size. In `Heatmap()` function, there are four options which control how
600 622
 the raster image: `use_raster`, `raster_device`, `raster_quality`, `raster_device_param`. 
601 623
 
602 624
 You can choose graphic device (`png`, `jpeg` and `tiff`) by `raster_device`, control the quality of the raster image by `raster_quality`,
603
-and pass further parameters for a specific device by `raster_device_param`.
625
+and pass further parameters for a specific device by `raster_device_param`. [Check this web page for better demonstrations.](http://zuguang.de/blog/html/d3aa6e2b289514ecddded64a467d1961.html)
604 626
 
605 627
 ## Session info
606 628
 
Browse code

just found dist() accpets NA values

Zuguang Gu authored on 26/04/2016 10:05:25
Showing1 changed files
... ...
@@ -109,12 +109,13 @@ by default clustering is applied on both dimensions while
109 109
 for character matrix, clustering is suppressed.
110 110
 
111 111
 ``NA`` is allowed in the heatmap. You can control the color of `NA` by `na_col` argument. 
112
-The matrix which contains `NA` can also be clustered by `Heatmap()` but giving warning messages.
112
+The matrix which contains `NA` can also be clustered by `Heatmap()` (since `dist()` accepts `NA` values)
113
+and clustering a matrix with `NA` values by "pearson", "spearman" or "kendall" method gives warning messages.
113 114
 
114 115
 ```{r na_value}
115 116
 mat_with_na = mat
116 117
 mat_with_na[sample(c(TRUE, FALSE), nrow(mat)*ncol(mat), replace = TRUE, prob = c(1, 9))] = NA
117
-Heatmap(mat_with_na, na_col = "orange")
118
+Heatmap(mat_with_na, na_col = "orange", clustering_distance_rows = "pearson")
118 119
 ```
119 120
 
120 121
 Color space is important for interpolating colors. By default, colors are linearly interpolated in [LAB color space](https://en.wikipedia.org/wiki/Lab_color_space), but you can select the color space in `colorRamp2()` function. Compare following two plots
Browse code

support Cairo devices to generate raster image

Zuguang Gu authored on 27/03/2016 16:10:14
Showing1 changed files
... ...
@@ -595,7 +595,7 @@ Saving plots in PDF format is kind of best parctice to preserve the quality. How
595 595
 when there are too many rows (say, > 10000), the output PDF file size would be huge and it takes
596 596
 time and memory to read the plot. On the other hand, details of the huge matrix will not be seen
597 597
 in limited size of PDF file. Rendering heatmaps as raster images will effectively reduce
598
-the file size. In `Heatmap()` function, there are three options which controls how to generate
598
+the file size. In `Heatmap()` function, there are four options which control how to generate
599 599
 the raster image: `use_raster`, `raster_device`, `raster_quality`, `raster_device_param`. 
600 600
 
601 601
 You can choose graphic device (`png`, `jpeg` and `tiff`) by `raster_device`, control the quality of the raster image by `raster_quality`,
Browse code

give warnings if there are duplicated heatmap names

Zuguang Gu authored on 27/03/2016 15:02:46
Showing1 changed files
... ...
@@ -591,7 +591,7 @@ Heatmap(mat, name = "go", rect_gp = gpar(type = "none"),
591 591
 
592 592
 ## Set heatmap body as raster image
593 593
 
594
-Saving plots in PDF format is kind of best parctice to preserve the quanlity. However,
594
+Saving plots in PDF format is kind of best parctice to preserve the quality. However,
595 595
 when there are too many rows (say, > 10000), the output PDF file size would be huge and it takes
596 596
 time and memory to read the plot. On the other hand, details of the huge matrix will not be seen
597 597
 in limited size of PDF file. Rendering heatmaps as raster images will effectively reduce
Browse code

heatmap bodies can be replaced with raster images

Zuguang Gu authored on 27/03/2016 14:24:29
Showing1 changed files
... ...
@@ -589,6 +589,18 @@ Heatmap(mat, name = "go", rect_gp = gpar(type = "none"),
589 589
 )
590 590
 ```
591 591
 
592
+## Set heatmap body as raster image
593
+
594
+Saving plots in PDF format is kind of best parctice to preserve the quanlity. However,
595
+when there are too many rows (say, > 10000), the output PDF file size would be huge and it takes
596
+time and memory to read the plot. On the other hand, details of the huge matrix will not be seen
597
+in limited size of PDF file. Rendering heatmaps as raster images will effectively reduce
598
+the file size. In `Heatmap()` function, there are three options which controls how to generate
599
+the raster image: `use_raster`, `raster_device`, `raster_quality`, `raster_device_param`. 
600
+
601
+You can choose graphic device (`png`, `jpeg` and `tiff`) by `raster_device`, control the quality of the raster image by `raster_quality`,
602
+and pass further parameters for a specific device by `raster_device_param`.
603
+
592 604
 ## Session info
593 605
 
594 606
 ```{r}
Browse code

solve conflicts

git-svn-id: https://hedgehog.fhcrc.org/bioconductor/trunk/madman/Rpacks/ComplexHeatmap@109710 bc3139a8-67e5-0310-9ffc-ced21a209358

z.gu authored on 16/10/2015 20:24:38
Showing1 changed files
... ...
@@ -497,6 +497,98 @@ Heatmap(cor_mat, name = "correlation", col = col_fun, rect_gp = gpar(type = "non
497 497
 Note `cell_fun` is applied to every cell through a `for` loop, so it will be a little bit slow
498 498
 for large matrix.
499 499
 
500
+One last example is to visualize a [GO game](https://en.wikipedia.org/wiki/Go_(game)). The input data takes
501
+records of moves in the game.
502
+
503
+```{r}
504
+str = "B[cp];W[pq];B[dc];W[qd];B[eq];W[od];B[de];W[jc];B[qk];W[qn]
505
+;B[qh];W[ck];B[ci];W[cn];B[hc];W[je];B[jq];W[df];B[ee];W[cf]
506
+;B[ei];W[bc];B[ce];W[be];B[bd];W[cd];B[bf];W[ad];B[bg];W[cc]
507
+;B[eb];W[db];B[ec];W[lq];B[nq];W[jp];B[iq];W[kq];B[pp];W[op]
508
+;B[po];W[oq];B[rp];W[ql];B[oo];W[no];B[pl];W[pm];B[np];W[qq]
509
+;B[om];W[ol];B[pk];W[qp];B[on];W[rm];B[mo];W[nr];B[rl];W[rk]
510
+;B[qm];W[dp];B[dq];W[ql];B[or];W[mp];B[nn];W[mq];B[qm];W[bp]
511
+;B[co];W[ql];B[no];W[pr];B[qm];W[dd];B[pn];W[ed];B[bo];W[eg]
512
+;B[ef];W[dg];B[ge];W[gh];B[gf];W[gg];B[ek];W[ig];B[fd];W[en]
513
+;B[bn];W[ip];B[dm];W[ff];B[cb];W[fe];B[hp];W[ho];B[hq];W[el]
514
+;B[dl];W[fk];B[ej];W[fp];B[go];W[hn];B[fo];W[em];B[dn];W[eo]
515
+;B[gp];W[ib];B[gc];W[pg];B[qg];W[ng];B[qc];W[re];B[pf];W[of]
516
+;B[rc];W[ob];B[ph];W[qo];B[rn];W[mi];B[og];W[oe];B[qe];W[rd]
517
+;B[rf];W[pd];B[gm];W[gl];B[fm];W[fl];B[lj];W[mj];B[lk];W[ro]
518
+;B[hl];W[hk];B[ik];W[dk];B[bi];W[di];B[dj];W[dh];B[hj];W[gj]
519
+;B[li];W[lh];B[kh];W[lg];B[jn];W[do];B[cl];W[ij];B[gk];W[bl]
520
+;B[cm];W[hk];B[jk];W[lo];B[hi];W[hm];B[gk];W[bm];B[cn];W[hk]
521
+;B[il];W[cq];B[bq];W[ii];B[sm];W[jo];B[kn];W[fq];B[ep];W[cj]
522
+;B[bk];W[er];B[cr];W[gr];B[gk];W[fj];B[ko];W[kp];B[hr];W[jr]
523
+;B[nh];W[mh];B[mk];W[bb];B[da];W[jh];B[ic];W[id];B[hb];W[jb]
524
+;B[oj];W[fn];B[fs];W[fr];B[gs];W[es];B[hs];W[gn];B[kr];W[is]
525
+;B[dr];W[fi];B[bj];W[hd];B[gd];W[ln];B[lm];W[oi];B[oh];W[ni]
526
+;B[pi];W[ki];B[kj];W[ji];B[so];W[rq];B[if];W[jf];B[hh];W[hf]
527
+;B[he];W[ie];B[hg];W[ba];B[ca];W[sp];B[im];W[sn];B[rm];W[pe]
528
+;B[qf];W[if];B[hk];W[nj];B[nk];W[lr];B[mn];W[af];B[ag];W[ch]
529
+;B[bh];W[lp];B[ia];W[ja];B[ha];W[sf];B[sg];W[se];B[eh];W[fh]
530
+;B[in];W[ih];B[ae];W[so];B[af]"
531
+```
532
+
533
+Then we convert it into a matrix:
534
+
535
+```{r}
536
+str = gsub("\\n", "", str)
537
+step = strsplit(str, ";")[[1]]
538
+type = gsub("(B|W).*", "\\1", step)
539
+row = gsub("(B|W)\\[(.).\\]", "\\2", step)
540
+column = gsub("(B|W)\\[.(.)\\]", "\\2", step)
541
+
542
+mat = matrix(nrow = 19, ncol = 19)
543
+rownames(mat) = letters[1:19]
544
+colnames(mat) = letters[1:19]
545
+for(i in seq_along(row)) {
546
+    mat[row[i], column[i]] = type[i]
547
+}
548
+mat
549
+```
550
+
551
+Black and white stones are put based on the values in the matrix:
552
+
553
+```{r, fig.width = 8, fig.height = 8}
554
+Heatmap(mat, name = "go", rect_gp = gpar(type = "none"),
555
+    cell_fun = function(j, i, x, y, w, h, col) {
556
+        grid.rect(x, y, w, h, gp = gpar(fill = "#dcb35c", col = NA))
557
+        if(i == 1) {
558
+            grid.segments(x, y-h*0.5, x, y)
559
+        } else if(i == nrow(mat)) {
560
+            grid.segments(x, y, x, y+h*0.5)
561
+        } else {
562
+            grid.segments(x, y-h*0.5, x, y+h*0.5)
563
+        }
564
+        if(j == 1) {
565
+            grid.segments(x, y, x+w*0.5, y)        
566
+        } else if(j == ncol(mat)) {
567
+            grid.segments(x-w*0.5, y, x, y)
568
+        } else {
569
+            grid.segments(x-w*0.5, y, x+w*0.5, y)
570
+        }
571
+
572
+        if(i %in% c(4, 10, 16) & j %in% c(4, 10, 16)) {
573
+            grid.points(x, y, pch = 16, size = unit(2, "mm"))
574
+        }
575
+                
576
+        r = min(unit.c(w, h))*0.45
577
+        if(is.na(mat[i, j])) {
578
+        } else if(mat[i, j] == "W") {
579
+            grid.circle(x, y, r, gp = gpar(fill = "white", col = "white"))
580
+        } else if(mat[i, j] == "B") {
581
+            grid.circle(x, y, r, gp = gpar(fill = "black", col = "black"))
582
+        }
583
+    },
584
+    col = c("B" = "black", "W" = "white"),
585
+    show_row_names = FALSE, show_column_names = FALSE,
586
+    column_title = "One famous GO game",
587
+    heatmap_legend_param = list(title = "Player", at = c("B", "W"), 
588
+        labels = c("player1", "player2"), grid_border = "black")
589
+)
590
+```
591
+
500 592
 ## Session info
501 593
 
502 594
 ```{r}
Browse code

Merge branch 'master' into devel

git-svn-id: https://hedgehog.fhcrc.org/bioconductor/trunk/madman/Rpacks/ComplexHeatmap@108253 bc3139a8-67e5-0310-9ffc-ced21a209358

z.gu authored on 07/09/2015 20:39:32
Showing1 changed files
1 1
old mode 100644
2 2
new mode 100755
Browse code

Merge branch 'master' into devel

git-svn-id: https://hedgehog.fhcrc.org/bioconductor/trunk/madman/Rpacks/ComplexHeatmap@108252 bc3139a8-67e5-0310-9ffc-ced21a209358

z.gu authored on 07/09/2015 20:38:03
Showing1 changed files
... ...
@@ -216,9 +216,9 @@ of the dendrograms and size of the dendrograms.
216 216
 
217 217
 ```{r cluster_basic}
218 218
 Heatmap(mat, name = "foo", cluster_rows = FALSE)
219
-Heatmap(mat, name = "foo", show_column_hclust = FALSE)
220
-Heatmap(mat, name = "foo", row_hclust_side = "right")
221
-Heatmap(mat, name = "foo", column_hclust_height = unit(2, "cm"))
219
+Heatmap(mat, name = "foo", show_column_dend = FALSE)
220
+Heatmap(mat, name = "foo", row_dend_side = "right")
221
+Heatmap(mat, name = "foo", column_dend_height = unit(2, "cm"))
222 222
 ```
223 223
 
224 224
 There are three ways to specify distance metric for clustering:
... ...
@@ -294,7 +294,7 @@ Heatmap(mat, name = "foo", cluster_rows = as.dendrogram(diana(mat)),
294 294
 
295 295
 In the native `heatmap()` function, dendrograms on row and on column are reordered to let features with larger different
296 296
 separated more from each other, but according to my experience, the default reordering can not always give nice visualization.
297
-So the reordering for the dendrograms are turned off for `Heatmap()` function. 
297
+So by default the reordering for the dendrograms are turned off for `Heatmap()` function. 
298 298
 
299 299
 Besides the default reordering method, you can first generate a dendrogram and apply other reordering
300 300
 method and then send the reordered dendrogram to `cluster_rows` argument. 
... ...
@@ -304,17 +304,17 @@ Compare following three plots:
304 304
 ```{r cluster_dendsort, fig.width = 14}
305 305
 pushViewport(viewport(layout = grid.layout(nr = 1, nc = 3)))
306 306
 pushViewport(viewport(layout.pos.row = 1, layout.pos.col = 1))
307
-draw(Heatmap(mat, name = "foo", row_hclust_reorder = FALSE, column_title = "no reordering"), newpage = FALSE)
307
+draw(Heatmap(mat, name = "foo", row_dend_reorder = FALSE, column_title = "no reordering"), newpage = FALSE)
308 308
 upViewport()
309 309
 
310 310
 pushViewport(viewport(layout.pos.row = 1, layout.pos.col = 2))
311
-draw(Heatmap(mat, name = "foo", row_hclust_reorder = TRUE, column_title = "default reordering"), newpage = FALSE)
311
+draw(Heatmap(mat, name = "foo", row_dend_reorder = TRUE, column_title = "applied reordering"), newpage = FALSE)
312 312
 upViewport()
313 313
 
314 314
 library(dendsort)
315 315
 dend = dendsort(hclust(dist(mat)))
316 316
 pushViewport(viewport(layout.pos.row = 1, layout.pos.col = 3))
317
-draw(Heatmap(mat, name = "foo", cluster_rows = dend, row_hclust_reorder = FALSE, 
317
+draw(Heatmap(mat, name = "foo", cluster_rows = dend, row_dend_reorder = FALSE, 
318 318
     column_title = "reordering by dendsort"), newpage = FALSE)
319 319
 upViewport(2)
320 320
 ```
... ...
@@ -341,25 +341,25 @@ Heatmap(mat, name = "foo", cluster_rows = function(m) as.dendrogram(diana(m)),
341 341
 
342 342
 Clustering can help to adjust order in rows and in columns. But you can still set the order manually by `row_order`
343 343
 and `column_order`. Note you need to turn off clustering
344
-if you want to set order manually. `row_order` and `column_order` can also be set according to matrix row names and column names.
344
+if you want to set order manually. `row_order` and `column_order` can also be set according to matrix row names and column names if they exist.
345 345
 
346 346
 ```{r manual_order}
347 347
 Heatmap(mat, name = "foo", cluster_rows = FALSE, cluster_columns = FALSE, 
348 348
     row_order = 12:1, column_order = 10:1)
349 349
 ```
350 350
 
351
-Note `row_reorder` and `row_order` are different. `row_reorder` is applied on the dendrogram. Because for any node in the
351
+Note `row_dend_reorder` and `row_order` are different. `row_dend_reorder` is applied on the dendrogram. Because for any node in the
352 352
 dendrogram, rotating two leaves gives an identical dendrogram. Thus, reordering the dendrogram by automatically rotating sub-dendrogram
353 353
 at every node will help to separate elements with more difference to be farther from each other. While `row_order` is
354
-applied on the matrix and dendrograms should be suppressed.
354
+applied on the matrix and dendrograms are suppressed.
355 355
 
356 356
 ## Dimension names
357 357
 
358 358
 Side, visibility and graphic parameters for dimension names can be set as follows.
359 359
 
360 360
 ```{r dimension_name}
361
-Heatmap(mat, name = "foo", row_names_side = "left", row_hclust_side = "right", 
362
-    column_names_side = "top", column_hclust_side = "bottom")
361
+Heatmap(mat, name = "foo", row_names_side = "left", row_dend_side = "right", 
362
+    column_names_side = "top", column_dend_side = "bottom")
363 363
 Heatmap(mat, name = "foo", show_row_names = FALSE)
364 364
 Heatmap(mat, name = "foo", row_names_gp = gpar(fontsize = 20))
365 365
 Heatmap(mat, name = "foo", row_names_gp = gpar(col = c(rep("red", 4), rep("blue", 8))))
... ...
@@ -376,7 +376,7 @@ example in the [**Heatmap Annotation**](s4.heatmap_annotation.html) vignette).
376 376
 
377 377
 A heatmap can be split by rows. This will enhance the visualization of group separation in the heatmap.
378 378
 The `km` argument with a value larger than 1 means applying a k-means clustering on rows and clustering
379
-is applied on every k-means clusters.
379
+is applied on every k-means cluster.
380 380
 
381 381
 ```{r k_means}
382 382
 Heatmap(mat, name = "foo", km = 2)
... ...
@@ -420,7 +420,8 @@ Heatmap(mat, name = "foo", split = paste0("pam", pa$clustering), gap = unit(5, "
420 420
 Character matrix can only be split by `split` argument.
421 421
 
422 422
 ```{r split_discrete_matrix}
423
-Heatmap(discrete_mat, name = "foo", split = rep(letters[1:2], each = 5))
423
+Heatmap(discrete_mat, name = "foo", col = 1:4,
424
+    split = rep(letters[1:2], each = 5))
424 425
 ```
425 426
 
426 427
 When split is applied on rows, graphic parameters for row title and row names can be specified as same
Browse code

resolve conflict from master branch

git-svn-id: https://hedgehog.fhcrc.org/bioconductor/trunk/madman/Rpacks/ComplexHeatmap@108131 bc3139a8-67e5-0310-9ffc-ced21a209358

z.gu authored on 03/09/2015 20:32:44
Showing1 changed files
... ...
@@ -1,7 +1,6 @@
1 1
 <!--
2 2
 %\VignetteEngine{knitr}
3
-%\VignetteIndexEntry{Making a single heatmap}
4
-%\VignetteIndexEntry{2.Making a single heatmap}
3
+%\VignetteIndexEntry{2. Making a single heatmap}
5 4
 -->
6 5
 
7 6
 Making A Single Heatmap
... ...
@@ -293,27 +292,29 @@ Heatmap(mat, name = "foo", cluster_rows = as.dendrogram(diana(mat)),
293 292
    cluster_columns = as.dendrogram(agnes(t(mat))))
294 293
 ```
295 294
 
296
-By default, dendrograms on row and on column are reordered to let features with larger different
297
-separated more from each other (to behave same as the native `heatmap()`). 
298
-You can first generate a dendrogram and apply other reordering
299
-method. But remember you need to set `row_reorder` to `FALSE` to turn off the default reordering.
295
+In the native `heatmap()` function, dendrograms on row and on column are reordered to let features with larger different
296
+separated more from each other, but according to my experience, the default reordering can not always give nice visualization.
297
+So the reordering for the dendrograms are turned off for `Heatmap()` function. 
298
+
299
+Besides the default reordering method, you can first generate a dendrogram and apply other reordering
300
+method and then send the reordered dendrogram to `cluster_rows` argument. 
300 301
 
301 302
 Compare following three plots:
302 303
 
303 304
 ```{r cluster_dendsort, fig.width = 14}
304 305
 pushViewport(viewport(layout = grid.layout(nr = 1, nc = 3)))
305 306
 pushViewport(viewport(layout.pos.row = 1, layout.pos.col = 1))
306
-draw(Heatmap(mat, name = "foo", row_reorder = FALSE, column_title = "no reordering"), newpage = FALSE)
307
+draw(Heatmap(mat, name = "foo", row_hclust_reorder = FALSE, column_title = "no reordering"), newpage = FALSE)
307 308
 upViewport()
308 309
 
309 310
 pushViewport(viewport(layout.pos.row = 1, layout.pos.col = 2))
310
-draw(Heatmap(mat, name = "foo", column_title = "default reordering"), newpage = FALSE)
311
+draw(Heatmap(mat, name = "foo", row_hclust_reorder = TRUE, column_title = "default reordering"), newpage = FALSE)
311 312
 upViewport()
312 313
 
313 314
 library(dendsort)
314 315
 dend = dendsort(hclust(dist(mat)))
315 316
 pushViewport(viewport(layout.pos.row = 1, layout.pos.col = 3))
316
-draw(Heatmap(mat, name = "foo", cluster_rows = dend, row_reorder = FALSE, 
317
+draw(Heatmap(mat, name = "foo", cluster_rows = dend, row_hclust_reorder = FALSE, 
317 318
     column_title = "reordering by dendsort"), newpage = FALSE)
318 319
 upViewport(2)
319 320
 ```
Browse code

fixed vignette headers

git-svn-id: https://hedgehog.fhcrc.org/bioconductor/trunk/madman/Rpacks/ComplexHeatmap@107722 bc3139a8-67e5-0310-9ffc-ced21a209358

z.gu authored on 24/08/2015 15:52:58
Showing1 changed files
... ...
@@ -1,10 +1,7 @@
1 1
 <!--
2 2
 %\VignetteEngine{knitr}
3
-<<<<<<< HEAD
4 3
 %\VignetteIndexEntry{Making a single heatmap}
5
-=======
6 4
 %\VignetteIndexEntry{2.Making a single heatmap}
7
->>>>>>> master
8 5
 -->
9 6
 
10 7
 Making A Single Heatmap
Browse code

resolve conflicts

From: Zuguang Gu <jokergoo@gmail.com>

git-svn-id: https://hedgehog.fhcrc.org/bioconductor/trunk/madman/Rpacks/ComplexHeatmap@107686 bc3139a8-67e5-0310-9ffc-ced21a209358

z.gu authored on 22/08/2015 12:00:46
Showing1 changed files
... ...
@@ -1,6 +1,10 @@
1 1
 <!--
2 2
 %\VignetteEngine{knitr}
3
+<<<<<<< HEAD
3 4
 %\VignetteIndexEntry{Making a single heatmap}
5
+=======
6
+%\VignetteIndexEntry{2.Making a single heatmap}
7
+>>>>>>> master
4 8
 -->
5 9
 
6 10
 Making A Single Heatmap
Browse code

Commit made by the Bioconductor Git-SVN bridge.

Commit id: 25191b4dc0bd4242c260ef5abd112d4bdd0ea887

add oncoPrint() function



git-svn-id: https://hedgehog.fhcrc.org/bioconductor/trunk/madman/Rpacks/ComplexHeatmap@107561 bc3139a8-67e5-0310-9ffc-ced21a209358

z.gu authored on 18/08/2015 22:21:59
Showing1 changed files
... ...
@@ -117,8 +117,8 @@ mat_with_na[sample(c(TRUE, FALSE), nrow(mat)*ncol(mat), replace = TRUE, prob = c
117 117
 Heatmap(mat_with_na, na_col = "orange")
118 118
 ```
119 119
 
120
-Color space is important for interpolating colors. By default, colors are linearly interpolated in [LAB](https://en.wikipedia.org/wiki/Lab_color_space), but you can select the color space in `colorRamp2()` function. Compare following two plots
121
-(`+` operation on two heatmaps will be introduced in [**Making a list of heatmaps**](a3.a_list_of_heatmap.html) vignette):
120
+Color space is important for interpolating colors. By default, colors are linearly interpolated in [LAB color space](https://en.wikipedia.org/wiki/Lab_color_space), but you can select the color space in `colorRamp2()` function. Compare following two plots
121
+(`+` operation on two heatmaps will be introduced in [**Making a list of heatmaps**](s3.a_list_of_heatmaps.html) vignette):
122 122
 
123 123
 ```{r, fig.width = 10}
124 124
 f1 = colorRamp2(seq(min(mat), max(mat), length = 3), c("blue", "#EEEEEE", "red"))
... ...
@@ -127,22 +127,39 @@ Heatmap(mat, col = f1, column_title = "LAB color space") +
127 127
 Heatmap(mat, col = f2, column_title = "RGB color space")
128 128
 ```
129 129
 
130
-On following figure, corresponding values change evenly on x-axis, you can see how colors change under different
131
-color spaces. Choosing a proper color space is a little bit subjective and it depends on specific data and color theme.
130
+On following figure, corresponding values change evenly on the folded axis, you can see how colors change under different
131
+color spaces (the plot is made by **HilbertCurve** package). Choosing a proper color space is a little bit 
132
+subjective and it depends on specific data and color theme.
132 133
 Sometimes you need to try several color spaces to determine one which can best reveal potential structure of your data.
133 134
 
134
-```{r, fig.width = 10, fig.height = 4}
135
-space = c("RGB", "LAB", "XYZ", "sRGB", "LUV")
136
-x = seq(-1, 1, length = 100)
137 135
 
138
-par(xpd = NA)
139
-plot(NULL, xlim = c(-1, 1), ylim = c(0.5, length(space)-0.5), type = "n", axes = FALSE, ann = FALSE)
136
+```{r, fig.width = 14, fig.height = 14/5, echo = FALSE, message = FALSE}
137
+suppressPackageStartupMessages(library(HilbertCurve))
138
+space = c("RGB", "LAB", "XYZ", "sRGB", "LUV")
139
+pushViewport(viewport(layout = grid.layout(nr = 1, nc = length(space))))
140 140
 for(i in seq_along(space)) {
141
-    f = colorRamp2(c(-1, 0, 1), c("blue", "#EEEEEE", "red"), space = space[i])
142
-    rect(x - 1/100, i - 0.5, x + 1/100, i + 0.5, col = f(x), border = NA)
143
-    text(1, i, space[i], adj = c(-0.2, 0.5))
141
+    pushViewport(viewport(layout.pos.row = 1, layout.pos.col = i))
142
+    hc = HilbertCurve(1, 100, level = 4, newpage = FALSE, title = space[i])
143
+    ir = IRanges(start = 1:99, end = 2:100)
144
+    f = colorRamp2(c(-1, 0, 1), c("green", "black", "red"), space = space[i])
145
+    col = f(seq(-1, 1, length = 100))
146
+    hc_points(hc, ir, np = 3, gp = gpar(col = col, fill = col))
147
+    upViewport()
144 148
 }
145
-axis(side = 1)
149
+upViewport()
150
+grid.newpage()
151
+pushViewport(viewport(layout = grid.layout(nr = 1, nc = length(space))))
152
+for(i in seq_along(space)) {
153
+    pushViewport(viewport(layout.pos.row = 1, layout.pos.col = i))
154
+    hc = HilbertCurve(1, 100, level = 4, newpage = FALSE, title = space[i])
155
+    ir = IRanges(start = 1:99, end = 2:100)
156
+    f = colorRamp2(c(-1, 0, 1), c("blue", "white", "red"), space = space[i])
157
+    col = f(seq(-1, 1, length = 100))
158
+    hc_points(hc, ir, np = 3, gp = gpar(col = col, fill = col))
159
+    upViewport()
160
+}
161
+upViewport()
162
+
146 163
 ```
147 164
 
148 165
 ## Titles
... ...
@@ -150,14 +167,14 @@ axis(side = 1)
150 167
 The name of the heatmap by default is used as the title of the heatmap legend.
151 168
 The name also plays as a unique id if you plot more than one heatmaps together.
152 169
 Later we can use this name to go to the corresponding heatmap to add more graphics 
153
-(see [**Heatmap Decoration**](5.heatmap_decoration.html) vignette).
170
+(see [**Heatmap Decoration**](s6.heatmap_decoration.html) vignette).
154 171
 
155 172
 ```{r with_matrix_name}
156 173
 Heatmap(mat, name = "foo")
157 174
 ```
158 175
 
159 176
 The title of the heatmap legend can be modified by `heatmap_legend_param` 
160
-(see [**Heatmap and Annotation Legends**](4.legend.html) vignette
177
+(see [**Heatmap and Annotation Legends**](s5.legend.html) vignette
161 178
 for more control on the legend).
162 179
 
163 180
 ```{r heatmap_legend_title}
... ...
@@ -348,10 +365,10 @@ Heatmap(mat, name = "foo", row_names_gp = gpar(col = c(rep("red", 4), rep("blue"
348 365
 
349 366
 Currently, rotations for column names and row names are not supported (or maybe in the future versions). Because
350 367
 after the text rotation, the dimension names will go inside other heatmap components
351
-which will mess up the heatmap layout. However, as will be introduced in [**Heatmap Annotation**](3.heatmap_annotation.html)
368
+which will mess up the heatmap layout. However, as will be introduced in [**Heatmap Annotation**](s4.heatmap_annotation.html)
352 369
 vignette, text rotation is allowed in the heatmap annotations. Thus, users can provide a row annotation
353 370
 or column annotation which only contains rotated text to simulate rotated row/column names (You will see the 
354
-example in the [**Heatmap Annotation**](3.heatmap_annotation.html) vignette).
371
+example in the [**Heatmap Annotation**](s4.heatmap_annotation.html) vignette).
355 372
 
356 373
 ## Split heatmap by rows
357 374
 
Browse code

Commit made by the Bioconductor Git-SVN bridge.

Commit id: 1de356e1d1343725223e03ff696f931d80b2842b

Merge branch 'master' of https://github.com/jokergoo/mheatmap


Commit id: 478962957a34b7a5e87c8336989bae3df54f9559

change default colors



git-svn-id: https://hedgehog.fhcrc.org/bioconductor/trunk/madman/Rpacks/ComplexHeatmap@107356 bc3139a8-67e5-0310-9ffc-ced21a209358

z.gu authored on 12/08/2015 22:03:22
Showing1 changed files
... ...
@@ -66,7 +66,7 @@ In this case, user should provide a color mapping function. A color mapping func
66 66
 should accept a vector of values and return a vector of corresponding colors. The `colorRamp2()` from
67 67
 the **circlize** package is helpful for generating such functions. The two arguments for `colorRamp2()`
68 68
 is a vector of breaks values and corresponding colors. Currently `colorRamp2()` linearly interpolates
69
-colors in every interval through RGB color space.
69
+colors in every interval through LAB color space.
70 70
 
71 71
 In following example, values between -3 and 3 are 
72 72
 linearly interpolated to obtain corresponding colors, values larger than 3 are all mapped to red and values less than -3 are
... ...
@@ -117,6 +117,34 @@ mat_with_na[sample(c(TRUE, FALSE), nrow(mat)*ncol(mat), replace = TRUE, prob = c
117 117
 Heatmap(mat_with_na, na_col = "orange")
118 118
 ```
119 119
 
120
+Color space is important for interpolating colors. By default, colors are linearly interpolated in [LAB](https://en.wikipedia.org/wiki/Lab_color_space), but you can select the color space in `colorRamp2()` function. Compare following two plots
121
+(`+` operation on two heatmaps will be introduced in [**Making a list of heatmaps**](a3.a_list_of_heatmap.html) vignette):
122
+
123
+```{r, fig.width = 10}
124
+f1 = colorRamp2(seq(min(mat), max(mat), length = 3), c("blue", "#EEEEEE", "red"))
125
+f2 = colorRamp2(seq(min(mat), max(mat), length = 3), c("blue", "#EEEEEE", "red"), space = "RGB")
126
+Heatmap(mat, col = f1, column_title = "LAB color space") +
127
+Heatmap(mat, col = f2, column_title = "RGB color space")
128
+```
129
+
130
+On following figure, corresponding values change evenly on x-axis, you can see how colors change under different
131
+color spaces. Choosing a proper color space is a little bit subjective and it depends on specific data and color theme.
132
+Sometimes you need to try several color spaces to determine one which can best reveal potential structure of your data.
133
+
134
+```{r, fig.width = 10, fig.height = 4}
135
+space = c("RGB", "LAB", "XYZ", "sRGB", "LUV")
136
+x = seq(-1, 1, length = 100)
137
+
138
+par(xpd = NA)
139
+plot(NULL, xlim = c(-1, 1), ylim = c(0.5, length(space)-0.5), type = "n", axes = FALSE, ann = FALSE)
140
+for(i in seq_along(space)) {
141
+    f = colorRamp2(c(-1, 0, 1), c("blue", "#EEEEEE", "red"), space = space[i])
142
+    rect(x - 1/100, i - 0.5, x + 1/100, i + 0.5, col = f(x), border = NA)
143
+    text(1, i, space[i], adj = c(-0.2, 0.5))
144
+}
145
+axis(side = 1)
146
+```
147
+
120 148
 ## Titles
121 149
 
122 150
 The name of the heatmap by default is used as the title of the heatmap legend.
Browse code

Commit made by the Bioconductor Git-SVN bridge.

Commit id: 262e3960558c1f61b986f5be7a2ffd4599f704fa

comprehensive modifications



git-svn-id: https://hedgehog.fhcrc.org/bioconductor/trunk/madman/Rpacks/ComplexHeatmap@107311 bc3139a8-67e5-0310-9ffc-ced21a209358

z.gu authored on 10/08/2015 22:17:54
Showing1 changed files
1 1
new file mode 100644
... ...
@@ -0,0 +1,456 @@
1
+<!--
2
+%\VignetteEngine{knitr}
3
+%\VignetteIndexEntry{Making a single heatmap}
4
+-->
5
+
6
+Making A Single Heatmap
7
+========================================
8
+
9
+**Author**: Zuguang Gu ( z.gu@dkfz.de )
10
+
11
+**Date**: `r Sys.Date()`
12
+
13
+-------------------------------------------------------------
14
+
15
+```{r global_settings, echo = FALSE, message = FALSE}
16
+library(markdown)
17
+options(markdown.HTML.options = c(options('markdown.HTML.options')[[1]], "toc"))
18
+
19
+library(knitr)
20
+knitr::opts_chunk$set(
21
+    error = FALSE,
22
+    tidy  = FALSE,
23
+    message = FALSE,
24
+    fig.align = "center",
25
+    fig.width = 5,
26
+    fig.height = 5)
27
+options(markdown.HTML.stylesheet = "custom.css")
28
+
29
+options(width = 100)
30
+```
31
+
32
+A single heatmap is mostly used for a quick view of the data. It is a special case of 
33
+a heatmap list which only contains one heatmap. Compare to available tools, **ComplexHeatmap** package provides a more flexible
34
+way to support visualization of a single heatmap. In following examples, we will demonstrate
35
+how to set parameters to visualize a single heatmap.
36
+
37
+First let's load packages and generate a random matrix:
38
+
39
+```{r data}
40
+library(ComplexHeatmap)
41
+library(circlize)
42
+
43
+set.seed(123)
44
+
45
+mat = cbind(rbind(matrix(rnorm(16, -1), 4), matrix(rnorm(32, 1), 8)),
46
+            rbind(matrix(rnorm(24, 1), 4), matrix(rnorm(48, -1), 8)))
47
+
48
+# permute the rows and columns
49
+mat = mat[sample(nrow(mat), nrow(mat)), sample(ncol(mat), ncol(mat))]
50
+
51
+rownames(mat) = paste0("R", 1:12)
52
+colnames(mat) = paste0("C", 1:10)
53
+```
54
+
55
+Plot the heatmap with default settings. The default style of the heatmap is quite the same
56
+as those generated by other similar heatmap functions.
57
+
58
+```{r default}
59
+Heatmap(mat)
60
+```
61
+
62
+## Colors
63
+
64
+In most cases, the heatmap visualizes a matrix with continuous values.
65
+In this case, user should provide a color mapping function. A color mapping function
66
+should accept a vector of values and return a vector of corresponding colors. The `colorRamp2()` from
67
+the **circlize** package is helpful for generating such functions. The two arguments for `colorRamp2()`
68
+is a vector of breaks values and corresponding colors. Currently `colorRamp2()` linearly interpolates
69
+colors in every interval through RGB color space.
70
+
71
+In following example, values between -3 and 3 are 
72
+linearly interpolated to obtain corresponding colors, values larger than 3 are all mapped to red and values less than -3 are
73
+all mapped to green (so the color mapping function demonstrated here is robust to outliers).
74
+
75
+```{r color_fun}
76
+mat2 = mat
77
+mat2[1, 1] = 100000
78
+Heatmap(mat2, col = colorRamp2(c(-3, 0, 3), c("green", "white", "red")), 
79
+    cluster_rows = FALSE, cluster_columns = FALSE)
80
+```
81
+
82
+If the matrix is continuous, you can also provide a vector of colors and colors will be interpolated according to the 'k'th quantile.
83
+But remember this method is not robust to outliers.
84
+
85
+```{r color_vector}
86
+Heatmap(mat, col = rev(rainbow(10)))
87
+```
88
+
89
+If the matrix contains discrete values (either numeric or character), colors should be specified as
90
+a named vector to make it possible for the mapping from discrete values to colors. If there is no name
91
+for the color, the order of colors corresponds to the order of `unique(mat)`.
92
+
93
+```{r discrete_matrix}
94
+discrete_mat = matrix(sample(1:4, 100, replace = TRUE), 10, 10)
95
+colors = structure(circlize::rand_color(4), names = c("1", "2", "3", "4"))
96
+Heatmap(discrete_mat, col = colors)
97
+```
98
+
99
+Or a character matrix:
100
+
101
+```{r discrete_character_matrix}
102
+discrete_mat = matrix(sample(letters[1:4], 100, replace = TRUE), 10, 10)
103
+colors = structure(circlize::rand_color(4), names = letters[1:4])
104
+Heatmap(discrete_mat, col = colors)
105
+```
106
+
107
+As you see, for the numeric matrix (no matter it is continuous mapping or discrete mapping), 
108
+by default clustering is applied on both dimensions while
109
+for character matrix, clustering is suppressed.
110
+
111
+``NA`` is allowed in the heatmap. You can control the color of `NA` by `na_col` argument. 
112
+The matrix which contains `NA` can also be clustered by `Heatmap()` but giving warning messages.
113
+
114
+```{r na_value}
115
+mat_with_na = mat
116
+mat_with_na[sample(c(TRUE, FALSE), nrow(mat)*ncol(mat), replace = TRUE, prob = c(1, 9))] = NA
117
+Heatmap(mat_with_na, na_col = "orange")
118
+```
119
+
120
+## Titles
121
+
122
+The name of the heatmap by default is used as the title of the heatmap legend.
123
+The name also plays as a unique id if you plot more than one heatmaps together.
124
+Later we can use this name to go to the corresponding heatmap to add more graphics 
125
+(see [**Heatmap Decoration**](5.heatmap_decoration.html) vignette).
126
+
127
+```{r with_matrix_name}
128
+Heatmap(mat, name = "foo")
129
+```
130
+
131
+The title of the heatmap legend can be modified by `heatmap_legend_param` 
132
+(see [**Heatmap and Annotation Legends**](4.legend.html) vignette
133
+for more control on the legend).
134
+
135
+```{r heatmap_legend_title}
136
+Heatmap(mat, heatmap_legend_param = list(title = "legend"))
137
+```
138
+
139
+You can set heatmap titles to be put either by the rows or by the columns. Note at a same time
140
+you can only put e.g. column title either on the top or at the bottom of the heatmap.
141
+The graphic parameters can be set by `row_title_gp` and `column_title_gp` respectively.
142
+Please remember you should use `gpar()` to specify graphic parameters.
143
+
144
+```{r row_column_title}
145
+Heatmap(mat, name = "foo", column_title = "I am a column title", 
146
+    row_title = "I am a row title")
147
+Heatmap(mat, name = "foo", column_title = "I am a column title at the bottom", 
148
+    column_title_side = "bottom")
149
+Heatmap(mat, name = "foo", column_title = "I am a big column title", 
150
+    column_title_gp = gpar(fontsize = 20, fontface = "bold"))
151
+```
152
+
153
+Roatations for titles can be set by `row_title_rot` and `column_title_rot`, but only horizontal and vertical 
154
+rotations are allowed.
155
+
156
+```{r title_rotation}
157
+Heatmap(mat, name = "foo", row_title = "row title", row_title_rot = 0)
158
+```
159
+
160
+## Clustering
161
+
162
+Clustering may be the key feature of the heatmap visualization. In **ComplexHeatmap** package,
163
+clustering is supported with high flexibility. You can specify the 
164
+clustering either by a pre-defined method (e.g. "eulidean" or "pearson"), or by a distance function, or by a object that already
165
+contains clustering, or directly by a clustering function. It is also possible to render 
166
+your dendrograms with different colors and styles for different branches for better revealing
167
+structures of your data.
168
+
169
+First there are general settings for the clustering, e.g. whether show dendrograms, side
170
+of the dendrograms and size of the dendrograms.
171
+
172
+```{r cluster_basic}
173
+Heatmap(mat, name = "foo", cluster_rows = FALSE)