@@ -2,14 +2,14 @@ Package: ComplexHeatmap

 Type: Package

 Title: Making Complex Heatmaps

 Version: 1.11.5

-Date: 2016-6-7

+Date: 2016-6-14

 Author: Zuguang Gu

 Maintainer: Zuguang Gu <z.gu@dkfz.de>

 Depends: R (>= 3.1.2), grid, graphics, stats, grDevices

 Imports: methods, circlize (>= 0.3.4), GetoptLong, colorspace,

     RColorBrewer, dendextend (>= 1.0.1), GlobalOptions (>= 0.0.10)

 Suggests: testthat (>= 0.3), knitr, markdown, cluster, MASS, pvclust, 

-    dendsort, HilbertCurve, Cairo, png, jpeg, tiff

+    dendsort, HilbertCurve, Cairo, png, jpeg, tiff, fastcluster

 VignetteBuilder: knitr

 Description: Complex heatmaps are efficient to visualize associations 

     between different sources of data sets and reveal potential structures. 

@@ -18,6 +18,6 @@ Description: Complex heatmaps are efficient to visualize associations

 biocViews: Software, Visualization, Sequencing

 URL: https://github.com/jokergoo/ComplexHeatmap

 License: GPL (>= 2)

-Packaged: 2016-6-7 00:00:00 UTC; Administrator

+Packaged: 2016-6-14 00:00:00 UTC; Administrator

 Repository: Bioconductor

-Date/Publication: 2016-6-7 00:00:00

+Date/Publication: 2016-6-14 00:00:00

@@ -648,6 +648,12 @@ setMethod(f = "make_column_cluster",

     signature = "Heatmap",

     definition = function(object) {

+    if(ht_global_opt("fast_hclust")) {

+        hclust = fastcluster::hclust

+    } else {

+        hclust = stats::hclust

+    }

+    

     mat = object@matrix

     distance = object@column_dend_param$distance

     method = object@column_dend_param$method

@@ -730,6 +736,12 @@ setMethod(f = "make_row_cluster",

     signature = "Heatmap",

     definition = function(object) {

+    if(ht_global_opt("fast_hclust")) {

+        hclust = fastcluster::hclust

+    } else {

+        hclust = stats::hclust

+    }

+

     mat = object@matrix

     distance = object@row_dend_param$distance

     method = object@row_dend_param$method

@@ -57,6 +57,7 @@ HeatmapAnnotation = setClass("HeatmapAnnotation",

 # -annotation_name_gp graphic parameters for anntation names. Graphic paramters can be vectors.

 # -annotation_name_offset offset to the annotations, `grid::unit` object. The value can be a vector.

 # -annotation_name_side side of the annotation names.

+# -annotation_name_rot rotation of the annotation names, can only take values in ``c(00, 90, 180, 270)``. The value can be a vector.

 #

 # == details

 # The simple annotations are defined by ``df`` and ``col`` arguments. Complex annotations are

@@ -85,7 +86,8 @@ HeatmapAnnotation = function(df, name, col, na_col = "grey",

 	show_annotation_name = FALSE,

 	annotation_name_gp = gpar(),

 	annotation_name_offset = unit(2, "mm"),

-	annotation_name_side = ifelse(which == "column", "right", "bottom")) {

+	annotation_name_side = ifelse(which == "column", "right", "bottom"),

+	annotation_name_rot = ifelse(which == "column", 0, 90)) {

 	.Object = new("HeatmapAnnotation")

@@ -104,7 +106,7 @@ HeatmapAnnotation = function(df, name, col, na_col = "grey",

     called_args = names(arg_list)

     anno_args = setdiff(called_args, c("name", "col", "na_col", "annotation_legend_param", "show_legend", "which", 

     	                             "annotation_height", "annotation_width", "height", "width", "gp", "gap",

-    	                             "show_annotation_name", "annotation_name_gp", "annotation_name_offset", "annotation_name_side"))

+    	                             "show_annotation_name", "annotation_name_gp", "annotation_name_offset", "annotation_name_side", "annotation_name_rot"))

     if(any(anno_args == "")) stop("annotations should have names.")

     if(any(duplicated(anno_args))) stop("names of annotations should be unique.")

     anno_arg_list = list(...)

@@ -170,6 +172,9 @@ HeatmapAnnotation = function(df, name, col, na_col = "grey",

     if(length(annotation_name_side) == 1) {

     	annotation_name_side = rep(annotation_name_side, n_total_anno)

     }

+    if(length(annotation_name_rot) == 1) {

+    	annotation_name_rot = rep(annotation_name_rot, n_total_anno)

+    }

     annotation_name_gp = recycle_gp(annotation_name_gp, n_total_anno)

 	i_simple = 0

@@ -195,7 +200,7 @@ HeatmapAnnotation = function(df, name, col, na_col = "grey",

 		        	anno_list = c(anno_list, list(SingleAnnotation(name = anno_name[i], value = df[, i], na_col = na_col, which = which, 

 		        		show_legend = show_legend[i_simple + i], gp = gp, legend_param = annotation_legend_param[[i_simple + i]],

 		        		show_name = show_annotation_name[i_anno], name_gp = subset_gp(annotation_name_gp, i_anno), 

-		        		name_offset = annotation_name_offset[i_anno], name_side = annotation_name_side[i_anno])))

+		        		name_offset = annotation_name_offset[i_anno], name_side = annotation_name_side[i_anno], name_rot = annotation_name_rot[i_anno])))

 		        }

 		    } else {

 		        for(i in seq_len(n_anno)) {

@@ -204,12 +209,12 @@ HeatmapAnnotation = function(df, name, col, na_col = "grey",

 		        		anno_list = c(anno_list, list(SingleAnnotation(name = anno_name[i], value = df[, i], na_col = na_col, which = which, 

 		        			show_legend = show_legend[i_simple + i], gp = gp, legend_param = annotation_legend_param[[i_simple + i]],

 		        			show_name = show_annotation_name[i_anno], name_gp = subset_gp(annotation_name_gp, i_anno), 

-		        			name_offset = annotation_name_offset[i_anno], name_side = annotation_name_side[i_anno])))

+		        			name_offset = annotation_name_offset[i_anno], name_side = annotation_name_side[i_anno], name_rot = annotation_name_rot[i_anno])))

 		        	} else {

 		        		anno_list = c(anno_list, list(SingleAnnotation(name = anno_name[i], value = df[, i], na_col = na_col, col = col[[ anno_name[i] ]], 

 		        			which = which, show_legend = show_legend[i_simple + i], gp = gp, legend_param = annotation_legend_param[[i_simple + i]],

 		        			show_name = show_annotation_name[i_anno], name_gp = subset_gp(annotation_name_gp, i_anno), 

-		        			name_offset = annotation_name_offset[i_anno], name_side = annotation_name_side[i_anno])))

+		        			name_offset = annotation_name_offset[i_anno], name_side = annotation_name_side[i_anno], name_rot = annotation_name_rot[i_anno])))

 		        	}

 		        }

 		    }

