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

 Package: ComplexHeatmap

 Type: Package

 Title: Make Complex Heatmaps

-Version: 1.99.6

+Version: 1.99.7

 Date: 2019-03-15

 Author: Zuguang Gu

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

@@ -1,11 +1,13 @@

 CHANGES in VERSION 1.99.6

-* adjust the size of heatmap annotations and add testing scripts

-* run multiple times k-means to get a consensus partition

-* `show_heatmap_legend` is set to FALSE if `rect_gp = gpar(type = "none")`

-* add `restore_matrix()`

-* add `row_names_centered`/`column_names_centered` arguments to `Heatmap()`

-* `gp` in `anno_text()` supports `fill` and `border`

+* adjust the size of heatmap annotations and add testing scripts.

+* run multiple times k-means to get a consensus partition.

+* `show_heatmap_legend` is set to FALSE if `rect_gp = gpar(type = "none")`.

+* add `restore_matrix()`.

+* add `row_names_centered`/`column_names_centered` arguments to `Heatmap()`.

+* `gp` in `anno_text()` supports `fill` and `border`.

+* `Legend` adds boxplot-style legend.

+* adjustment according to annotation extension is improved.

 ========================

@@ -391,7 +391,7 @@ setMethod(f = "show",

 			cat("  subsetable variable:", paste(var_subsetable, collapse = ", "), "\n")

 		}

 	}

-	cat("  this object is ", ifelse(object@subsetable, "\b", "not "), "subsetable\n", sep = "")

