update

DESCRIPTION

@@ -2,7 +2,7 @@ Package: ComplexHeatmap
 Type: Package
 Title: Make Complex Heatmaps
 Version: 2.9.4
-Date: 2021-09-08
+Date: 2021-10-17
 Author: Zuguang Gu
 Maintainer: Zuguang Gu <[email protected]>
 Depends: R (>= 3.5.0), methods, grid, graphics, stats, grDevices

NAMESPACE

@@ -139,6 +139,7 @@ export("alter_graphic")
 export("anno_barplot")
 export("anno_block")
 export("anno_boxplot")
+export("anno_customize")
 export("anno_density")
 export("anno_empty")
 export("anno_histogram")
@@ -224,6 +225,7 @@ export("set_size")
 export("smartAlign2")
 export("subset_gp")
 export("subset_matrix_by_row")
+export("subset_no")
 export("subset_vector")
 export("test_alter_fun")
 export("unify_mat_list")

NEWS

@@ -5,6 +5,7 @@ CHANGES in VERSION 2.9.4
 * Rasterization: the default maximal size for temporary image is set to 30000 px (both for width and height).
 * add a new argument `beside` in `anno_barplot()` to position bars beside each other.
 * add `plot()` method for `Heatmap` and `HeatmapList` classes.
+* add `anno_customize()`.
 
 ========================
 

R/00_S4_generic_methods.R

@@ -1,32 +1,32 @@
-setGeneric('add_heatmap', function(object, ...) standardGeneric('add_heatmap'))
-setGeneric('row_dend', function(object, ...) standardGeneric('row_dend'))
+setGeneric('set_component_height', function(object, ...) standardGeneric('set_component_height'))
+setGeneric('draw_heatmap_list', function(object, ...) standardGeneric('draw_heatmap_list'))
+setGeneric('heatmap_legend_size', function(object, ...) standardGeneric('heatmap_legend_size'))
+setGeneric('draw_title', function(object, ...) standardGeneric('draw_title'))
+setGeneric('set_component_width', function(object, ...) standardGeneric('set_component_width'))
+setGeneric('map_to_colors', function(object, ...) standardGeneric('map_to_colors'))
+setGeneric('component_width', function(object, ...) standardGeneric('component_width'))
+setGeneric('draw_annotation', function(object, ...) standardGeneric('draw_annotation'))
+setGeneric('re_size', function(object, ...) standardGeneric('re_size'))
+setGeneric('copy_all', function(object, ...) standardGeneric('copy_all'))
+setGeneric('make_column_cluster', function(object, ...) standardGeneric('make_column_cluster'))
+setGeneric('attach_annotation', function(object, ...) standardGeneric('attach_annotation'))
+setGeneric('get_color_mapping_list', function(object, ...) standardGeneric('get_color_mapping_list'))
 setGeneric('annotation_legend_size', function(object, ...) standardGeneric('annotation_legend_size'))
-setGeneric('make_layout', function(object, ...) standardGeneric('make_layout'))
+setGeneric('prepare', function(object, ...) standardGeneric('prepare'))
 setGeneric('draw_dimnames', function(object, ...) standardGeneric('draw_dimnames'))
 setGeneric('color_mapping_legend', function(object, ...) standardGeneric('color_mapping_legend'))
-setGeneric('copy_all', function(object, ...) standardGeneric('copy_all'))
-setGeneric('draw_dend', function(object, ...) standardGeneric('draw_dend'))
-setGeneric('attach_annotation', function(object, ...) standardGeneric('attach_annotation'))
+setGeneric('adjust_heatmap_list', function(object, ...) standardGeneric('adjust_heatmap_list'))
 setGeneric('component_height', function(object, ...) standardGeneric('component_height'))
-setGeneric('get_color_mapping_list', function(object, ...) standardGeneric('get_color_mapping_list'))
-setGeneric('column_order', function(object, ...) standardGeneric('column_order'))
-setGeneric('set_component_height', function(object, ...) standardGeneric('set_component_height'))
+setGeneric('row_order', function(object, ...) standardGeneric('row_order'))
 setGeneric('draw_heatmap_body', function(object, ...) standardGeneric('draw_heatmap_body'))