@@ -219,7 +224,7 @@ HeatmapAnnotation = function(df, name, col, na_col = "grey",

 			if(inherits(anno_arg_list[[ag]], "function")) {

 				anno_list = c(anno_list, list(SingleAnnotation(name = ag, fun = anno_arg_list[[ag]], which = which,

 					show_name = show_annotation_name[i_anno], name_gp = subset_gp(annotation_name_gp, i_anno), 

-		        	name_offset = annotation_name_offset[i_anno], name_side = annotation_name_side[i_anno])))

+		        	name_offset = annotation_name_offset[i_anno], name_side = annotation_name_side[i_anno], name_rot = annotation_name_rot[i_anno])))

 			} else if(is.atomic(anno_arg_list[[ag]])) {

 			    if(is.null(simple_length)) {

@@ -231,18 +236,18 @@ HeatmapAnnotation = function(df, name, col, na_col = "grey",

 			        anno_list = c(anno_list, list(SingleAnnotation(name = ag, value = anno_arg_list[[ag]], na_col = na_col, which = which, 

 			        	show_legend = show_legend[i_simple + 1], gp = gp, legend_param = annotation_legend_param[[i_simple + 1]],

 			        	show_name = show_annotation_name[i_anno], name_gp = subset_gp(annotation_name_gp, i_anno), 

-		        		name_offset = annotation_name_offset[i_anno], name_side = annotation_name_side[i_anno])))

+		        		name_offset = annotation_name_offset[i_anno], name_side = annotation_name_side[i_anno], name_rot = annotation_name_rot[i_anno])))

 			    } else {

 			        if(is.null(col[[ ag ]])) { # if the color is not provided

 			        	anno_list = c(anno_list, list(SingleAnnotation(name = ag, value = anno_arg_list[[ag]], na_col = na_col, which = which, 

 			        		show_legend = show_legend[i_simple + 1], gp = gp, legend_param = annotation_legend_param[[i_simple + 1]],

 			        		show_name = show_annotation_name[i_anno], name_gp = subset_gp(annotation_name_gp, i_anno), 

-		        		name_offset = annotation_name_offset[i_anno], name_side = annotation_name_side[i_anno])))

+		        		name_offset = annotation_name_offset[i_anno], name_side = annotation_name_side[i_anno], name_rot = annotation_name_rot[i_anno])))

 			        } else {

 			        	anno_list = c(anno_list, list(SingleAnnotation(name = ag, value = anno_arg_list[[ag]], na_col = na_col, col = col[[ ag ]], 

 			        		which = which, show_legend = show_legend[i_simple + 1], gp = gp, legend_param = annotation_legend_param[[i_simple + 1]],

 			        		show_name = show_annotation_name[i_anno], name_gp = subset_gp(annotation_name_gp, i_anno), 

-		        			name_offset = annotation_name_offset[i_anno], name_side = annotation_name_side[i_anno])))

+		        			name_offset = annotation_name_offset[i_anno], name_side = annotation_name_side[i_anno], name_rot = annotation_name_rot[i_anno])))

 			        }

 			    }

 			    i_simple = i_simple + 1