+	cat("  this object is ", ifelse(object@subsetable, "", "not "), "subsetable\n", sep = "")

 	dirt = c("bottom", "left", "top", "right")

 	for(i in 1:4) {

 		if(!identical(unit(0, "mm"), object@extended[i])) {

@@ -354,9 +354,17 @@ Heatmap = function(matrix, col, name,

         }

     }

-    if(ncol(matrix) == 0) {

-        show_heatmap_legend = FALSE

-        .Object@heatmap_param$show_heatmap_legend = FALSE

+    # if(ncol(matrix) == 0 || nrow(matrix) == 0) {

+    #     show_heatmap_legend = FALSE

+    #     .Object@heatmap_param$show_heatmap_legend = FALSE

+    # }

+    if(ncol(matrix) == 0 && (!is.null(left_annotation) || !is.null(right_annotation))) {

+        message_wrap("If you have row annotations for a zeor-column matrix, please directly use in form of `rowAnnotation(...) + NULL`")

+        return(invisible(NULL))

+    }

+    if(nrow(matrix) == 0 && (!is.null(top_annotation) || !is.null(bottom_annotation))) {

+        message_wrap("If you have column annotations for a zero-row matrix, please directly use in form of `HeatmapAnnotation(...) %v% NULL`")

+        return(invisible(NULL))

     }

     if(identical(rect_gp$type, "none")) {

         show_heatmap_legend = FALSE

@@ -1430,6 +1438,10 @@ make_cluster = function(object, which = c("row", "column")) {

         }

     }

     slot(object, paste0(which, "_title")) = title

+    # check whether height of the dendrogram is zero

+    if(all(sapply(dend_list, dend_heights) == 0)) {

+        slot(object, paste0(which, "_dend_param"))$show = FALSE

+    }

     return(object)

 }

@@ -52,7 +52,7 @@ HeatmapAnnotation = setClass("HeatmapAnnotation",

 #      See `SingleAnnotation` for how to set colors.

 # -na_col Color for ``NA`` values in simple annotations.

 # -annotation_legend_param A list which contains parameters for annotation legends. See `color_mapping_legend,ColorMapping-method` for all possible options.

-# -show_legend Whether show annotation legends. The value can be one single value or a vector which corresponds to simple annotations.

+# -show_legend Whether show annotation legends. The value can be one single value or a vector.

 # -which Are these row annotations or column annotations?

 # -gp Graphic parameters for simple annotations (with ``fill`` parameter ignored).

 # -border border of single annotations.

@@ -215,6 +215,10 @@ HeatmapAnnotation = function(...,

     if(length(show_legend) == 1) {

 		show_legend = recycle_param(show_legend, simple_anno_name, TRUE)

 	}

+	# check length of show_legend

+	if(length(show_legend) == length(anno_value_list) && !all(l_simple_anno)) {

+		show_legend = show_legend[l_simple_anno]

+	}

 	###### normalize `heatmap_legend_param` #######

 	if(length(annotation_legend_param) == 0) {

@@ -206,6 +206,7 @@ setMethod(f = "add_heatmap",

 # -km = this modifies ``km`` of the main heatmap

 # -split this modifies ``split`` of the main heatmap

 # -row_km this modifies ``row_km`` of the main heatmap

+# -row_km_repeats this modifies ``row_km_repeats`` of the main heatmap

 # -row_split this modifies ``row_split`` of the main heatmap

 # -height this modifies ``height`` of the main heatmap

 # -heatmap_height this modifies ``heatmap_height`` of the main heatmap

@@ -219,6 +220,7 @@ setMethod(f = "add_heatmap",

 # -column_dend_gp this modifies ``column_dend_gp`` of the main heatmap

 # -column_order this modifies ``column_order`` of the main heatmap

 # -column_km this modifies ``column_km`` of the main heatmap

+# -column_km_repeats this modifies ``column_km_repeats`` of the main heatmap

 # -column_split this modifies ``column_split`` of the main heatmap

 # -width this modifies ``width`` of the main heatmap

 # -heatmap_width this modifies ``heatmap_width`` of the main heatmap

@@ -298,6 +300,7 @@ setMethod(f = "draw",

     km = NULL,

     split = NULL,

     row_km = km,

+    row_km_repeats = NULL,

     row_split = split,

     height = NULL,

     heatmap_height = NULL,

@@ -312,6 +315,7 @@ setMethod(f = "draw",

     column_dend_gp = NULL,

     column_order = NULL,

     column_km = NULL,

+    column_km_repeats = NULL,

     column_split = NULL,

     width = NULL,

     heatmap_width = NULL,

@@ -465,6 +469,7 @@ setMethod(f = "draw",

         row_dend_gp = row_dend_gp,

         row_order = row_order,

         row_km = row_km,

+        row_km_repeats = row_km_repeats,

         row_split = row_split,

         height = height,

         heatmap_height = heatmap_height,

@@ -479,6 +484,7 @@ setMethod(f = "draw",

         column_dend_gp = column_dend_gp,

         column_order = column_order,

         column_km = column_km,

+        column_km_repeats = column_km_repeats,

         column_split = column_split,

         width = width,

         heatmap_width = heatmap_width

@@ -514,7 +520,7 @@ setMethod(f = "draw",

     ht_graphic_fun_list = object@layout$graphic_fun_list

     for(j in seq_len(nrow(ht_layout_index))) {

-        pushViewport(viewport(layout.pos.row = ht_layout_index[j, 1], layout.pos.col = ht_layout_index[j, 2]))

+        pushViewport(viewport(name = paste0("global-", rownames(ht_layout_index)[j]), layout.pos.row = ht_layout_index[j, 1], layout.pos.col = ht_layout_index[j, 2]))

         ht_graphic_fun_list[[j]](object)

         upViewport()

     }

@@ -50,6 +50,7 @@ setMethod(f = "adjust_heatmap_list",

         }

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

+        max_title_component_width = unit(c(0, 0), "mm")

         max_title_component_height = unit.c(

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

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

@@ -191,6 +192,7 @@ setMethod(f = "adjust_heatmap_list",

             object@layout$row_anno_max_bottom_extended = row_anno_max_bottom_extended

             object@layout$max_bottom_component_height = max_bottom_component_height

             object@layout$max_title_component_height = max_title_component_height

+            object@layout$max_title_component_width = max_title_component_width

             ## left and right

             column_anno_max_left_extended = unit(0, "mm")

@@ -251,6 +253,7 @@ setMethod(f = "adjust_heatmap_list",

             }

         }

+        max_title_component_height = unit(c(0, 0), "mm")

         max_title_component_width = unit.c(

             max(do.call("unit.c", lapply(object@ht_list[ht_index], function(ht) component_width(ht, "row_title_left")))),

             max(do.call("unit.c", lapply(object@ht_list[ht_index], function(ht) component_width(ht, "row_title_right"))))

@@ -392,6 +395,7 @@ setMethod(f = "adjust_heatmap_list",

             object@layout$column_anno_max_right_extended = column_anno_max_right_extended

             object@layout$max_right_component_width = max_right_component_width

             object@layout$max_title_component_width = max_title_component_width

+            object@layout$max_title_component_height = max_title_component_height

             ## top and bottom

             row_anno_max_top_extended = unit(0, "mm")

@@ -399,6 +403,7 @@ setMethod(f = "adjust_heatmap_list",

             if(inherits(object@ht_list[[1]], "Heatmap")) {

                 ht_first = object@ht_list[[1]]

                 max_top_component_height = sum(component_height(ht_first, c("column_names_top", "column_dend_top", "column_anno_top", "column_title_top")))

+

                 u = unit(0, "mm")

                 if(!is.null(ht_first@left_annotation)) {

                     u = unit.c(u, ht_first@left_annotation@extended[3])

@@ -499,20 +504,22 @@ setMethod(f = "adjust_heatmap_list",

             }

         }

     }

+

     if(is.null(adjust_annotation_extension)) adjust_annotation_extension = TRUE

     if(adjust_annotation_extension) {

-        if(object@layout$row_anno_max_bottom_extended[[1]] > object@layout$max_bottom_component_height[[1]]) {

-            padding[1] = object@layout$row_anno_max_bottom_extended - object@layout$max_bottom_component_height

+        # note e.g. max_*_component_height does not include the height of titles

+        if(object@layout$row_anno_max_bottom_extended[[1]] > object@layout$max_bottom_component_height[[1]]+ object@layout$max_title_component_height[[2]]) {

+            padding[1] = object@layout$row_anno_max_bottom_extended - object@layout$max_bottom_component_height - object@layout$max_title_component_height[2]

         }

-        if(object@layout$column_anno_max_left_extended[[1]] > object@layout$max_left_component_width[[1]]) {

-            padding[2] = object@layout$column_anno_max_left_extended - object@layout$max_left_component_width + GLOBAL_PADDING[2]

+        if(object@layout$column_anno_max_left_extended[[1]] > object@layout$max_left_component_width[[1]] + object@layout$max_title_component_width[[1]]) {

+            padding[2] = object@layout$column_anno_max_left_extended - object@layout$max_left_component_width - object@layout$max_title_component_width[1]

         }

-        if(object@layout$row_anno_max_top_extended[[1]] > object@layout$max_top_component_height[[1]]) {

-            padding[3] = object@layout$row_anno_max_top_extended - object@layout$max_top_component_height + GLOBAL_PADDING[3]

+        if(object@layout$row_anno_max_top_extended[[1]] > object@layout$max_top_component_height[[1]] + object@layout$max_title_component_height[[1]]) {

+            padding[3] = object@layout$row_anno_max_top_extended - object@layout$max_top_component_height - object@layout$max_title_component_height[1]

         }

-        if(object@layout$column_anno_max_right_extended[[1]] > object@layout$max_right_component_width[[1]]) {

-            padding[4] = object@layout$column_anno_max_right_extended - object@layout$max_right_component_width + GLOBAL_PADDING[4]

+        if(object@layout$column_anno_max_right_extended[[1]] > object@layout$max_right_component_width[[1]] + object@layout$max_title_component_width[[2]]) {

+            padding[4] = object@layout$column_anno_max_right_extended - object@layout$max_right_component_width - object@layout$max_title_component_width[2]

         }

     }

     object@layout$heatmap_list_padding = padding

@@ -35,6 +35,7 @@

 # -row_dend_gp Overwrite the corresponding setting in the main heatmap.

 # -row_order Overwrite the corresponding setting in the main heatmap.

 # -row_km Overwrite the corresponding setting in the main heatmap.

+# -row_km_repeats Overwrite the corresponding setting in the main heatmap.

 # -row_split Overwrite the corresponding setting in the main heatmap.

 # -height Overwrite the corresponding setting in the main heatmap.

 # -heatmap_height Overwrite the corresponding setting in the main heatmap.

@@ -48,6 +49,7 @@

 # -column_dend_gp Overwrite the corresponding setting in the main heatmap.

 # -column_order Overwrite the corresponding setting in the main heatmap.

 # -column_km Overwrite the corresponding setting in the main heatmap.

+# -column_km_repeats Overwrite the corresponding setting in the main heatmap.

 # -column_split Overwrite the corresponding setting in the main heatmap.

 # -width Overwrite the corresponding setting in the main heatmap.

 # -heatmap_width Overwrite the corresponding setting in the main heatmap.

@@ -104,6 +106,7 @@ setMethod(f = "make_layout",

     row_dend_gp = NULL,

     row_order = NULL,

     row_km = NULL,

+    row_km_repeats = NULL,

     row_split = NULL,

     height = NULL,

     heatmap_height = NULL,

@@ -118,6 +121,7 @@ setMethod(f = "make_layout",

     column_dend_gp = NULL,

     column_order = NULL,

     column_km = NULL,

+    column_km_repeats = NULL,

     column_split = NULL,

     width = NULL,

     heatmap_width = NULL) {

@@ -235,6 +239,10 @@ setMethod(f = "make_layout",

             object@ht_list[[i_main]]@matrix_param$row_km = row_km

             if(verbose) qqcat("set row_km to main heatmap\n")

         }

+        if(!is.null(row_km_repeats)) {

+            object@ht_list[[i_main]]@matrix_param$row_km_repeats = row_km_repeats

+            if(verbose) qqcat("set row_km_repeats to main heatmap\n")

+        }

         if(!is.null(row_gap)) {

             object@ht_list[[i_main]]@matrix_param$row_gap = row_gap

@@ -372,6 +380,10 @@ setMethod(f = "make_layout",

             object@ht_list[[i_main]]@matrix_param$column_km = column_km

             if(verbose) qqcat("set column_km to main heatmap\n")

         }

+        if(!is.null(column_km_repeats)) {

+            object@ht_list[[i_main]]@matrix_param$column_km_repeats = column_km_repeats

+            if(verbose) qqcat("set column_km_repeats to main heatmap\n")

+        }

         if(!is.null(column_gap)) {

             object@ht_list[[i_main]]@matrix_param$column_gap = column_gap

@@ -848,6 +860,16 @@ setMethod(f = "make_layout",

             }

         }

     }

+    if(length(heatmap_legend_list) != 0) {

+        if(inherits(heatmap_legend_list, c("Legends", "grob"))) {

+            heatmap_legend_list = list(heatmap_legend_list)

+        }

+    }

+    if(length(annotation_legend_list) != 0) {

+        if(inherits(annotation_legend_list, c("Legends", "grob"))) {

+            annotation_legend_list = list(annotation_legend_list)

+        }

+    }

     if(merge_legends) {

         heatmap_legend_list = c(heatmap_legend_list, annotation_legend_list)

     }

@@ -60,7 +60,7 @@ Legends = function(...) {

 # -labels_rot Text rotation for labels. It should only be used for horizontal continuous legend.

 # -border Color of legend grid borders. It also works for the ticks in the continuous legend.

 # -background Background colors for the grids. It is used when points and lines are the legend graphics.

-# -type Type of legends. The value can be one of ``grid``, ``points`` and ``lines``.

+# -type Type of legends. The value can be one of ``grid``, ``points``, ``lines`` and ``boxplot``.

 # -legend_gp Graphic parameters for the legend grids. You should control the filled color of the legend grids by ``gpar(fill = ...)``.

 # -pch Type of points if points are used as legend. Note you can use single-letter as pch, e.g. ``pch = 'A'``.

 #      There are three additional integers that are valid for ``pch``: 26 and 27 for single diagonal lines and 28 for double diagonal lines.

@@ -425,6 +425,18 @@ discrete_legend_body = function(at, labels = at, nrow = NULL, ncol = 1, by_row =

 					         gp = subset_gp(legend_gp, index))

 			))

 		}

+		if(any(c("boxplot", "box") %in% type)) {

+			gl = c(gl, list(

+				segmentsGrob(x0 = grid_x, y0 = grid_y - grid_height*0.45, 

+					         x1 = grid_x, y1 = grid_y + grid_height*0.45,

+					         gp = subset_gp(legend_gp, index)),

+				rectGrob(x = grid_x, y = grid_y, width = grid_width*0.9, height = grid_height*0.5,

+					     gp = subset_gp(legend_gp, index)),

+				segmentsGrob(x0 = grid_x - grid_width*0.45, y0 = grid_y, 

+					         x1 = grid_x + grid_width*0.45, y1 = grid_y,

+					         gp = subset_gp(legend_gp, index))

+			))

+		}

 	}

 	class(gl) = "gList"

@@ -742,6 +754,8 @@ horizontal_continuous_legend_body = function(at, labels = at, col_fun,

 # == param

 # -... A list of objects returned by `Legend`.

 # -gap Gap between two neighbouring legends. The value is a `grid::unit` object with length of one.

+#      It is the same as ``row_gap`` if the direction if vertial and the same as ``column_gap`` if

+#      the direction is horizontal.

 # -row_gap Horizontal gaps between legends.

 # -column_gap Vertical gaps between legends.

 # -direction The direction to arrange legends.

@@ -765,7 +779,7 @@ horizontal_continuous_legend_body = function(at, labels = at, col_fun,

 # draw(pd, test = "two legends")

 # pd = packLegend(lgd1, lgd2, direction = "horizontal")

 # draw(pd, test = "two legends packed horizontally")

-packLegend = function(...,gap = unit(2, "mm"), row_gap = unit(2, "mm"), column_gap = unit(2, "mm"),

+packLegend = function(..., gap = unit(2, "mm"), row_gap = unit(2, "mm"), column_gap = unit(2, "mm"),

 	direction = c("vertical", "horizontal"),

 	max_width = NULL, max_height = NULL, list = NULL) {

@@ -94,8 +94,8 @@ oncoPrint = function(mat,

 	if("axis_gp" %in% arg_names) {

 		stop_wrap("`axis_gp` is removed from the arguments. Please set `axis_param(gp = ...)` in `anno_oncoprint_barplot()` when you define the `top_annotation` or `right_annotation`.")

 	}

-	if("show_row_names" %in% arg_names) {

-		stop_wrap("`show_row_names` is removed from the arguments. Please directly remove `anno_oncoprint_barplot()` in `right_annotation` to remove barplots on the left of the oncoPrint.")

+	if("show_row_barplot" %in% arg_names) {

+		stop_wrap("`show_row_barplot` is removed from the arguments. Please directly remove `anno_oncoprint_barplot()` in `right_annotation` to remove barplots on the right of the oncoPrint.")

 	}

 	if("row_barplot_width" %in% arg_names) {

 		stop_wrap("`row_barplot_width` is removed from the arguments. Please directly set `width` in `anno_oncoprint_barplot()` in `right_annotation`.")

@@ -110,6 +110,10 @@ oncoPrint = function(mat,

 		stop_wrap("`barplot_ignore` is removed from the arguments. The subset of alterations now can be controlled in `anno_oncoprint_barplot()`.")

 	}

+	if(inherits(col, "function")) {

+		stop_wrap("`col` should be specified as a vector.")

+	}

+

 	# convert mat to mat_list

 	if(inherits(mat, "data.frame")) {

 		mat = as.matrix(mat)

@@ -152,8 +156,7 @@ oncoPrint = function(mat,

 		stop_wrap("Incorrect type of 'mat'")

 	}

-	cat("All mutation types:", paste(all_type, collapse = ", "), "\n")

-

+	message_wrap(paste0("All mutation types: ", paste(all_type, collapse = ", ")))

 	# type as the third dimension

 	arr = array(FALSE, dim = c(dim(mat_list[[1]]), length(all_type)), dimnames = c(dimnames(mat_list[[1]]), list(all_type)))

@@ -573,7 +576,7 @@ anno_oncoprint_barplot = function(type = NULL, which = c("column", "row"),

 			axis = axis, axis_param = axis_param)@fun

 		fun(index, k, n)

 	}

-	

+

 	if(which == "row") {

 		fun = row_fun

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

@@ -592,8 +595,19 @@ anno_oncoprint_barplot = function(type = NULL, which = c("column", "row"),

 	anno@subsetable = TRUE

 	anno@show_name = FALSE

+	if(exists("arr", envir = parent.frame(1))) {

+		arr = get("arr", envir = parent.frame(1))

+		if(which == "row") {

+			data_scale = c(0, max(apply(arr, 1, sum)))

+		} else {

+			data_scale = c(0, max(apply(arr, 2, sum)))

+		}

+	} else {

+		data_scale = c(0, 100)

+	}

+

 	axis_param = validate_axis_param(axis_param, which)

-	axis_grob = if(axis) construct_axis_grob(axis_param, which, c(0, 100)) else NULL

+	axis_grob = if(axis) construct_axis_grob(axis_param, which, data_scale) else NULL

 	anno@extended = update_anno_extend(anno, axis_grob, axis_param)

 	return(anno) 

@@ -56,7 +56,7 @@ default_col = function(x, main_matrix = FALSE) {

         x = as.vector(x)

     }

-    if(length(unique(x)) == 1) {

+    if(length(unique(as.vector(x))) == 1) {

         x = as.character(x)

     }

@@ -11,18 +11,6 @@ If you use it in published research, please cite:

 Gu, Z. Complex heatmaps reveal patterns and correlations in multidimensional 

   genomic data. Bioinformatics 2016.

 ========================================

-

-This version is a major update of the package. The major new features are:

-

-1. Support splitting heatmaps by columns.

-2. Support concatenating heatmaps/annotations vertically.

-3. Provide more types of heatmap annotations.

-4. Support UpSet plot.

-

-Note this version is not 100% compatible with the older versions (< 1.99.0).

-Please check by `vignette('difference_to_old_versions', package = 'ComplexHeatmap')`.

-

-Above messages will be removed in the future.

 ")	

     packageStartupMessage(msg)

@@ -37,7 +37,7 @@ HeatmapAnnotation(...,

   \item{col}{A list of colors which contain color mapping to \code{df} or simple annotations defined in \code{...}.  See \code{\link{SingleAnnotation}} for how to set colors.}

   \item{na_col}{Color for \code{NA} values in simple annotations.}

   \item{annotation_legend_param}{A list which contains parameters for annotation legends. See \code{\link{color_mapping_legend,ColorMapping-method}} for all possible options.}

-  \item{show_legend}{Whether show annotation legends. The value can be one single value or a vector which corresponds to simple annotations.}

+  \item{show_legend}{Whether show annotation legends. The value can be one single value or a vector.}

   \item{which}{Are these row annotations or column annotations?}

   \item{gp}{Graphic parameters for simple annotations (with \code{fill} parameter ignored).}

   \item{border}{border of single annotations.}

@@ -33,7 +33,7 @@ Legend(at, labels = at, col_fun, nrow = NULL, ncol = 1, by_row = FALSE,

   \item{labels_rot}{Text rotation for labels. It should only be used for horizontal continuous legend.}

   \item{border}{Color of legend grid borders. It also works for the ticks in the continuous legend.}

   \item{background}{Background colors for the grids. It is used when points and lines are the legend graphics.}

-  \item{type}{Type of legends. The value can be one of \code{grid}, \code{points} and \code{lines}.}

+  \item{type}{Type of legends. The value can be one of \code{grid}, \code{points}, \code{lines} and \code{boxplot}.}

   \item{legend_gp}{Graphic parameters for the legend grids. You should control the filled color of the legend grids by \code{gpar(fill = ...)}.}

   \item{pch}{Type of points if points are used as legend. Note you can use single-letter as pch, e.g. \code{pch = 'A'}. There are three additional integers that are valid for \code{pch}: 26 and 27 for single diagonal lines and 28 for double diagonal lines.}

   \item{size}{Size of points.}

@@ -50,6 +50,7 @@ Draw a list of heatmaps

     km = NULL,

     split = NULL,

     row_km = km,

+    row_km_repeats = NULL,

     row_split = split,

     height = NULL,

     heatmap_height = NULL,

@@ -64,6 +65,7 @@ Draw a list of heatmaps

     column_dend_gp = NULL,

     column_order = NULL,

     column_km = NULL,

+    column_km_repeats = NULL,

     column_split = NULL,

     width = NULL,

     heatmap_width = NULL,

@@ -124,6 +126,7 @@ Draw a list of heatmaps

   \item{km}{= this modifies \code{km} of the main heatmap}

   \item{split}{this modifies \code{split} of the main heatmap}

   \item{row_km}{this modifies \code{row_km} of the main heatmap}

+  \item{row_km_repeats}{this modifies \code{row_km_repeats} of the main heatmap}

   \item{row_split}{this modifies \code{row_split} of the main heatmap}

   \item{height}{this modifies \code{height} of the main heatmap}

   \item{heatmap_height}{this modifies \code{heatmap_height} of the main heatmap}

@@ -137,6 +140,7 @@ Draw a list of heatmaps

   \item{column_dend_gp}{this modifies \code{column_dend_gp} of the main heatmap}

   \item{column_order}{this modifies \code{column_order} of the main heatmap}

   \item{column_km}{this modifies \code{column_km} of the main heatmap}

+  \item{column_km_repeats}{this modifies \code{column_km_repeats} of the main heatmap}

   \item{column_split}{this modifies \code{column_split} of the main heatmap}

   \item{width}{this modifies \code{width} of the main heatmap}

   \item{heatmap_width}{this modifies \code{heatmap_width} of the main heatmap}

@@ -45,6 +45,7 @@ Make Layout for the Heatmap List

     row_dend_gp = NULL,

     row_order = NULL,

     row_km = NULL,

+    row_km_repeats = NULL,

     row_split = NULL,

     height = NULL,

     heatmap_height = NULL,

@@ -59,6 +60,7 @@ Make Layout for the Heatmap List

     column_dend_gp = NULL,

     column_order = NULL,

     column_km = NULL,

+    column_km_repeats = NULL,

     column_split = NULL,

     width = NULL,

     heatmap_width = NULL)

@@ -97,6 +99,7 @@ Make Layout for the Heatmap List

   \item{row_dend_gp}{Overwrite the corresponding setting in the main heatmap.}

   \item{row_order}{Overwrite the corresponding setting in the main heatmap.}

   \item{row_km}{Overwrite the corresponding setting in the main heatmap.}

+  \item{row_km_repeats}{Overwrite the corresponding setting in the main heatmap.}

   \item{row_split}{Overwrite the corresponding setting in the main heatmap.}

   \item{height}{Overwrite the corresponding setting in the main heatmap.}

   \item{heatmap_height}{Overwrite the corresponding setting in the main heatmap.}

@@ -110,6 +113,7 @@ Make Layout for the Heatmap List

   \item{column_dend_gp}{Overwrite the corresponding setting in the main heatmap.}

   \item{column_order}{Overwrite the corresponding setting in the main heatmap.}

   \item{column_km}{Overwrite the corresponding setting in the main heatmap.}

+  \item{column_km_repeats}{Overwrite the corresponding setting in the main heatmap.}

   \item{column_split}{Overwrite the corresponding setting in the main heatmap.}

   \item{width}{Overwrite the corresponding setting in the main heatmap.}

   \item{heatmap_width}{Overwrite the corresponding setting in the main heatmap.}

@@ -7,14 +7,14 @@ Pack Legends

 Pack Legends

 }

 \usage{

-packLegend(...,gap = unit(2, "mm"), row_gap = unit(2, "mm"), column_gap = unit(2, "mm"),

+packLegend(..., gap = unit(2, "mm"), row_gap = unit(2, "mm"), column_gap = unit(2, "mm"),

     direction = c("vertical", "horizontal"),

     max_width = NULL, max_height = NULL, list = NULL)

 }

 \arguments{

   \item{...}{A list of objects returned by \code{\link{Legend}}.}

-  \item{gap}{Gap between two neighbouring legends. The value is a \code{\link[grid]{unit}} object with length of one.}

+  \item{gap}{Gap between two neighbouring legends. The value is a \code{\link[grid]{unit}} object with length of one. It is the same as \code{row_gap} if the direction if vertial and the same as \code{column_gap} if the direction is horizontal.}

   \item{row_gap}{Horizontal gaps between legends.}

   \item{column_gap}{Vertical gaps between legends.}

   \item{direction}{The direction to arrange legends.}

deleted file mode 100644

@@ -1,124 +0,0 @@

-<!--

-%\VignetteEngine{knitr}

-%\VignetteIndexEntry{Difference to older versions}

-

-

-Difference to Older Versions of ComplexHeatmap Package

-=================================================

-

-**Author**: Zuguang Gu ( z.gu@dkfz.de )

-

-**Date**: `r Sys.Date()`

-

-**Package version**: `r installed.packages()["ComplexHeatmap", "Version"]`

-

-

-<style type="text/css">

-h1, h2, h3, h4, h5 {

-    line-height: 120%;

-}

-</style>

-

-From version 1.99.0 of **ComplexHeatmap**, there are big changes to the older versions. The major

-functionalities are still the same, but it is not 100% compatible. This vignette lists the

-changes between the new and old versions.

-

-## Heatmap() function

-

-- New arguments `column_km` and `column_split` to split heatmap by columns. The old `km` and `split`

-  are renamed to `row_km` and `row_split`, although `km` and `split` are still usable.

-- A new argument `border` controls the border of the heatmap body. If heatmap is split into slices,

-  all the slices will have borders.

-- Row title and column title allow background color by e.g. `column_title_gp = gpar(fill = ...)`.

-- `cluster_rows` and `cluster_columns` also allow objects which can be converted to `dendrogram`.

-- If `cluster_rows` and `cluster_columns` are provided as clustering object, dendrogram reordering

-  is turned off by default.

-- Add examples of how to integrate seriation.

-  (https://jokergoo.github.io/ComplexHeatmap-reference/book/a-single-heatmap.html#heatmap-seriation)

-- Row names and column names allow rotation by `row_names_rot` and `column_names_rot`.

-- New arguments `row_labels` and `column_labels` which can be set to replace row names and column

-  names on the heatmap.

-- When heatmap is split and clustering is performed, there is a parent dendrogram which is

-  calculated from mean values in slices and put on top of the children dendrograms. There is a dashed

-  line showing the part of the parent dendrogram and emphasizing the dendrogram is combined from

-  several dendrograms.

-- Remove `combined_name_fun` argument and control the titles for the heatmap slices directly by

-  `row_title` and `column_title`. The two arguments support a string template which is convinient to

-  control the title for each slice.

-  (https://jokergoo.github.io/ComplexHeatmap-reference/book/a-single-heatmap.html#titles-for-splitting)

-- New argument `layer_fun` is a vectorized version of `cell_fun`. This functionality is too

-  low-level and normally users will not use it.

-  (https://jokergoo.github.io/ComplexHeatmap-reference/book/a-single-heatmap.html#customize-the-heatmap-body)

-- New arguments `width`, `heatmap_width`, `height`, `heatmap_height` to control the size of the

-  heatmap.

-  (https://jokergoo.github.io/ComplexHeatmap-reference/book/a-single-heatmap.html#size-of-the-heatmap)

-- New arguments `left_annotation` and `right_annotation`, which means row annotations can be components

-  of the heatmap, just like column annotations.

-- Remove `top_annotation_height` and `bottom_annotation_height`. The height of annotations should be

-  set in `HeatmapAnnotation()` function now.

-

-## HeatmapAnnotation() function

-

-- All annotations have default width/height now. E.g. the column simple annotation has height of 5mm

-  and the column barplot annotation has height of 1cm.

-- Provide more annotation functions: `anno_empty()`, `anno_simple`, `anno_image()`, `anno_block()`,

-  `anno_lines()`, `anno_joyplot()`, `anno_horizon()`, `anno_summary()`, `anno_zoom()`.

-  (https://jokergoo.github.io/ComplexHeatmap-reference/book/heatmap-annotations.html)

-- The size of the annotations are better to be set in the annotation functions, e.g.

-  `anno_points(..., height = )`, but you can still set `annotation_height`.

-- The axis for the annotations (e.g. `anno_points()`, ...) can be controlled by the `axis_param`

-  argument in the annotation function.

-- `anno_link()` is now renamed to `anno_mark()`. This annotation has default width and no need to

-  manually calcualte.

-- `anno_text()`: the size of the annotation is automatically calculated.

-- By default, the annotation names and axes are drawn and the space for them are also taken into

-  account for the layout of the final heatmap.

-- Two `HeatmapAnnotation` objects can be added as a single `HeatmapAnnotation` object by `c()`.

-  (https://jokergoo.github.io/ComplexHeatmap-reference/book/heatmap-annotations.html#heatmap-annotation-utility-function)

-- No need to use `row_anno_*()` functions, now `anno_*()` functions can automatically check whether

-  they are in column annotations or row annotations.

-

-## A list of heatmaps

-

-- Heatmaps and annotations can be concatenated vertically by `%v%`.

-  (https://jokergoo.github.io/ComplexHeatmap-reference/book/a-list-of-heatmaps.html#vertical-concatenation)

-- More arguments for the main heatmap can be controlled directly in `draw()`.

-  (https://jokergoo.github.io/ComplexHeatmap-reference/book/a-list-of-heatmaps.html#control-main-heatmap-in-draw-function)

-- Global options can be temporarily set in `draw()`. (https://jokergoo.github.io/ComplexHeatmap-reference/book/a-list-of-heatmaps.html#change-parameters-globally, the last paragraph.)

-- Annotations and column names are nicely adjusted.

-  (https://jokergoo.github.io/ComplexHeatmap-reference/book/a-list-of-heatmaps.html#annotations-as-components-are-adjusted)

-

-## Legends

-

-- Legends are re-implemented as a `gTree` object internally. `Legend()` and `packLegend()` all

-  returns a `Legends` object. This object can be treated as a single graphic element and can be drawn by

-  specifying the positions on the viewport. (https://jokergoo.github.io/ComplexHeatmap-reference/book/legends.html)

-- Positions of legend labels are automatically adjusted if they overlap.

-- A list of legends are automatically wrapped into multiple columns or rows if they are too long and

-  exceed the plotting region.

-

-## oncoPrint() function

-

-- It automatially tests whether functions in `alter_fun` are vectorized.

-- The oncoPrint barplot annotations are now controlled by `anno_oncoprint_barplot()` and they are

-  basically normal heatmap annotations. Also axis is controlled in `anno_oncoprint_barplot()`.

-- `barplot_ignore` is removed and the subset of alterations in directly controlled in

-  `anno_oncoprint_barplot()`.

-- Similar as `Heatmap()`, all the argument related to the size of annotations are removed and they

-  should be set directly in `HeatmapAnnotation()` or `anno_oncoprint_barplot()`.

-- New arguments `remove_empty_rows` and `remove_empty_columns`. If the number of rows and columns

-  gets smaller, all the oncoPrint components (e.g. row names, annotations) will be adjusted as well.

-- `oncoPrint()` now returns a `Heatmap` object which can be concatenated to other

-  heatmaps/annotations horizontally or vertically.

-

-## densityHeatmap() function

-

-- Columns can be clustered by the Kolmogorov-Smirnov distance between distributions.

-- `densityHeatmap()` returns a vertical heatmap that more heatmaps and annotations can concatenate

-  to it vertically.

-

-## UpSet() function

-- Add a new `UpSet()` function to make UpSet plots and can be concatenated to other heatmaps/annotations. (https://jokergoo.github.io/ComplexHeatmap-reference/book/upset-plot.html)

-

@@ -26,26 +26,33 @@ library(ComplexHeatmap)

 ### There is no plot comming out after running Heatmap() function.

-In this case, you need to use `draw()` function explicitly. See https://jokergoo.github.io/ComplexHeatmap-reference/book/a-single-heatmap.html#plot-the-heatmap and https://jokergoo.github.io/ComplexHeatmap-reference/book/a-list-of-heatmaps.html#plot-the-heamtap-list.

+In this case, you need to use `draw()` function explicitly. See

+https://jokergoo.github.io/ComplexHeatmap-reference/book/a-single-heatmap.html#plot-the-heatmap

+and

+https://jokergoo.github.io/ComplexHeatmap-reference/book/a-list-of-heatmaps.html#plot-the-heamtap-list.

 ### Retrieve orders and dendrograms.

-For retrieving orders and dendrograms from a single heatmap. See https://jokergoo.github.io/ComplexHeatmap-reference/book/a-single-heatmap.html#get-orders-and-dendrograms-from-heatmap.

+For retrieving orders and dendrograms from a single heatmap. See

+https://jokergoo.github.io/ComplexHeatmap-reference/book/a-single-heatmap.html#get-orders-and-dendrograms-from-heatmap.

-For retrieving orders and dendrograms from a list of heatmaps. See https://jokergoo.github.io/ComplexHeatmap-reference/book/a-list-of-heatmaps.html#get-orders-and-dendrograms-from-a-list-of-heatmaps.

+For retrieving orders and dendrograms from a list of heatmaps. See

+https://jokergoo.github.io/ComplexHeatmap-reference/book/a-list-of-heatmaps.html#get-orders-and-dendrograms-from-a-list-of-heatmaps.

 ### How should I control the height or width of the heatmap annotations?

-For complex annotations generated by `anno_*()` functions, width or height should be set inside 

-the `anno_*()` function, such as `anno_points(..., height = ...)`. The size of simple annotations

-is controlled by `anno_simple_size`. The `width`/`height` and `annotation_width`/`annotation_height`

-are used to adjust the size for multiple annotations which are put in one `HeatmapAnnotation` object.

-See https://jokergoo.github.io/ComplexHeatmap-reference/book/heatmap-annotations.html#multiple-annotations

+For complex annotations generated by `anno_*()` functions, width or height

+should be set inside the `anno_*()` function, such as `anno_points(..., height = ...)`. The size of simple annotations is controlled by `anno_simple_size`.

+The `width`/`height` and `annotation_width`/`annotation_height` are used to

+adjust the size for multiple annotations which are put in one

+`HeatmapAnnotation` object. See

+https://jokergoo.github.io/ComplexHeatmap-reference/book/heatmap-annotations.html#multiple-annotations

 ### How should I control the axes of the annotations?

-In the annotation functions `anno_*()`, the argument `axis_param` can be used to set the axes. The value

-should be a list and the default settings for axis can be get by:

+In the annotation functions `anno_*()`, the argument `axis_param` can be used

+to set the axes. The value should be a list and the default settings for axis

+can be get by:

 ```{r, eval = FALSE}

 default_axis_param("column")

@@ -54,16 +61,19 @@ default_axis_param("row")

 ### How to control the style of legends?

-The style of legends can be controlled by `heatmap_legend_param` in `Heatmap()`, or

-`annotation_legend_param` in `HeatmapAnnotation()`. The parameters for controlling legends are those

-arguments in `Legend()` function. See

+The style of legends can be controlled by `heatmap_legend_param` in

+`Heatmap()`, or `annotation_legend_param` in `HeatmapAnnotation()`. The

+parameters for controlling legends are those arguments in `Legend()` function.

+See

 https://jokergoo.github.io/ComplexHeatmap-reference/book/legends.html#heatmap-and-annotation-legends.

 ### Some text are cut by the plotting region.

-The layout of the **ComplexHeatmap** is not perfect that it is still possible some of the text are

-drawn out of the plotting region. In this case, you can set the `padding` argument in `draw()` function

-to increase the blank areas around the final plot. See https://jokergoo.github.io/ComplexHeatmap-reference/book/a-list-of-heatmaps.html#manually-increase-space-around-the-plot.

+The layout of the **ComplexHeatmap** is not perfect that it is still possible

+some of the text are drawn out of the plotting region. In this case, you can

+set the `padding` argument in `draw()` function to increase the blank areas

+around the final plot. See

+https://jokergoo.github.io/ComplexHeatmap-reference/book/a-list-of-heatmaps.html#manually-increase-space-around-the-plot.

 ### Can the heatmaps be added vertically?

@@ -76,8 +86,8 @@ methematical expression.

 ### I have many heatmaps and I want to put them into different panels for a big figure for my paper.

-You can set `newpage = FALSE` in `draw()` function and use `grid.layout()` to manage the layout of

-your panels. 

+You can set `newpage = FALSE` in `draw()` function and use `grid.layout()` to

+manage the layout of your panels.

 ```{r, eval = FALSE}

 pushViewport(viewport(layout = grid.layout(...)))

@@ -87,8 +97,9 @@ popViewport()

 ...

 ```

-But I more suggest to use `grid.grabExpr()` to directly capture the output of the

-heatmap and later draw the whole plot as a single graphic element by `grid.draw()`.

+But I more suggest to use `grid.grabExpr()` to directly capture the output of

+the heatmap and later draw the whole plot as a single graphic element by

+`grid.draw()`.

 ```{r, eval = FALSE}

 ht_grob = grid.grabExpr(draw(ht, ...))

@@ -102,7 +113,8 @@ popViewport()

 ### I have a matrix with too many rows and I want to simplify the row dendrogram.

-You can first group your rows into several groups and make a group-level dendrogram on it. See following example:

+You can first group your rows into several groups and make a group-level

+dendrogram on it. See following example:

 ```{r}

 m = matrix(rnorm(1000*10), nr = 1000)

@@ -115,13 +127,14 @@ Heatmap(m, cluster_rows = cluster_within_group(t(m), group),

 ### I have a matrix with huge nunmber of rows or columns, what is the efficient way to visualize it?

 Heatmap is used to visualize the global patterns of your matrix while not

-every single row or column. I suggest to random sample rows or columns

-into a reasonable small number, and the final heatmap should be the same as if

-you still insist to use the full matrix.

+every single row or column. I suggest to random sample rows or columns into a

+reasonable small number, and the final heatmap should be the same as if you

+still insist to use the full matrix.

 ### How to add axes for dendrograms?

-You need to use `decorate_row_dend()` or `decorate_column_dend()` to manually add the axes. See following examples:

+You need to use `decorate_row_dend()` or `decorate_column_dend()` to manually

+add the axes. See following examples:

 ```{r}

 m = matrix(rnorm(100), 10)

@@ -145,3 +158,14 @@ Note for the left row dendrogram, the x-axis is from right to left, you need to

 and `label` in `grid.xaxis()` function.

 You can also check `annotation_axis_grob()` function (later use `grid.draw()` to draw the axes) to draw a nicer axis.

+

+### I still have a problem with the package and I am lost in the see of the huge vignette.

+

+The vignette (https://jokergoo.github.io/ComplexHeatmap-reference/book/)

+contains huge number of examples and plots showing different usage of the

+package. It is sometimes not easy to find the solution you are looking for. In

+this case, don't hesitate to write me an email. I am glad to answer all of your

+questions!

+

+

+