@@ -1,7 +1,7 @@

 Package: ComplexHeatmap

 Type: Package

 Title: Making Complex Heatmaps

-Version: 1.1.0

+Version: 1.1.1

 Date: 2015-3-26

 Author: Zuguang Gu

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

@@ -42,8 +42,10 @@ exportMethods(component_width)

 exportMethods(draw_heatmap_list)

 export(grid.dendrogram)

 export(dist2)

+export(rowAnnotation)

 exportMethods(draw_heatmap_legend)

 exportMethods(add_heatmap)

+export(columnAnnotation)

 export(anno_barplot)

 export(anno_density)

@@ -1,7 +1,12 @@

-CHANGES IN VERSION 0.99.4

+CHANGES IN VERSION 1.1.1

 * fixed a bug when setting `cluster_rows` to FALSE but still cluster

   on rows.

+* add `rowAnnotation` and `columnAnnotation` functions

+* add examples in the vignette

+* No error if the heatmap list only contains zero-column matrix

+

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

 CHANGES IN VERSION 0.99.2

@@ -228,6 +228,7 @@ Heatmap = function(matrix, col, name, rect_gp = gpar(col = NA),

     if(ncol(matrix) == 0) {

         .Object@heatmap_param$show_heatmap_legend = FALSE

+        .Object@heatmap_param$width = unit(0, "null")

     }

     if(is.character(matrix) || ncol(matrix) <= 1) {

@@ -24,7 +24,8 @@ HeatmapAnnotation = setClass("HeatmapAnnotation",

 		anno_list = "list",  # a list of `SingleAnnotation` objects

 		anno_size = "ANY",

 		which = "character",

-		size = "ANY"  # only for  consistent of Heatmap

+		size = "ANY",  # only for  consistent of Heatmap

+		gap = "ANY"

 	),

 	prototype = list(

 		anno_list = list(),

@@ -47,8 +48,9 @@ HeatmapAnnotation = setClass("HeatmapAnnotation",

 # -annotation_height height of each annotation if annotations are column annotations.

 # -annotation_width width of each annotation if annotations are row annotations.

 # -height not using currently.

-# -width width of the whole heatmap annotations, only used for column annotation when appending to the list of heatmaps.

+# -width width of the whole heatmap annotations, only used for row annotation when appending to the list of heatmaps.

 # -gp graphic parameters for simple annotations.

+# -gap gap between each annotation

 #

 # == details

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

@@ -57,12 +59,16 @@ HeatmapAnnotation = setClass("HeatmapAnnotation",

 # == value

 # A `HeatmapAnnotation-class` object.

 #

+# == seealso

+# There are two shortcut functions: `rowAnnotation` and `columnAnnotation`.

+#

 # == author

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

 #

 HeatmapAnnotation = function(df, name, col, show_legend, ..., 

 	which = c("column", "row"), annotation_height = 1, annotation_width = 1, 

-	height = unit(1, "cm"), width = unit(1, "cm"), gp = gpar(col = NA)) {

+	height = unit(1, "cm"), width = unit(1, "cm"), gp = gpar(col = NA),

+	gap = unit(0, "null")) {

 	.Object = new("HeatmapAnnotation")

@@ -139,7 +145,7 @@ HeatmapAnnotation = function(df, name, col, show_legend, ...,

 	}

 	if(!is.unit(anno_size)) {

-		anno_size = unit(anno_size/sum(anno_size), "npc")

+		anno_size = unit(anno_size/sum(anno_size), "null")

 	}

@@ -153,9 +159,63 @@ HeatmapAnnotation = function(df, name, col, show_legend, ...,

     .Object@size = size

+    if(is.null(gap)) gap = unit(0, "null")

+

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

+    	.Object@gap = rep(gap, n_anno)

+    } else if(length(gap) == n_anno - 1) {

+    	.Object@gap = unit.c(gap, unit(0, "null"))

+    } else if(length(gap) < n_anno - 1) {

+    	stop("Length of `gap` is wrong.")

+    } else {

+    	.Object@gap = gap

+    }

+

     return(.Object)

 }

+# == title

+# Construct row annotations

+#

+# == param

+# -... pass to `HeatmapAnnotation`

+#

+# == details

+# The function is identical to 

+#

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

+#

+# == value

+# A `HeatmapAnnotation-class` object.

+#

+# == author

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

+#

+rowAnnotation = function(...) {

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

+}

+

+# == title

+# Construct column annotations

+#

+# == param

+# -... pass to `HeatmapAnnotation`

+#

+# == details

+# The function is identical to

+#

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

+#

+# == value

+# A `HeatmapAnnotation-class` object.

+#

+# == author

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

+#

+columnAnnotation = function(...) {

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

+}

+

 # == title

 # Get a list of color mapping objects

 #

@@ -210,13 +270,14 @@ setMethod(f = "draw",

 	which = object@which

 	n_anno = length(object@anno_list)

 	anno_size = object@anno_size

+	gap = object@gap

 	pushViewport(viewport(...))

 	for(i in seq_len(n_anno)) {

 		if(which == "column") {

-			pushViewport(viewport(y = sum(anno_size[seq_len(i)]), height = anno_size[i], just = c("center", "top")))

+			pushViewport(viewport(y = sum(anno_size[seq_len(i)]) + sum(gap[seq_len(i)]) - gap[i], height = anno_size[i], just = c("center", "top")))

 		} else {

-			pushViewport(viewport(x = sum(anno_size[seq_len(i)]), width = anno_size[i], just = c("right", "center")))

+			pushViewport(viewport(x = sum(anno_size[seq_len(i)]) + sum(gap[seq_len(i)]) - gap[i], width = anno_size[i], just = c("right", "center")))

 		}

 		draw(object@anno_list[[i]], index)

 		upViewport()

@@ -668,8 +668,30 @@ setMethod(f = "draw_heatmap_list",

     gap = object@ht_list_param$gap

     ht_index = which(sapply(object@ht_list, inherits, "Heatmap"))

-

     n = length(object@ht_list)

+

+    # if there is only one heatmap but with zero column, width for one

+    # row annotations is allowed to have no width set

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

+        ht = object@ht_list[[ht_index]]

+        i_row_anno_nofix_width = which(sapply(object@ht_list, function(ht) {

+            if(inherits(ht, "Heatmap")) {

+                return(FALSE)

+            } else {

+                return(is.null(ht@size))

+            }

+        }))

+        i_row_anno_fix_width = setdiff(seq_len(n), c(i_row_anno_nofix_width, ht_index))

+        if(!is.null(ht@heatmap_param$width) && length(i_row_anno_nofix_width) == 1) {

+            if(length(i_row_anno_fix_width)) {

+                row_anno_fix_width = sum(do.call("unit.c", lapply(object@ht_list[i_row_anno_fix_width], function(x) x@size)))

+            } else {

+                row_anno_fix_width = unit(0, "null")

+            }

+            object@ht_list[[i_row_anno_nofix_width]]@size = unit(1, "npc") - ht@heatmap_param$width - row_anno_fix_width - sum(gap) + gap[length(gap)]

+        }

+    }

+

     # since each heatmap actually has nine rows, calculate the maximum height of corresponding rows in all heatmap 

     max_component_height = unit.c(

         max(do.call("unit.c", lapply(object@ht_list[ht_index], function(ht) component_height(ht, k = 1)))),

@@ -730,13 +752,17 @@ setMethod(f = "draw_heatmap_list",

     })

     heatmap_fixed_width = do.call("unit.c", heatmap_fixed_width)

     # width for body for each heatmap

-    heatmap_body_width = (unit(1, "npc") - sum(width_without_heatmap_body) - sum(heatmap_fixed_width) - sum(gap) + gap[length(gap)]) * (1/sum(heatmap_ncol)) * heatmap_ncol

+    if(sum(heatmap_ncol) == 0) {

+        heatmap_nofixed_width = unit(rep(0, n), "null")

+    } else {

+        heatmap_nofixed_width = (unit(1, "npc") - sum(width_without_heatmap_body) - sum(heatmap_fixed_width) - sum(gap) + gap[length(gap)]) * (1/sum(heatmap_ncol)) * heatmap_ncol

+    }

     # width of heatmap including body, and other components

     # width without fixed width

-    heatmap_width = sum(width_without_heatmap_body[1:3]) + heatmap_body_width[1] + sum(width_without_heatmap_body[5:7-1])

+    heatmap_width = sum(width_without_heatmap_body[1:3]) + heatmap_nofixed_width[1] + sum(width_without_heatmap_body[5:7-1])

     for(i in seq_len(n - 1) + 1) {

-        heatmap_width = unit.c(heatmap_width, sum(width_without_heatmap_body[6*(i-1) + 1:3]) + heatmap_body_width[i] + sum(width_without_heatmap_body[6*(i-1) + 5:7-1]))

+        heatmap_width = unit.c(heatmap_width, sum(width_without_heatmap_body[6*(i-1) + 1:3]) + heatmap_nofixed_width[i] + sum(width_without_heatmap_body[6*(i-1) + 5:7-1]))

     }

     # width with fixed width

     heatmap_width = heatmap_width + heatmap_fixed_width

@@ -13,7 +13,8 @@ Constructor method for HeatmapAnnotation class

 \usage{

 HeatmapAnnotation(df, name, col, show_legend, ...,

     which = c("column", "row"), annotation_height = 1, annotation_width = 1,

-    height = unit(1, "cm"), width = unit(1, "cm"), gp = gpar(col = NA))

+    height = unit(1, "cm"), width = unit(1, "cm"), gp = gpar(col = NA),

+    gap = NULL)

 }

 \arguments{

@@ -26,8 +27,9 @@ HeatmapAnnotation(df, name, col, show_legend, ...,

   \item{annotation_height}{height of each annotation if annotations are column annotations.}

   \item{annotation_width}{width of each annotation if annotations are row annotations.}

   \item{height}{not using currently.}

-  \item{width}{width of the whole heatmap annotations, only used for column annotation when appending to the list of heatmaps.}

+  \item{width}{width of the whole heatmap annotations, only used for row annotation when appending to the list of heatmaps.}

   \item{gp}{graphic parameters for simple annotations.}

+  \item{gap}{gap between each annotation}

 }

 \details{

@@ -39,6 +41,11 @@ The simple annotations are defined by \code{df} and \code{col} arguments. Comple

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

+}

+\seealso{

+There are two shortcut functions: \code{\link{rowAnnotation}} and \code{\link{columnAnnotation}}.  

+

+

 }

 \author{

 Zuguang Gu <z.gu@dkfz.de>  

@@ -20,7 +20,7 @@ Add heatmaps or row annotations as a heatmap list

 }

 \details{

-There is a shortcut function \code{+.Heatmap}.  

+There is a shortcut function \code{+.AdditiveUnit}.  

 }

@@ -20,7 +20,7 @@ Add row annotations or heatmaps as a heatmap list

 }

 \details{

-There is a shortcut function \code{+.HeatmapAnnotation}.  

+There is a shortcut function \code{+.AdditiveUnit}.  

 }

@@ -20,7 +20,7 @@ Add heatmaps and row annotations to the heatmap list

 }

 \details{

-There is a shortcut function \code{+.HeatmapList}.  

+There is a shortcut function \code{+.AdditiveUnit}.  

 }

new file mode 100644

@@ -0,0 +1,39 @@

+\name{columnAnnotation}

+\alias{columnAnnotation}

+\title{

+Construct column annotations  

+

+

+}

+\description{

+Construct column annotations  

+

+

+}

+\usage{

+columnAnnotation(...)

+}

+\arguments{

+

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

+

+}

+\details{

+The function is identical to  

+

+  \preformatted{

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

+  }

+

+

+}

+\value{

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

+

+

+}

+\author{

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

+

+

+}

new file mode 100644

@@ -0,0 +1,39 @@

+\name{rowAnnotation}

+\alias{rowAnnotation}

+\title{

+Construct row annotations  

+

+

+}

+\description{

+Construct row annotations  

+

+

+}

+\usage{

+rowAnnotation(...)

+}

+\arguments{

+

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

+

+}

+\details{

+The function is identical to   

+

+  \preformatted{

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

+  }

+

+

+}

+\value{

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

+

+

+}

+\author{

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

+

+

+}

@@ -649,6 +649,14 @@ ha = HeatmapAnnotation(df = df, which = "row", width = unit(1, "cm"))

 draw(ha, 1:12)

 ```

+Similar, there can be more than one row annotation:

+

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

+ha_combined = HeatmapAnnotation(df = df, boxplot = anno_boxplot(mat, which = "row"), 

+    which = "row", annotation_width = c(1, 3))

+draw(ha_combined, 1:12)

+```

+

 ### Mix heatmaps and row annotations

 Essentially, row annotations and column annotations are identical graphics, but in applications,

@@ -677,7 +685,7 @@ For row annotations, more complex annotation graphics can help to visualize the

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

 random_data = lapply(1:12, function(x) runif(20))

 random_data[1:6] = lapply(random_data[1:6], function(x) x*0.5)

-ha = HeatmapAnnotation(distribution = function(index) {

+ha2 = HeatmapAnnotation(distribution = function(index) {

         random_data = random_data[index]

         n = length(index)

@@ -692,7 +700,17 @@ ha = HeatmapAnnotation(distribution = function(index) {

             upViewport()

         }

     }, which = "row", width = unit(10, "cm"))

-draw(ht1 + ha, row_hclust_side = "left", row_sub_title_side = "right")

+draw(ht1 + ha2, row_hclust_side = "left", row_sub_title_side = "right")

+```

+

+If no heatmap is needed to draw and users only want to arrange a list of row annotations, an empty

+matrix with no column can be added to the heatmap list. (This functionality will be improved in the future)

+

+```{r all_row_annotations, fig.width = 4}

+nr = nrow(mat)

+ha = HeatmapAnnotation(df = df, which = "row", width = NULL)

+Heatmap(matrix(nrow = nr, ncol = 0), split = sample(c("A", "B"), nr, replace = TRUE)) + 

+    ha + ha_boxplot

 ```

 ## Access components