-setGeneric('re_size', function(object, ...) standardGeneric('re_size'))
+setGeneric('make_layout', function(object, ...) standardGeneric('make_layout'))
+setGeneric('row_dend', function(object, ...) standardGeneric('row_dend'))
 setGeneric('draw_heatmap_legend', function(object, ...) standardGeneric('draw_heatmap_legend'))
-setGeneric('prepare', function(object, ...) standardGeneric('prepare'))
-setGeneric('draw_annotation', function(object, ...) standardGeneric('draw_annotation'))
-setGeneric('map_to_colors', function(object, ...) standardGeneric('map_to_colors'))
-setGeneric('draw_annotation_legend', function(object, ...) standardGeneric('draw_annotation_legend'))
-setGeneric('component_width', function(object, ...) standardGeneric('component_width'))
-setGeneric('get_legend_param_list', function(object, ...) standardGeneric('get_legend_param_list'))
-setGeneric('column_dend', function(object, ...) standardGeneric('column_dend'))
-setGeneric('heatmap_legend_size', function(object, ...) standardGeneric('heatmap_legend_size'))
-setGeneric('draw_title', function(object, ...) standardGeneric('draw_title'))
-setGeneric('draw_heatmap_list', function(object, ...) standardGeneric('draw_heatmap_list'))
-setGeneric('adjust_heatmap_list', function(object, ...) standardGeneric('adjust_heatmap_list'))
 setGeneric('draw', function(object, ...) standardGeneric('draw'))
-setGeneric('set_component_width', function(object, ...) standardGeneric('set_component_width'))
+setGeneric('column_dend', function(object, ...) standardGeneric('column_dend'))
+setGeneric('column_order', function(object, ...) standardGeneric('column_order'))
+setGeneric('draw_annotation_legend', function(object, ...) standardGeneric('draw_annotation_legend'))
 setGeneric('make_row_cluster', function(object, ...) standardGeneric('make_row_cluster'))
-setGeneric('row_order', function(object, ...) standardGeneric('row_order'))
-setGeneric('make_column_cluster', function(object, ...) standardGeneric('make_column_cluster'))
+setGeneric('get_legend_param_list', function(object, ...) standardGeneric('get_legend_param_list'))
+setGeneric('draw_dend', function(object, ...) standardGeneric('draw_dend'))
+setGeneric('add_heatmap', function(object, ...) standardGeneric('add_heatmap'))

R/AnnotationFunction-function.R

@@ -101,6 +101,18 @@ subset_matrix_by_row = function(x, i) x[i, , drop = FALSE]
 #
 subset_vector = function(x, i) x[i]
 
+# == title
+# Do not do subseting
+#
+# == param
+# -x A vector.
+# -i The indices.
+#
+# == details
+# Mainly used for constructing the `AnnotationFunction-class` object.
+#
+subset_no = function(x, i) x
+
 # == title
 # Simple Annotation
 #