@@ -311,12 +316,11 @@ HeatmapAnnotation = function(df, name, col, na_col = "grey",

 #

 # == param

 # -... pass to `HeatmapAnnotation`

-# -width default width of the row annotations

 #

 # == details

 # The function is identical to 

 #

-#     HeatmapAnnotation(..., which = "row", width = width)

+#     HeatmapAnnotation(..., which = "row")

 #

 # == value

 # A `HeatmapAnnotation-class` object.

@@ -324,8 +328,8 @@ HeatmapAnnotation = function(df, name, col, na_col = "grey",

 # == author

 # Zuguang Gu <z.gu@dkfz.de>

 #

-rowAnnotation = function(..., width = unit(1, "cm")) {

-	HeatmapAnnotation(..., which = "row", width = width)

+rowAnnotation = function(...) {

+	HeatmapAnnotation(..., which = "row")

 }

 # == title

@@ -65,6 +65,7 @@ SingleAnnotation = setClass("SingleAnnotation",

 # -name_gp graphic parameters for annotation name

 # -name_offset offset to the annotation, a `grid::unit` object

 # -name_side 'right' and 'left' for column annotations and 'top' and 'bottom' for row annotations

+# -name_rot rotation of the annotation name, can only take values in ``c(00, 90, 180, 270)``.

 #

 # == details

 # The most simple annotation is one row or one column grids in which different colors

@@ -99,10 +100,11 @@ SingleAnnotation = function(name, value, col, fun,

 	show_legend = TRUE, 

 	gp = gpar(col = NA), 

 	legend_param = list(),

-	show_name = TRUE, 

+	show_name = FALSE, 

 	name_gp = gpar(fontsize = 12),

 	name_offset = unit(2, "mm"),

-	name_side = ifelse(which == "column", "right", "bottom")) {

+	name_side = ifelse(which == "column", "right", "bottom"),

+    name_rot = ifelse(which == "column", 0, 90)) {

 	# re-define some of the argument values according to global settings

     called_args = names(as.list(match.call())[-1])

@@ -131,7 +133,11 @@ SingleAnnotation = function(name, value, col, fun,

     }

     .Object@name = name

-    name_rot = ifelse(which == "column", 0, 90)

+    if(!name_rot %in% c(0, 90, 180, 270)) {

+        stop("`name_rot` can only take values in c(0, 90, 180, 270)")

+    }

+

+    

     if(which == "column") {

     	if(!name_side %in% c("left", "right")) {

     		stop("`name_side` should be 'left' or 'right' when it is a column annotation.")

@@ -139,11 +145,27 @@ SingleAnnotation = function(name, value, col, fun,

     	if(name_side == "left") {

     		name_x = unit(0, "npc") - name_offset

     		name_y = unit(0.5, "npc")

-    		name_just = "right"

+            if(name_rot == 0) {

+                name_just = "right"

+            } else if(name_rot == 90) {

+                name_just = "bottom"

+            } else if(name_rot == 180) {

+                name_just = "left"

+            } else {

+                name_just = "top"

+            }

     	} else {

     		name_x = unit(1, "npc") + name_offset

     		name_y = unit(0.5, "npc")

-    		name_just = "left"

+            if(name_rot == 0) {

+                name_just = "left"

+            } else if(name_rot == 90) {

+                name_just = "top"

+            } else if(name_rot == 180) {

+                name_just = "right"

+            } else {

+                name_just = "bottom"

+            }

     	}

     } else if(which == "row") {

     	if(!name_side %in% c("top", "bottom")) {

@@ -152,11 +174,27 @@ SingleAnnotation = function(name, value, col, fun,

     	if(name_side == "top") {

     		name_x = unit(0.5, "npc")

     		name_y = unit(1, "npc") + name_offset

-    		name_just = "left"

+            if(name_rot == 0) {

+                name_just = "bottom"

+            } else if(name_rot == 90) {

+                name_just = "left"

+            } else if(name_rot == 180) {

+                name_just = "top"

+            } else {

+                name_just = "right"

+            }

     	} else {

     		name_x = unit(0.5, "npc")

     		name_y = unit(0, "npc") - name_offset

-    		name_just = "right"

+            if(name_rot == 0) {

+                name_just = "top"

+            } else if(name_rot == 90) {

+                name_just = "right"

+            } else if(name_rot == 180) {

+                name_just = "bottom"

+            } else {

+                name_just = "left"

+            }

     	}

     }

     .Object@name_param = list(show = show_name,

@@ -107,20 +107,7 @@ ht_global_opt = setGlobalOptions(

 		.value = NULL),

 	fast_hclust = list(

 		.value = FALSE,

-		.filter = function(x) {

-				if(x) {

-					if(require(fastcluster)) {

-						assign("hclust", envir = topenv()) = getFromNamespace("hclust", "fastcluster")

-					} else {

-						stop("Cannot find fastcluster package.")

-					}

-				} else {

-					assign("hclust", envir = topenv()) = getFromNamespace("hclust", "stats")

-				}

-				x

-			}

-		)

+		.class = "logical",

+		.length = 1

+	)

 )

-

-hclust = getFromNamespace("hclust", "stats")

-

@@ -21,7 +21,8 @@ HeatmapAnnotation(df, name, col, na_col = "grey",

     show_annotation_name = FALSE,

     annotation_name_gp = gpar(),

     annotation_name_offset = unit(2, "mm"),

-    annotation_name_side = ifelse(which == "column", "right", "bottom"))

+    annotation_name_side = ifelse(which == "column", "right", "bottom"),

+    annotation_name_rot = ifelse(which == "column", 0, 90))

 }

 \arguments{

@@ -43,6 +44,7 @@ HeatmapAnnotation(df, name, col, na_col = "grey",

   \item{annotation_name_gp}{graphic parameters for anntation names. Graphic paramters can be vectors.}

   \item{annotation_name_offset}{offset to the annotations, \code{\link[grid]{unit}} object. The value can be a vector.}

   \item{annotation_name_side}{side of the annotation names.}

+  \item{annotation_name_rot}{rotation of the annotation names, can only take values in \code{c(00, 90, 180, 270)}. The value can be a vector.}

 }

 \details{

@@ -13,10 +13,11 @@ SingleAnnotation(name, value, col, fun,

     show_legend = TRUE,

     gp = gpar(col = NA),

     legend_param = list(),

-    show_name = TRUE,

+    show_name = FALSE,

     name_gp = gpar(fontsize = 12),

     name_offset = unit(2, "mm"),

-    name_side = ifelse(which == "column", "right", "bottom"))

+    name_side = ifelse(which == "column", "right", "bottom"),

+    name_rot = ifelse(which == "column", 0, 90))

 }

 \arguments{

@@ -33,6 +34,7 @@ SingleAnnotation(name, value, col, fun,

   \item{name_gp}{graphic parameters for annotation name}

   \item{name_offset}{offset to the annotation, a \code{\link[grid]{unit}} object}

   \item{name_side}{'right' and 'left' for column annotations and 'top' and 'bottom' for row annotations}

+  \item{name_rot}{rotation of the annotation name, can only take values in \code{c(00, 90, 180, 270)}.}

 }

 \details{

@@ -7,19 +7,18 @@ Construct row annotations

 Construct row annotations

 }

 \usage{

-rowAnnotation(..., width = unit(1, "cm"))

+rowAnnotation(...)

 }

 \arguments{

   \item{...}{pass to \code{\link{HeatmapAnnotation}}}

-  \item{width}{default width of the row annotations}

 }

 \details{

 The function is identical to

   \preformatted{

-    HeatmapAnnotation(..., which = "row", width = width)  }

+    HeatmapAnnotation(..., which = "row")  }

 }

 \value{

 A \code{\link{HeatmapAnnotation-class}} object.

@@ -64,7 +64,7 @@ to get full use of the package.

 ## Vignettes

-There are several vignettes in the package. Each vignette focuses on a specific topic. Following

+There are several vignettes in the package. Each vignette focuses on one specific topic. Following

 lists the general topics discussed in these vignettes:

   1. [**Making a Single Heatmap**](s2.single_heatmap.html)

@@ -72,13 +72,13 @@ lists the general topics discussed in these vignettes:

     This vignette introduces the basic configuration for making a single heatmap. Similar as other

     R functions/packages, the basic usage is quite similar, but there are several unique features

     for **ComplexHeamtap** package.

-    - Works both for numeric matrix and character matrix

+    - Works both for numeric matrix and character matrix.

     - For numeric matrix which contains continuous values, the package allows a color mapping function

       which can give more accurate colors and be robust to outliers.

     - Highly flexible for clustering. You can define the distance method for clustering by:

-          * a pre-defined distance such as "euclidean" or "pearson"

-          * a self-defined function which calculates distance from a matrix.

-          * a self-defined function which calculates distance from two vectors

+          * a pre-defined distance such as "euclidean" or "pearson",

+          * a self-defined function which calculates distance from a matrix,

+          * a self-defined function which calculates distance from two vectors.

         You can define the clustering method by:

           * a clustering function such as `diana()` from **cluster** package

@@ -96,7 +96,7 @@ lists the general topics discussed in these vignettes:

   3. [**Heatmap Annotations**](s4.heatmap_annotation.html)

-    This vignette introduces the concept of the heatmap annotation and demonstrate how to make simple annotations

+    This vignette introduces the concept of the heatmap annotation and demonstrates how to make simple annotations

     as well as complex annotations. Also, the vignette explains the difference between column annotations

     and row annotations.

@@ -121,4 +121,11 @@ lists the general topics discussed in these vignettes:

   8. [**Examples**](s9.examples.html)

     More simulated and real-world examples are shown in this vignette.

+

+In the supplementaries of [the ComplexHeatmap paper](http://bioinformatics.oxfordjournals.org/content/early/2016/05/20/bioinformatics.btw313.abstract), there are four comprehensive examples which are applied

+on real-world high-throughput datasets. [The examples can be found here.](http://jokergoo.github.io/supplementary/ComplexHeatmap-supplementary1-4/index.html)

+

+Also [my blog](http://jokergoo.github.io/blog.html) has some examples and tips for making better complex heatmaps.

+

+

@@ -196,7 +196,7 @@ Heatmap(mat, name = "foo", column_title = "I am a big column title",

     column_title_gp = gpar(fontsize = 20, fontface = "bold"))

 ```

-Roatations for titles can be set by `row_title_rot` and `column_title_rot`, but only horizontal and vertical 

+Rotations for titles can be set by `row_title_rot` and `column_title_rot`, but only horizontal and vertical 

 rotations are allowed.

 ```{r title_rotation}

@@ -212,7 +212,7 @@ contains clustering, or directly by a clustering function. It is also possible t

 your dendrograms with different colors and styles for different branches for better revealing

 structures of your data.

-First there are general settings for the clustering, e.g. whether show dendrograms, side

+First there are general settings for the clustering, e.g. whether do or show dendrograms, side

 of the dendrograms and size of the dendrograms.

 ```{r cluster_basic}

@@ -263,6 +263,7 @@ If possible distance method provided, you can also cluster a character matrix.

 ```{r cluster_character_matrix}

 mat_letters = matrix(sample(letters[1:4], 100, replace = TRUE), 10)

+# distance in th ASCII table

 dist_letters = function(x, y) {

     x = strtoi(charToRaw(paste(x, collapse = "")), base = 16)

     y = strtoi(charToRaw(paste(y, collapse = "")), base = 16)

@@ -294,8 +295,7 @@ Heatmap(mat, name = "foo", cluster_rows = as.dendrogram(diana(mat)),

 ```

 In the native `heatmap()` function, dendrograms on row and on column are reordered to let features with larger different

-separated more from each other, but according to my experience, the default reordering can not always give nice visualization.

-So by default the reordering for the dendrograms are turned off for `Heatmap()` function. 

+separated more from each other, By default the reordering for the dendrograms are turned on by `Heatmap()` as well. 

 Besides the default reordering method, you can first generate a dendrogram and apply other reordering

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

     cluster_columns = function(m) as.dendrogram(agnes(m)))

 ```

+`fastcluster::hclust` implements a faster version of `hclust`. We can re-define `cluster_rows` and `cluster_columns`

+to use the faster version of `hclust`. But note `fastcluster::hclust` only speed up the calculation of the cluster while not the

+calculation of distance matrix.

+

+```{r}

+# code not run when building the vignette

+Heatmap(mat, name = "foo", cluster_rows = function(m) fastcluster::hclust(dist(m)),

+    cluster_columns = function(m) fastcluster::hclust(dist(m))) # for column cluster, m will be automatically transposed

+```

+

+To make it more convinient to use the faster version of `hclust` (assuming you have many heatmaps to be concatenated), it can

+be set as a global option:

+

+```{r}

+# code not run when building the vignette

+ht_global_opt(fast_hclust = TRUE)

+# now hclust from fastcluster package is used in all heatmaps

+Heatmap(mat, name = "foo")

+```

+

 Clustering can help to adjust order in rows and in columns. But you can still set the order manually by `row_order`

 and `column_order`. Note you need to turn off clustering

 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

 `split` can be specified as a single number:

 ```{r split_dendrogram}

+dend = hclust(dist(mat))

+dend = color_branches(dend, k = 2)

 Heatmap(mat, name = "foo", cluster_rows = dend, split = 2)

 ```

@@ -600,7 +622,7 @@ the file size. In `Heatmap()` function, there are four options which control how

 the raster image: `use_raster`, `raster_device`, `raster_quality`, `raster_device_param`. 

 You can choose graphic device (`png`, `jpeg` and `tiff`) by `raster_device`, control the quality of the raster image by `raster_quality`,

-and pass further parameters for a specific device by `raster_device_param`.

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

 ## Session info

@@ -31,7 +31,8 @@ options(width = 100)

 A list of heatmaps can improve visualization of the correspondence between multiple data sources.

 In this vignette, we will discuss configurations for making a list of heatmaps and you can

-see more real-world examples in the [**Examples**](s9.examples.html) vignette.

+see more real-world examples in the [**Examples**](s9.examples.html) vignette as well as [in the 

+supplementaries](http://jokergoo.github.io/supplementary/ComplexHeatmap-supplementary1-4/index.html) of [the ComplexHeatmap paper](http://bioinformatics.oxfordjournals.org/content/early/2016/05/20/bioinformatics.btw313.abstract).

 ## Heatmap concatenation

@@ -44,13 +45,18 @@ are to be combined, users can append one heatmap to the other by `+` operator.

 ```{r heatmap_list_default, fig.width = 10}

 library(ComplexHeatmap)

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

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

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

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

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

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

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

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

+

+mat2 = matrix(rnorm(60, 2), 6, 10)

+mat2 = rbind(mat2, matrix(rnorm(60, -2), 6, 10))

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

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

-ht1 = Heatmap(mat, name = "ht1")

-ht2 = Heatmap(mat, name = "ht2")

+ht1 = Heatmap(mat1, name = "ht1")

+ht2 = Heatmap(mat2, name = "ht2")

 class(ht1)

 class(ht2)

@@ -61,7 +67,7 @@ Under default mode, dendrograms from the second heatmap will be removed and row

 The returned value of addition of two heatmaps is a `HeatmapList` object. Directly calling `ht_list` object

 will call `draw()` method with default settings. With explicitly calling `draw()` method, you can have more controls

-on the legend and titles.

+e.g. on the legend and titles.

 ```{r}

 ht_list = ht1 + ht2

@@ -91,8 +97,8 @@ for(s in sth) {

 A heatmap list also has titles which are independent to the heatmap titles.

 ```{r heatmap_list_title, fig.width = 10}

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

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

+ht1 = Heatmap(mat1, name = "ht1", row_title = "Heatmap 1", column_title = "Heatmap 1")

+ht2 = Heatmap(mat2, name = "ht2", row_title = "Heatmap 2", column_title = "Heatmap 2")

 ht_list = ht1 + ht2

 draw(ht_list, row_title = "Two heatmaps, row title", row_title_gp = gpar(col = "red"),

@@ -113,8 +119,8 @@ draw(ht_list + ht_list, gap = unit(c(3, 6, 9, 0), "mm"))

 The width for some (not all) heatmaps can be set to a fixed width.

 ```{r heatmap_list_size, fig.width = 10, fig.keep = "all"}

-ht1 = Heatmap(mat, name = "ht1", column_title = "Heatmap 1")

-ht2 = Heatmap(mat, name = "ht2", column_title = "Heatmap 2", width = unit(5, "cm"))

+ht1 = Heatmap(mat1, name = "ht1", column_title = "Heatmap 1")

+ht2 = Heatmap(mat2, name = "ht2", column_title = "Heatmap 2", width = unit(5, "cm"))

 ht1 + ht2

 ```

@@ -122,8 +128,8 @@ or the width can be set as relative values. Please not in this case, `width` for

 should be set (relative width and fixed width can be mixed).

 ```{r heatmap_list_relative_size, fig.width = 10, fig.keep = "all"}

-ht1 = Heatmap(mat, name = "ht1", column_title = "Heatmap 1", width = 2)

-ht2 = Heatmap(mat, name = "ht2", column_title = "Heatmap 2", width = 1)

+ht1 = Heatmap(mat1, name = "ht1", column_title = "Heatmap 1", width = 2)

+ht2 = Heatmap(mat2, name = "ht2", column_title = "Heatmap 2", width = 1)

 ht1 + ht2

 ```

@@ -141,8 +147,8 @@ The main heatmap can be specified by `main_heatmap` argument. The value can be a

 (of course, you need to set the heatmap name when you create the `Heatmap` object).

 ```{r heatmap_list_auto_adjust, fig.width = 10, fig.keep = "all"}

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

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

+ht1 = Heatmap(mat1, name = "ht1", column_title = "Heatmap 1", km = 2)

+ht2 = Heatmap(mat2, name = "ht2", column_title = "Heatmap 2")

 ht1 + ht2

 # note we changed the order of `ht1` and `ht2`

@@ -156,8 +162,8 @@ draw(ht2 + ht1, main_heatmap = "ht1")

 If there is no row clustering in the main heatmap, all other heatmaps have no row clustering neither.

 ```{r heatmap_list_auto_adjust_no_row_cluster, fig.width = 10}

-ht1 = Heatmap(mat, name = "ht1", column_title = "Heatmap 1", cluster_rows = FALSE)

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

+ht1 = Heatmap(mat1, name = "ht1", column_title = "Heatmap 1", cluster_rows = FALSE)

+ht2 = Heatmap(mat2, name = "ht2", column_title = "Heatmap 2")

 ht1 + ht2

 ```

@@ -168,8 +174,8 @@ ht1 + ht2

 ```{r, fig.width = 10}

 ht_global_opt(heatmap_row_names_gp = gpar(fontface = "italic"), 

 	          heatmap_column_names_gp = gpar(fontsize = 14))

-ht1 = Heatmap(mat, name = "ht1", column_title = "Heatmap 1")

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

+ht1 = Heatmap(mat1, name = "ht1", column_title = "Heatmap 1")

+ht2 = Heatmap(mat2, name = "ht2", column_title = "Heatmap 2")

 ht1 + ht2

 ht_global_opt(RESET = TRUE)

 ```

@@ -208,7 +214,7 @@ column_dend(ht_list)

 ## Heatmap list with row annotations

-Row annotations can also be reordered and split according to the main heatmap, 

+Row annotations can be added to the heatmap list, 

 please see [**Heatmap Annotation**](s4.heatmap_annotation.html) for more explanations.

 ## Modify row orders/clustering in main heatmap

@@ -218,11 +224,7 @@ in `draw()` method. This makes it convinient to switch main heatmaps without mod

 heatmaps. Actually settings specified in `draw()` will overwrite corresponding settings in the main heatmap.

 ```{r, fig.width = 8}

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

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

-mat2 = mat1[sample(1:nrow(mat1)), ]

-

-split = sample(c("a", "b"), nrow(mat1), replace = TRUE)

+split = rep(c("a", "b"), each = 6)

 ht_list = Heatmap(mat1, name = "mat1", cluster_rows = FALSE, column_title = "mat1") + 

           Heatmap(mat2, name = "mat2", cluster_rows = FALSE, column_title = "mat2")

 draw(ht_list, main_heatmap = "mat1", split = split)

@@ -45,7 +45,7 @@ color mapping functions, depending on whether the simple annotations are discret

 In the heatmap, simple annotations will be represented as rows of grids.

 There is a `draw()` method for the `HeatmapAnnotation` class. `draw()` is used internally and here

-we just use it for illustration.

+we just use it for demonstration.

 ```{r heatmap_annotation, fig.width = 7, fig.height = 0.5}

 library(ComplexHeatmap)

@@ -103,7 +103,7 @@ ha

 draw(ha, 1:10)

 ```

-Also individual annotations can be specified as vectors:

+Also individual annotations can be directly specified as vectors:

 ```{r heatmap_annotation_vector, fig.width = 7, fig.height = 1}

 ha = HeatmapAnnotation(type = c(rep("a", 5), rep("b", 5)),

@@ -367,7 +367,7 @@ The order of elements in row annotations will be adjusted by the clustering of h

 ha = rowAnnotation(df = df, col = list(type = c("a" = "red", "b" = "blue")),

     width = unit(1, "cm"))

 ht1 = Heatmap(mat, name = "ht1")

-ht1 = Heatmap(mat, name = "ht2")

+ht2 = Heatmap(mat, name = "ht2")

 ht1 + ha + ht2

 ```

@@ -378,7 +378,7 @@ splitted as well.

 ht1 = Heatmap(mat, name = "ht1", km = 2)

 ha = rowAnnotation(df = df, col = list(type = c("a" = "red", "b" = "blue")),

     boxplot = row_anno_boxplot(mat, axis = TRUE), 

-    width = unit(6, "cm"))

+    annotation_width = unit(c(1, 5), "cm"))

 ha + ht1

 ```

@@ -544,6 +544,43 @@ draw(ht_list, column_title = "reverse axis direction", newpage = FALSE)

 upViewport(2)

 ```

+## Add annotation names

+

+From version 1.11.5, `HeatmapAnnotation()` supports adding annotation names directly to the annotations.

+However, due to the design of the package, sometimes the names will be positioned outside of the plot

+or overlap to other heatmap compoments, thus, by default it is turned off.

+

+```{r}

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

+                age = sample(1:20, 10))

+value = rnorm(10)

+ha = HeatmapAnnotation(df = df, points = anno_points(value, axis = TRUE),

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

+               age = colorRamp2(c(0, 20), c("white", "red"))),

+    annotation_height = unit(c(0.5, 0.5, 2), "cm"),

+    show_annotation_name = TRUE,

+    annotation_name_offset = unit(2, "mm"),

+    annotation_name_rot = c(0, 0, 90))

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

+```

+

+Or the row annotation names: Note we manually adjust `padding` to fully show the text of "points".

+

+```{r}

+df = data.frame(type = c(rep("a", 6), rep("b", 6)),

+                age = sample(1:20, 12))

+value = rnorm(12)

+ha = rowAnnotation(df = df, points = row_anno_points(value, axis = TRUE),

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

+               age = colorRamp2(c(0, 20), c("white", "red"))),

+    annotation_width = unit(c(0.5, 0.5, 2), "cm"),

+    show_annotation_name = c(TRUE, FALSE, TRUE),

+    annotation_name_offset = unit(c(2, 2, 8), "mm"),

+    annotation_name_rot = c(90, 90, 0))

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

+draw(ht, padding = unit(c(4, 2, 2, 2), "mm"))

+```

+

 ## Adjust positions of column names

 In the layout of the heatmap components, column names are put directly below the heatmap body. This will cause

@@ -119,7 +119,8 @@ ha = HeatmapAnnotation(df = df, col = list(type = c("a" =  "red", "b" = "blue"))

                                                labels_gp = gpar(fontsize = 8))))

 ht1 = Heatmap(mat, name = "ht1", column_title = "Heatmap 1", top_annotation = ha)

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

-    heatmap_legend_param = list(title = "Heatmap2", title_gp = gpar(fontsize = 8), labels_gp = gpar(fontsize = 14)))

+    heatmap_legend_param = list(title = "Heatmap2", title_gp = gpar(fontsize = 8), 

+        labels_gp = gpar(fontsize = 14)))

 ht1 + ht2

 ```

@@ -146,6 +147,16 @@ ht1 = Heatmap(mat, name = "ht1")

 ht1 + ha_chr

 ```

+Or put at bottom of the heatmap:

+

+```{r, fig.width = 6}

+ha_chr = rowAnnotation(chr = sample(paste0("chr", 1:20), nrow(mat), replace = TRUE),

+    annotation_legend_param = list(chr = list(nrow = 2, title = "chr", title_position = "leftcenter")),

+    width = unit(5, "mm"))

+ht1 = Heatmap(mat, name = "ht1", show_heatmap_legend = FALSE)

+draw(ht1 + ha_chr, heatmap_legend_side = "bottom")

+```

+

 If you don't like the default discrete color bar for continuous values, you can specify `color_bar` to `continuous`.

 For the simple annotation which contains continuous values, `color_bar` can also be set to `continuous`.

@@ -206,6 +217,8 @@ lgd = Legend(at = c("class1", "class2"), title = "points", type = "points", lege

 draw(ht, annotation_legend_list = list(lgd))

 ```

+Also check [this blog link](http://zuguang.de/blog/html/dde69a9cf5a606a9486b19eb91ba6f4e.html) for more demonstrations.

+

 ## Session info

 ```{r}

@@ -165,7 +165,8 @@ can be used in the decoration code.

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

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

-would makes the adjustment of the heatmap layout difficult. But since you can go to any component 

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

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

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

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

@@ -37,6 +37,8 @@ additional barplots at both sides of the heatmap which show numbers of different

 each sample and for each gene. Also with the functionality of **ComplexHeatmap**, you can control oncoPrint with

 more flexibilities.

+## General settings

+

 There are two different forms of input data. The first is represented as a matrix in which 

 element would include multiple alterations in a form of a complex string. In follow example,

 'g1' in 's1' has two types of alterations which are 'snv' and 'indel'.

@@ -78,7 +80,10 @@ oncoPrint(mat, get_type = function(x) strsplit(x, ";")[[1]],

 	), col = col)

 ```

-The second type of input data is a list of matrix for which each matrix contains binary value representing

+In above example, form of the string (e.g. `snv;indel`) correlates to how you define `get_type`. If the string

+has the form of `snv|indel|amp`, `get_type` should be defined as `function(x) strsplit(x, "|")[[1]]`.

+

+If you are pulzzed by how to generated the matrix, there is a second way. The second type of input data is a list of matrix for which each matrix contains binary value representing

 whether the alteration is absent or present. The list should have names which correspond to the alteration

 types.

@@ -100,30 +105,27 @@ mat_list = unify_mat_list(mat_list)

 mat_list

 ```

-Same as the first example, but here we also define `background` in `alter_fun` argument. This function defines

-how to add graphics when there is no alteration and it is always put as the first in the list.

+Pass `mat_list` to `oncoPrint()`:

 ```{r}

 oncoPrint(mat_list,

 	alter_fun = list(

-		background = function(x, y, w, h) NULL,

 		snv = function(x, y, w, h) grid.rect(x, y, w*0.9, h*0.9, gp = gpar(fill = col["snv"], col = NA)),

 		indel = function(x, y, w, h) grid.rect(x, y, w*0.9, h*0.4, gp = gpar(fill = col["indel"], col = NA))

 	), col = col)

 ```

-If types of alterations is less than two and the purpose is only to have a quick look at the data, there are default

-graphics added:

-

-```{r}

-oncoPrint(mat_list)

-```

-

 In above examples, `alter_fun` is a list of functons which add graphics layer by layer. Graphics

 can also be added in a grid-by-grid style by specifying `alter_fun` as a single function. The difference

 from the function list is now `alter_fun` should accept a fifth argument which is a logical vector. 

 This logical vector shows whether different alterations exist for current gene in current sample.

+Let's assume in a grid there is only snv event, `v` for this grid is:

+

+```{r, echo = FALSE}

+print(c("snv" = TRUE, "indel" = FALSE))

+```

+

 ```{r}

 oncoPrint(mat_list,

 	alter_fun = function(x, y, w, h, v) {

@@ -146,6 +148,32 @@ oncoPrint(mat_list,

     }, col = col)

 ```

+If `alter_fun` is specified as a list, the order of the elements controls the order of adding graphics. 

+There is a special element named `background` which defines how to draw background and it should be always put

+as the first element in the `alter_fun` list. In following example, backgrond color is changed to light green with borders.

+

+```{r}

+oncoPrint(mat_list,

+	alter_fun = list(

+		background = function(x, y, w, h) grid.rect(x, y, w, h, gp = gpar(fill = "#00FF0020")),

+		snv = function(x, y, w, h) grid.rect(x, y, w*0.9, h*0.9, gp = gpar(fill = col["snv"], col = NA)),

+		indel = function(x, y, w, h) grid.rect(x, y, w*0.9, h*0.4, gp = gpar(fill = col["indel"], col = NA))

+	), col = col)

+```

+

+Or just remove the background:

+

+```{r}

+oncoPrint(mat_list,

+	alter_fun = list(

+		background = NULL,

+		snv = function(x, y, w, h) grid.rect(x, y, w*0.9, h*0.9, gp = gpar(fill = col["snv"], col = NA)),

+		indel = function(x, y, w, h) grid.rect(x, y, w*0.9, h*0.4, gp = gpar(fill = col["indel"], col = NA))

+	), col = col)

+```

+

+## Apply to cBioPortal dataset

+

 Now we make an oncoPrint with a real-world data. The data is retrieved from [cBioPortal](http://www.cbioportal.org/). 

 Steps for getting the data are as follows:

@@ -264,7 +292,7 @@ ht_list = oncoPrint(mat, get_type = function(x) strsplit(x, ";")[[1]],

 	heatmap_legend_param = list(title = "Alternations", at = c("AMP", "HOMDEL", "MUT"), 

 		labels = c("Amplification", "Deep deletion", "Mutation")),

 	split = sample(letters[1:2], nrow(mat), replace = TRUE)) +

-Heatmap(matrix(rnorm(nrow(mat)*10), ncol = 10), name = "expr", width = unit(4, "cm"))

+Heatmap(matrix(rnorm(nrow(mat)*10), ncol = 10), name = "expr", show_column_dend = FALSE, width = unit(4, "cm"))

 draw(ht_list, row_sub_title_side = "left")

 ```

@@ -28,6 +28,11 @@ options(markdown.HTML.stylesheet = "custom.css")

 options(width = 100)

 ```

+In the supplementaries of [the ComplexHeatmap paper](http://bioinformatics.oxfordjournals.org/content/early/2016/05/20/bioinformatics.btw313.abstract), there are four comprehensive examples which are applied

+on real-world high-throughput datasets. [The examples can be found here.](http://jokergoo.github.io/supplementary/ComplexHeatmap-supplementary1-4/index.html)

+

+Also [my blog](http://jokergoo.github.io/blog.html) has some examples and tips for making better complex heatmaps.

+

 ### Add more information for gene expression matrix