@@ -4073,4 +4085,119 @@ anno_zoom = function(align_to, panel_fun = function(index, nm = NULL) { grid.rec
 	return(anno)
 }
 
+# == title
+# Customized annotation
+#
+# == param
+# -x A categorical variable.
+# -graphics A list of functions that define graphics for each level in ``x``.
+# -which Is it a row annotation or a column annotation?
+# -width Width of the annotation. The value should be an absolute unit. Width is not allowed to be set for column annotation.
+# -height Height of the annotation. The value should be an absolute unit. Height is not allowed to be set for row annotation.
+# -border Whether to draw border.
+# -verbose Whether to print messages.
+#
+# == details
+# Functions in ``graphics`` define simple graphics drawn in each annotation cell. The function takes four arguments:
+#
+# -x,y Center of the annotation cell.
+# -w,h Width and height of the annotation cell.
+#
+# == value
+# An annotation function which can be used in `HeatmapAnnotation`.
+#
+# == example
+# x = sort(sample(letters[1:3], 10, replace = TRUE))
+# graphics = list(
+#     "a" = function(x, y, w, h) grid.points(x, y, pch = 16),
+#     "b" = function(x, y, w, h) grid.rect(x, y, w*0.8, h*0.8, gp = gpar(fill = "red")),
+#     "c" = function(x, y, w, h) grid.segments(x - 0.5*w, y - 0.5*h, x + 0.5*w, y + 0.5*h, gp = gpar(lty = 2))
+# )
+#
+# anno = anno_customize(x, graphics = graphics)
+#
+# m = matrix(rnorm(100), 10)
+# Heatmap(m, top_annotation = HeatmapAnnotation(bar = x, foo = anno))
+#
+# # Add legends for `foo`
+# ht = Heatmap(m, top_annotation = HeatmapAnnotation(bar = x, foo = anno))
+# lgd = Legend(title = "foo", at = names(graphics), graphics = graphics)
+# draw(ht, annotation_legend_list = list(lgd))
+anno_customize = function(x, graphics = list(), which = c("column", "row"),  
+	border = TRUE, width = NULL, height = NULL, verbose = TRUE) {
+
+	if(is.null(.ENV$current_annotation_which)) {
+		which = match.arg(which)[1]
+	} else {
+		which = .ENV$current_annotation_which
+	}
+
+	anno_size = anno_width_and_height(which, width, height, unit(5, "mm"))
+
+	value = as.character(x)
+	n = length(value)
+
+	if(verbose) {
+		nm = setdiff(value, names(graphics))
+		if(length(nm)) {
+			message(qq("Note: following levels in `x` have no graphics defined:\n    @{paste(nm, collapse = ', ')}.\nSet `verbose = FALSE` in `anno_customize()` to turn off this message."))
+		}
+	}
+
+	row_fun = function(index, k = 1, N = 1) {
+
+		n = length(index)
+
+		pushViewport(viewport(yscale = c(0.5, n+0.5)))
+		for(i in seq_len(n)) {
+			if(!is.null(graphics[[ value[index[i]] ]])) {
+				fun = graphics[[ value[index[i]] ]]
+				pushViewport(viewport(y = n-i+1, height = 1, default.units = "native"))
+				fun(unit(0.5, "npc"), unit(0.5, "npc"), unit(1, "npc"), unit(1, "npc"))
+				popViewport()
+			}
+		}
+		if(border) grid.rect(gp = gpar(fill = "transparent"))
+		popViewport()
+	}
+
+	column_fun = function(index, k = 1, N = 1) {
+
+		n = length(index)
+
+		pushViewport(viewport(xscale = c(0.5, n+0.5)))
+		for(i in seq_len(n)) {
+			if(!is.null(graphics[[ value[index[i]] ]])) {
+				fun = graphics[[ value[index[i]] ]]
+				pushViewport(viewport(x = i, width = 1, default.units = "native"))
+				fun(unit(0.5, "npc"), unit(0.5, "npc"), unit(1, "npc"), unit(1, "npc"))
+				popViewport()
+			}
+		}
+		if(border) grid.rect(gp = gpar(fill = "transparent"))
+		popViewport()
+	}
+
+	if(which == "row") {
+		fun = row_fun
+	} else if(which == "column") {
+		fun = column_fun
+	}
+
+	anno = AnnotationFunction(
+		fun = fun,
+		fun_name = "anno_customize",
+		which = which,
+		width = anno_size$width,
+		height = anno_size$height,
+		n = n,
+		var_import = list(value, border, graphics)
+	)
+
+	anno@subset_rule$value = subset_vector
+
+	anno@subsetable = TRUE
+
+	return(anno) 
+}
 

R/Heatmap-class.R

@@ -360,7 +360,10 @@ Heatmap = function(matrix, col, name,
 
     if(is.data.frame(matrix)) {
         if(verbose) qqcat("convert data frame to matrix\n")
-        warning_wrap("The input is a data frame, convert it to the matrix.")
+        warning_wrap("The input is a data frame, convert it to a matrix.")
+        if(!all(sapply(matrix, is.numeric))) {
+            warning_wrap("Note: not all columns in the data frame are numeric. The data frame will be converted into a character matrix.")
+        }
         matrix = as.matrix(matrix)
     }
     fa_level = NULL

R/oncoPrint.R

@@ -135,7 +135,7 @@ oncoPrint = function(mat, name,
 
 		## check whether there are NA values in the matrix
 		if(any(is.na(mat))) {
-			message_wrap("Found NA values in the matrix and treat as no alteration. If `NA` means no alteration, you can explicitly set it to empty strings like ''. If `NA` is an alteration type, you should format it to a string like `'NA'` and define a graphic for it.")
+			message_wrap("Found NA values in the matrix and treat as no alteration. If `NA` means no alteration, you can explicitly set it to empty strings like ''. If `NA` is an alteration type, you should format it to a string like `'NA'` and define graphics for it.")
 		}
 
 		mat_list = lapply(all_type, function(type) {

man/add_heatmap-dispatch.Rd

@@ -10,9 +10,9 @@ Method dispatch page for \code{add_heatmap}.
 \code{add_heatmap} can be dispatched on following classes:
 
 \itemize{
+\item \code{\link{add_heatmap,Heatmap-method}}, \code{\link{Heatmap-class}} class method
 \item \code{\link{add_heatmap,HeatmapList-method}}, \code{\link{HeatmapList-class}} class method
 \item \code{\link{add_heatmap,HeatmapAnnotation-method}}, \code{\link{HeatmapAnnotation-class}} class method
-\item \code{\link{add_heatmap,Heatmap-method}}, \code{\link{Heatmap-class}} class method
 }
 }
 \examples{

man/anno_customize.Rd

@@ -0,0 +1,52 @@
+\name{anno_customize}
+\alias{anno_customize}
+\title{
+Customized annotation
+}
+\description{
+Customized annotation
+}
+\usage{
+anno_customize(x, graphics = list(), which = c("column", "row"),
+    border = TRUE, width = NULL, height = NULL, verbose = TRUE)
+}
+\arguments{
+
+  \item{x}{A categorical variable.}
+  \item{graphics}{A list of functions that define graphics for each level in \code{x}.}
+  \item{which}{Is it a row annotation or a column annotation?}
+  \item{width}{Width of the annotation. The value should be an absolute unit. Width is not allowed to be set for column annotation.}
+  \item{height}{Height of the annotation. The value should be an absolute unit. Height is not allowed to be set for row annotation.}
+  \item{border}{Whether to draw border.}
+  \item{verbose}{Whether to print messages.}
+
+}
+\details{
+Functions in \code{graphics} define simple graphics drawn in each annotation cell. The function takes four arguments:
+
+\describe{
+  \item{x,y}{Center of the annotation cell.}
+  \item{w,h}{Width and height of the annotation cell.}
+}
+}
+\value{
+An annotation function which can be used in \code{\link{HeatmapAnnotation}}.
+}
+\examples{
+x = sort(sample(letters[1:3], 10, replace = TRUE))
+graphics = list(
+    "a" = function(x, y, w, h) grid.points(x, y, pch = 16),
+    "b" = function(x, y, w, h) grid.rect(x, y, w*0.8, h*0.8, gp = gpar(fill = "red")),
+    "c" = function(x, y, w, h) grid.segments(x - 0.5*w, y - 0.5*h, x + 0.5*w, y + 0.5*h, gp = gpar(lty = 2))
+)
+
+anno = anno_customize(x, graphics = graphics)
+
+m = matrix(rnorm(100), 10)
+Heatmap(m, top_annotation = HeatmapAnnotation(bar = x, foo = anno))
+
+# Add legends for `foo`
+ht = Heatmap(m, top_annotation = HeatmapAnnotation(bar = x, foo = anno))
+lgd = Legend(title = "foo", at = names(graphics), graphics = graphics)
+draw(ht, annotation_legend_list = list(lgd))
+}

man/column_dend-dispatch.Rd

@@ -10,8 +10,8 @@ Method dispatch page for \code{column_dend}.
 \code{column_dend} can be dispatched on following classes:
 
 \itemize{
-\item \code{\link{column_dend,HeatmapList-method}}, \code{\link{HeatmapList-class}} class method
 \item \code{\link{column_dend,Heatmap-method}}, \code{\link{Heatmap-class}} class method
+\item \code{\link{column_dend,HeatmapList-method}}, \code{\link{HeatmapList-class}} class method
 }
 }
 \examples{

man/column_order-dispatch.Rd

@@ -10,8 +10,8 @@ Method dispatch page for \code{column_order}.
 \code{column_order} can be dispatched on following classes:
 
 \itemize{
-\item \code{\link{column_order,HeatmapList-method}}, \code{\link{HeatmapList-class}} class method
 \item \code{\link{column_order,Heatmap-method}}, \code{\link{Heatmap-class}} class method
+\item \code{\link{column_order,HeatmapList-method}}, \code{\link{HeatmapList-class}} class method
 }
 }
 \examples{

man/draw-dispatch.Rd

@@ -10,11 +10,11 @@ Method dispatch page for \code{draw}.
 \code{draw} can be dispatched on following classes:
 
 \itemize{
-\item \code{\link{draw,HeatmapList-method}}, \code{\link{HeatmapList-class}} class method
+\item \code{\link{draw,AnnotationFunction-method}}, \code{\link{AnnotationFunction-class}} class method
 \item \code{\link{draw,SingleAnnotation-method}}, \code{\link{SingleAnnotation-class}} class method
 \item \code{\link{draw,HeatmapAnnotation-method}}, \code{\link{HeatmapAnnotation-class}} class method
-\item \code{\link{draw,AnnotationFunction-method}}, \code{\link{AnnotationFunction-class}} class method
 \item \code{\link{draw,Heatmap-method}}, \code{\link{Heatmap-class}} class method
+\item \code{\link{draw,HeatmapList-method}}, \code{\link{HeatmapList-class}} class method
 \item \code{\link{draw,Legends-method}}, \code{\link{Legends-class}} class method
 }
 }

man/draw_title-dispatch.Rd

@@ -10,8 +10,8 @@ Method dispatch page for \code{draw_title}.
 \code{draw_title} can be dispatched on following classes:
 
 \itemize{
-\item \code{\link{draw_title,Heatmap-method}}, \code{\link{Heatmap-class}} class method
 \item \code{\link{draw_title,HeatmapList-method}}, \code{\link{HeatmapList-class}} class method
+\item \code{\link{draw_title,Heatmap-method}}, \code{\link{Heatmap-class}} class method
 }
 }
 \examples{

man/plot.HeatmapAnnotation.Rd

@@ -18,4 +18,5 @@ Draw heatmap annotations
 \examples{
 # There is no example
 NULL
+
 }

man/row_dend-dispatch.Rd

@@ -10,8 +10,8 @@ Method dispatch page for \code{row_dend}.
 \code{row_dend} can be dispatched on following classes:
 
 \itemize{
-\item \code{\link{row_dend,Heatmap-method}}, \code{\link{Heatmap-class}} class method
 \item \code{\link{row_dend,HeatmapList-method}}, \code{\link{HeatmapList-class}} class method
+\item \code{\link{row_dend,Heatmap-method}}, \code{\link{Heatmap-class}} class method
 }
 }
 \examples{

man/row_order-dispatch.Rd

@@ -10,8 +10,8 @@ Method dispatch page for \code{row_order}.
 \code{row_order} can be dispatched on following classes:
 
 \itemize{
-\item \code{\link{row_order,Heatmap-method}}, \code{\link{Heatmap-class}} class method
 \item \code{\link{row_order,HeatmapList-method}}, \code{\link{HeatmapList-class}} class method
+\item \code{\link{row_order,Heatmap-method}}, \code{\link{Heatmap-class}} class method
 }
 }
 \examples{

man/show-dispatch.Rd

@@ -10,11 +10,11 @@ Method dispatch page for \code{show}.
 \code{show} can be dispatched on following classes:
 
 \itemize{
+\item \code{\link{show,ColorMapping-method}}, \code{\link{ColorMapping-class}} class method
 \item \code{\link{show,SingleAnnotation-method}}, \code{\link{SingleAnnotation-class}} class method
+\item \code{\link{show,AnnotationFunction-method}}, \code{\link{AnnotationFunction-class}} class method
 \item \code{\link{show,HeatmapList-method}}, \code{\link{HeatmapList-class}} class method
 \item \code{\link{show,HeatmapAnnotation-method}}, \code{\link{HeatmapAnnotation-class}} class method
-\item \code{\link{show,ColorMapping-method}}, \code{\link{ColorMapping-class}} class method
-\item \code{\link{show,AnnotationFunction-method}}, \code{\link{AnnotationFunction-class}} class method
 \item \code{\link{show,Heatmap-method}}, \code{\link{Heatmap-class}} class method
 }
 }