@@ -186,6 +186,14 @@ AnnotationFunction = function(fun, fun_name = "", which = c("column", "row"), ce

 		subsettable = TRUE

 	}

+	if(length(var_import) == 0) {

+		global_vars = codetools::findGlobals(fun, merge = FALSE)$variables

+

+        for(v in global_vars) {

+           var_import[[v]] = get(v, envir = environment(fun))

+        }

+	}

+

 	if(length(var_import)) {

 		anno@var_env = new.env()

 		if(is.character(var_import)) {

@@ -24,7 +24,7 @@ AnnotationFunction = setClass("AnnotationFunction",

 		var_env = "environment",

 		fun = "function",

 		subset_rule = "list",

-		subsetable = "logical",

+		subsettable = "logical",

 		data_scale = "numeric",

 		extended = "ANY",

 		show_name = "logical"

@@ -34,7 +34,7 @@ AnnotationFunction = setClass("AnnotationFunction",

 		width = unit(1, "npc"),

 		height = unit(1, "npc"),

 		subset_rule = list(),

-		subsetable = FALSE,

+		subsettable = FALSE,

 		data_scale = c(0, 1),

 		n = NA_integer_,

 		extended = unit(c(0, 0, 0, 0), "mm"),

@@ -92,8 +92,8 @@ anno_width_and_height = function(which, width = NULL, height = NULL,

 # -data_scale The data scale on the data axis (y-axis for column annotation and x-axis for row annotation). It is only used

 #             when `decorate_annotation` is used with "native" unit coordinates.

 # -subset_rule The rule of subsetting variables in ``var_import``. It should be set when users want the final object to

-#              be subsetable. See **Details** section.

-# -subsetable Whether the object is subsetable?

+#              be subsettable. See **Details** section.

+# -subsettable Whether the object is subsettable?

 # -show_name It is used to turn off the drawing of annotation names in `HeatmapAnnotation`. Annotations always have names

 #        associated and normally they will be drawn beside the annotation graphics to tell what the annotation is about.

 #        e.g. the annotation names put beside the points annotation graphics. However, for some of the annotations, the names

@@ -133,7 +133,7 @@ anno_width_and_height = function(which, width = NULL, height = NULL,

 #     },

 #     var_import = list(x = x),

 #     n = 10,

-#     subsetable = TRUE,

+#     subsettable = TRUE,

 #     height = unit(2, "cm")

 # )

 # m = rbind(1:10, 11:20)

@@ -141,7 +141,7 @@ anno_width_and_height = function(which, width = NULL, height = NULL,

 # Heatmap(m, top_annotation = HeatmapAnnotation(foo = anno1), column_km = 2)

 AnnotationFunction = function(fun, fun_name = "", which = c("column", "row"), cell_fun = NULL,

 	var_import = list(), n = NA, data_scale = c(0, 1), subset_rule = list(), 

-	subsetable = length(subset_rule) > 0, show_name = TRUE, width = NULL, height = NULL) {

+	subsettable = length(subset_rule) > 0, show_name = TRUE, width = NULL, height = NULL) {

 	which = match.arg(which)[1]

@@ -183,7 +183,7 @@ AnnotationFunction = function(fun, fun_name = "", which = c("column", "row"), ce

 				}

 			}

 		}

-		subsetable = TRUE

+		subsettable = TRUE

 	}

 	if(length(var_import)) {

@@ -232,13 +232,13 @@ AnnotationFunction = function(fun, fun_name = "", which = c("column", "row"), ce

 		}

 	}

-	if(missing(subsetable)) {

+	if(missing(subsettable)) {

 		# is user defined subset rule

 		if(length(anno@subset_rule)) {

-			anno@subsetable = TRUE

+			anno@subsettable = TRUE

 		}

 	} else {

-		anno@subsetable = subsetable

+		anno@subsettable = subsettable

 	}

 	return(anno)

@@ -263,8 +263,8 @@ AnnotationFunction = function(fun, fun_name = "", which = c("column", "row"), ce

 	if(nargs() == 1) {

 		return(x)

 	} else {

-		if(!x@subsetable) {

-			stop_wrap("This object is not subsetable.")

+		if(!x@subsettable) {

+			stop_wrap("This object is not subsettable.")

 		}

 		x = copy_all(x)

 		if(x@fun_name == "anno_mark") {

@@ -425,12 +425,12 @@ setMethod(f = "show",

 	var_imported = names(object@var_env)

 	if(length(var_imported)) {

 		cat("  imported variable:", paste(var_imported, collapse = ", "), "\n")

-		var_subsetable = names(object@subset_rule)

-		if(length(var_subsetable)) {

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

+		var_subsettable = names(object@subset_rule)

+		if(length(var_subsettable)) {

+			cat("  subsettable variable:", paste(var_subsettable, collapse = ", "), "\n")

 		}

 	}

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

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

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

 	for(i in 1:4) {

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

@@ -85,6 +85,7 @@ anno_width_and_height = function(which, width = NULL, height = NULL,

 # -fun A function which defines how to draw the annotation. See **Details** section.

 # -fun_name The name of the function. It is only used for printing the object.

 # -which Whether it is drawn as a column annotation or a row annotation?

+# -cell_fun A simplified version of ``fun``. ``cell_fun`` only accepts one single index and it draws repeatedly in each annotation cell.

 # -var_import The names of the variables or the variable themselves that the annotation function depends on. See **Details** section.

 # -n Number of observations in the annotation. It is not mandatory, but it is better to provide this information

 #   so that the higher order `HeatmapAnnotation` knows it and it can perform check on the consistency of annotations and heatmaps.

@@ -138,7 +139,7 @@ anno_width_and_height = function(which, width = NULL, height = NULL,

 # m = rbind(1:10, 11:20)

 # Heatmap(m, top_annotation = HeatmapAnnotation(foo = anno1))

 # Heatmap(m, top_annotation = HeatmapAnnotation(foo = anno1), column_km = 2)

-AnnotationFunction = function(fun, fun_name = "", which = c("column", "row"), 

+AnnotationFunction = function(fun, fun_name = "", which = c("column", "row"), cell_fun = NULL,

 	var_import = list(), n = NA, data_scale = c(0, 1), subset_rule = list(), 

 	subsetable = length(subset_rule) > 0, show_name = TRUE, width = NULL, height = NULL) {

@@ -162,6 +163,29 @@ AnnotationFunction = function(fun, fun_name = "", which = c("column", "row"),

 	anno@n = n

 	anno@data_scale = data_scale

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

+		if(which == "column") {

+			fun = function(index, k, n) {

+				n = length(index)

+				for(i in seq_along(index)) {

+					pushViewport(viewport(x = i/n, width = 1/n, just = "right", default.units = "npc"))

+					cell_fun(index[i])

+					popViewport()

+				}

+			}

+		} else {

+			fun = function(index, k, n) {

+				n = length(index)

+				for(i in seq_along(index)) {

+					pushViewport(viewport(y = 1 - i/n, height = 1/n, just = "bottom", default.units = "npc"))

+					cell_fun(index[i])

+					popViewport()

+				}

+			}

+		}

+		subsetable = TRUE

+	}

+

 	if(length(var_import)) {

 		anno@var_env = new.env()

 		if(is.character(var_import)) {

@@ -245,9 +245,10 @@ AnnotationFunction = function(fun, fun_name = "", which = c("column", "row"),

 		x = copy_all(x)

 		if(x@fun_name == "anno_mark") {

 			called_args = attr(x, "called_args")

+			od = order(i)

 			i = sort(i)

 			l = called_args$at %in% i

-			called_args$at = which(i %in% called_args$at)

+			called_args$at = od[which(i %in% called_args$at)]

 			called_args$labels = called_args$labels[l]

 			called_args$link_gp = subset_gp(called_args$link_gp, l)

 			called_args$labels_gp = subset_gp(called_args$labels_gp, l)

@@ -244,8 +244,17 @@ AnnotationFunction = function(fun, fun_name = "", which = c("column", "row"),

 		}

 		x = copy_all(x)

 		if(x@fun_name == "anno_mark") {

-			ind_at = which(x@var_env[["at"]] %in% i)

+			called_args = attr(x, "called_args")

+			i = sort(i)

+			l = called_args$at %in% i

+			called_args$at = which(i %in% called_args$at)

+			called_args$labels = called_args$labels[l]

+			called_args$link_gp = subset_gp(called_args$link_gp, l)

+			called_args$labels_gp = subset_gp(called_args$labels_gp, l)

+			x2 = do.call(anno_mark, called_args)

+			return(x2)

 		}

+

 		for(var in names(x@subset_rule)) {

 			oe = try(x@var_env[[var]] <- x@subset_rule[[var]](x@var_env[[var]], i), silent = TRUE)

@@ -243,12 +243,17 @@ AnnotationFunction = function(fun, fun_name = "", which = c("column", "row"),

 			stop_wrap("This object is not subsetable.")

 		}

 		x = copy_all(x)

+		if(x@fun_name == "anno_mark") {

+			ind_at = which(x@var_env[["at"]] %in% i)

+		}

 		for(var in names(x@subset_rule)) {

+			

 			oe = try(x@var_env[[var]] <- x@subset_rule[[var]](x@var_env[[var]], i), silent = TRUE)

 			if(inherits(oe, "try-error")) {

 				message(paste0("An error when subsetting ", var))

 				stop_wrap(oe)

 			}

+			

 		}

 		if(is.logical(i)) {

 			x@n = sum(i)

@@ -312,13 +312,13 @@ setMethod(f = "draw",

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

 			grid.rect(y = 1, height = unit(1, "npc") + object@extended[1], just = "top",

 				gp = gpar(fill = "transparent", col = "red", lty = 2))

-		} else if(!identical(unit(0, "mm"), object@extended[[2]])) {

+		} else if(!identical(unit(0, "mm"), object@extended[2])) {

 			grid.rect(x = 1, width = unit(1, "npc") + object@extended[2], just = "right",

 				gp = gpar(fill = "transparent", col = "red", lty = 2))

-		} else if(!identical(unit(0, "mm"), object@extended[[3]])) {

+		} else if(!identical(unit(0, "mm"), object@extended[3])) {

 			grid.rect(y = 0, height = unit(1, "npc") + object@extended[3], just = "bottom",

 				gp = gpar(fill = "transparent", col = "red", lty = 2))

-		} else if(!identical(unit(0, "mm"), object@extended[[4]])) {

+		} else if(!identical(unit(0, "mm"), object@extended[4])) {

 			grid.rect(x = 0, width = unit(1, "npc") + object@extended[4], just = "left",

 				gp = gpar(fill = "transparent", col = "red", lty = 2))

 		}

@@ -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])) {

@@ -53,7 +53,7 @@ anno_width_and_height = function(which, width = NULL, height = NULL,

 			if(!is_abs_unit(height)) {

 				stop_wrap("height of the annotation can only be an absolute unit.")

 			} else {

-				height = convertHeight(height, "mm")

+				# height = convertHeight(height, "mm")

 			}

 		}

 		if(is.null(width)) {

@@ -67,7 +67,7 @@ anno_width_and_height = function(which, width = NULL, height = NULL,

 			if(!is_abs_unit(width)) {

 				stop_wrap("width of the annotation can only be an absolute unit.")

 			} else {

-				width = convertWidth(width, "mm")

+				# width = convertWidth(width, "mm")

 			}

 		}

 		if(is.null(height)) {

@@ -398,7 +398,6 @@ setMethod(f = "show",

 			cat(" ", as.character(object@extended[i]), "extension on the", dirt[i], "\n")

 		}

 	}

-	

 })

 # == title

@@ -268,6 +268,7 @@ AnnotationFunction = function(fun, fun_name = "", which = c("column", "row"),

 # -k Current slice index.

 # -n Total number of slices.

 # -test Is it in test mode? The value can be logical or a text which is plotted as the title of plot.

+# -... Pass to `grid::viewport`.

 #

 # == detail

 # Normally it is called internally by the `SingleAnnotation-class`.

@@ -277,7 +278,7 @@ AnnotationFunction = function(fun, fun_name = "", which = c("column", "row"),

 # 

 setMethod(f = "draw",

 	signature = "AnnotationFunction",

-	definition = function(object, index, k = 1, n = 1, test = FALSE) {

+	definition = function(object, index, k = 1, n = 1, test = FALSE, ...) {

 	if(is.character(test)) {

 		test2 = TRUE

@@ -302,7 +303,7 @@ setMethod(f = "draw",

     anno_width = object@width

     # names should be passed to the data viewport

-	pushViewport(viewport(width = anno_width, height = anno_height))

+	pushViewport(viewport(width = anno_width, height = anno_height, ...))

 	vp_name1 = current.viewport()$name

 	object@fun(index, k, n)

 	if(test2) {

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

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

 		}

 	}

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

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

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

 	for(i in 1:4) {

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

@@ -3,14 +3,13 @@

 # The AnnotationFunction Class

 #

 # == details

-# The heatmap annotation is basically graphics aligned to the heatmap columns

-# if it is column annotation or heatmap rows if it is row annotation, while

-# there is no restrictions for the graphic types, e.g. it can be heatmap-like

+# The heatmap annotation is basically graphics aligned to the heatmap columns or rows.

+# There is no restriction for the graphic types, e.g. it can be heatmap-like

 # annotation or points. Here the AnnotationFunction class is designed for

 # creating complex and flexible annotation graphics. As the main part of the class, it uses

 # a user-defined function to define the graphics. It also keeps information of

 # the size of the plotting regions of the annotation. And most importantly, it

-# allows subsetting of the annotation to draw a subset of the graphics, which

+# allows subsetting to the annotation to draw a subset of the graphics, which

 # is the base for the splitting of the annotations.

 #

 # See `AnnotationFunction` constructor for details.

@@ -108,96 +107,37 @@ anno_width_and_height = function(which, width = NULL, height = NULL,

 #        the width must be an absolute unit.

 #

 # == details

-# We use a normal R function defines how to draw the annotation graphics. As

-# expected, the main part of the AnnotationFunction class is this function.

-# The function defines how to draw at specific positions which correspond to

-# rows or columns in the heatmap. The function should have three arguments:

-# ``index``, ``k`` and ``n`` (the names of the arguments can be arbitory)

-# where ``k`` and ``n`` are optional. ``index`` corresponds to the indices of

-# rows or columns of the heatmap. The value of ``index`` is not necessarily to

-# be the whole row indices or column indices of the heatmap. It can be a

-# subset of the indices if the annotation is split into slices according to

-# the split of the heatmap. ``index`` is always reordered according to the

-# reordering of heatmap rows or columns (e.g. by clustering). So, ``index``

-# actually contains a list of row or column indices for the current slice

-# after row or column reordering.

-# 

-# As mentioned, annotation can be split into slices. ``k`` corresponds to the

-# current slice and ``n`` corresponds to the total number of slices. As you can image, 

-# when ``n > 1``, the annotation function will be executed for all ``k``s. The

-# information of ``k`` and ``n`` sometimes can be useful, for example, we want

-# to add axis ot the right side of a column annotation, if this column annotation

-# is split into several slices, the axis is only drawn when``k == n``.

-#

-# Since the function only allows ``index``, ``k`` and ``n``, the function

-# sometimes uses several external variables which can not be defined inside

-# the function, e.g. the data points for the annotation. These variables

-# should be imported into the AnnotationFunction class so that the function

-# can correctly find these variables (by ``var_import`` argument).

-#

-# One important feature for AnnotationFunction class is it can be subsetable.

-# To allow subsetting of the object, users need to define the rules for the

-# imported variables. The rules are simple function which

-# accpets the variable and indices, and returns the subset of the variable.

-# The subset rule functions implemented in this package are `subset_gp`,

-# `subset_matrix_by_row` and `subset_vector`. These three functions are enough

-# for most of the cases.

-#

-# In following, we defined three AnnotationFunction objects: 

-#

-# 1. It needs external variable and support subsetting

-#

-#	x = 1:10

-#	anno1 = AnnotationFunction(

-#		fun = function(index) {

-#			n = length(index)

-#			pushViewport(viewport())

-#			grid.points(1:n, x[index])

-#			popViewport()

-#		},

-#		var_imported = list(x = x),

-#		n = 10,

-#		subset_rule = list(x = subset_vector),

-#		subsetable = TRUE

-#	)

-#

-# 2. The data variable is defined inside the function and no need to import other variables.

-#

-#	anno2 = AnnotationFunction(

-#		fun = function(index) {

-#			x = 1:10

-#			n = length(index)

-#			pushViewport(viewport())

-#			grid.points(1:n, x[index])

-#			popViewport()

-#		},

-#		n = 10,

-#		subsetable = TRUE

-#	)

-#

-# 3. Only specify the function to the constructor. ``anno3`` is not subsettable.

-#

-#	anno3 = AnnotationFunction(

-#		fun = function(index) {

-#			x = 1:10

-#			n = length(index)

-#			pushViewport(viewport())

-#			grid.points(1:n, x[index])

-#			popViewport()

-#		}

-#	)

-#

-# As you can see from the examples, you need to push a viewport for graphics and finally pop the viewport.

-#

-# In the package, we have implemted quite a lot annotation function by `AnnotationFunction` constructor:

+# In the package, we have implemted quite a lot annotation functions by `AnnotationFunction` constructor:

 # `anno_empty`, `anno_image`, `anno_points`, `anno_lines`, `anno_barplot`, `anno_boxplot`, `anno_histogram`,

 # `anno_density`, `anno_joyplot`, `anno_horizon`, `anno_text` and `anno_mark`. These built-in annotation functions

 # support as both row annotations and column annotations and they are are all subsettable.

 #

-# == seealso

 # The build-in annotation functions are already enough for most of the analysis, nevertheless, if users

 # want to know more about how to construct the AnnotationFunction class manually, they can refer to

-# ComplexHeatmap Complete Reference ().

+# https://jokergoo.github.io/ComplexHeatmap-reference/book/heatmap-annotations.html#implement-new-annotation-functions.

+#

+# == value

+# A `AnnotationFunction-class` object which can be used in `HeatmapAnnotation`.

+#

+# == example

+# x = 1:10

+# anno1 = AnnotationFunction(

+#     fun = function(index, k, n) {

+#         n = length(index)

+#         pushViewport(viewport(xscale = c(0.5, n + 0.5), yscale = c(0, 10)))

+#         grid.rect()

+#         grid.points(1:n, x[index], default.units = "native")

+#         if(k == 1) grid.yaxis()

+#         popViewport()

+#     },

+#     var_import = list(x = x),

+#     n = 10,

+#     subsetable = TRUE,

+#     height = unit(2, "cm")

+# )

+# m = rbind(1:10, 11:20)

+# Heatmap(m, top_annotation = HeatmapAnnotation(foo = anno1))

+# Heatmap(m, top_annotation = HeatmapAnnotation(foo = anno1), column_km = 2)

 AnnotationFunction = function(fun, fun_name = "", which = c("column", "row"), 

 	var_import = list(), n = NA, data_scale = c(0, 1), subset_rule = list(), 

 	subsetable = length(subset_rule) > 0, show_name = TRUE, width = NULL, height = NULL) {

@@ -325,12 +265,12 @@ AnnotationFunction = function(fun, fun_name = "", which = c("column", "row"),

 # == param

 # -object The `AnnotationFunction-class` object.

 # -index Index of observations.

-# -k Current index of slice.

+# -k Current slice index.

 # -n Total number of slices.

 # -test Is it in test mode? The value can be logical or a text which is plotted as the title of plot.

 #

 # == detail

-# Normally it is called internally by the `SingleAnnotation` class.

+# Normally it is called internally by the `SingleAnnotation-class`.

 #

 # When ``test`` is set to ``TRUE``, the annotation graphic is directly drawn,

 # which is generally for testing purpose.

@@ -404,7 +344,7 @@ setMethod(f = "draw",

 # == detail 

 # In `AnnotationFunction-class`, there is an environment which

 # stores some external variables for the annotation function (specified by the

-# ``var_import`` argument by constructing the `AnnotationFunction-class`

+# ``var_import`` argument when constructing the `AnnotationFunction-class`

 # object. This `copy_all,AnnotationFunction-method` hard copies all the

 # variables into a new isolated environment.

 #

@@ -1,6 +1,6 @@

 # == title

-# The AnnotationFunction class

+# The AnnotationFunction Class

 #

 # == details

 # The heatmap annotation is basically graphics aligned to the heatmap columns

@@ -97,8 +97,8 @@ anno_width_and_height = function(which, width = NULL, height = NULL,

 # -show_name It is used to turn off the drawing of annotation names in `HeatmapAnnotation`. Annotations always have names

 #        associated and normally they will be drawn beside the annotation graphics to tell what the annotation is about.

 #        e.g. the annotation names put beside the points annotation graphics. However, for some of the annotations, the names

-#        are not necessarily to be drawn, such as text annotations drawn by `anno_text` or an empty annotation drawn by `anno_empty()`.

-#        In this case, when `show_names` is set to `FALSE`, there will be no annotation names drawn for the annotation.

+#        are not necessarily to be drawn, such as text annotations drawn by `anno_text` or an empty annotation drawn by `anno_empty`.

+#        In this case, when ``show_names`` is set to ``FALSE``, there will be no annotation names drawn for the annotation.

 # -width The width of the plotting region (the viewport) that the annotation is drawn. If it is a row annotation,

 #        the width must be an absolute unit. Since the ``AnnotationFunction`` object is always contained by the `SingleAnnotation-class`object,

 #        you can only set the width of row annotations or height of column annotations, while e.g. the height of the row annotation is always ``unit(1, "npc")``

@@ -348,6 +348,9 @@ setMethod(f = "draw",

 	if(test2) {

         grid.newpage()

         pushViewport(viewport(width = 0.8, height = 0.8))

+        if(is.na(object@n)) {

+        	object@n = 1

+        }

     }

     verbose = ht_opt$verbose

@@ -3,12 +3,14 @@

 # The AnnotationFunction class

 #

 # == details

-# The heatmap annotation is basically graphics aligned to the columns or heatmap if it is column annotation

-# or heatmap rows if it is row annotation, while the type of the graphics can be arbitory, e.g.

-# it can be heatmap-like or points. Here the AnnotationFunction class is designed for creating

-# complex and flexible annotation graphics. As the main part, it uses a use-defined function

-# to define the graphics. It also keeps information of the size of the plotting regions of the annotation.

-# And most importantly, it allows subsetting of the annotation to draw a subset of the graphics, which

+# The heatmap annotation is basically graphics aligned to the heatmap columns

+# if it is column annotation or heatmap rows if it is row annotation, while

+# there is no restrictions for the graphic types, e.g. it can be heatmap-like

+# annotation or points. Here the AnnotationFunction class is designed for

+# creating complex and flexible annotation graphics. As the main part of the class, it uses

+# a user-defined function to define the graphics. It also keeps information of

+# the size of the plotting regions of the annotation. And most importantly, it

+# allows subsetting of the annotation to draw a subset of the graphics, which

 # is the base for the splitting of the annotations.

 #

 # See `AnnotationFunction` constructor for details.

@@ -81,7 +83,7 @@ anno_width_and_height = function(which, width = NULL, height = NULL,

 # Constructor of AnnotationFunction Class

 #

 # == param

-# -fun A function which defines how to draw this annotation. See **Details** section.

+# -fun A function which defines how to draw the annotation. See **Details** section.

 # -fun_name The name of the function. It is only used for printing the object.

 # -which Whether it is drawn as a column annotation or a row annotation?

 # -var_import The names of the variables or the variable themselves that the annotation function depends on. See **Details** section.

@@ -92,36 +94,54 @@ anno_width_and_height = function(which, width = NULL, height = NULL,

 # -subset_rule The rule of subsetting variables in ``var_import``. It should be set when users want the final object to

 #              be subsetable. See **Details** section.

 # -subsetable Whether the object is subsetable?

+# -show_name It is used to turn off the drawing of annotation names in `HeatmapAnnotation`. Annotations always have names

+#        associated and normally they will be drawn beside the annotation graphics to tell what the annotation is about.

+#        e.g. the annotation names put beside the points annotation graphics. However, for some of the annotations, the names

+#        are not necessarily to be drawn, such as text annotations drawn by `anno_text` or an empty annotation drawn by `anno_empty()`.

+#        In this case, when `show_names` is set to `FALSE`, there will be no annotation names drawn for the annotation.

 # -width The width of the plotting region (the viewport) that the annotation is drawn. If it is a row annotation,

-#        the width must be an absolute unit.

+#        the width must be an absolute unit. Since the ``AnnotationFunction`` object is always contained by the `SingleAnnotation-class`object,

+#        you can only set the width of row annotations or height of column annotations, while e.g. the height of the row annotation is always ``unit(1, "npc")``

+#        which means it always fully filled in the parent ``SingleAnnotation`` and only in `SingleAnnotation` or even `HeatmapAnnotation`

+#        can adjust the height of the row annotations.

 # -height The height of the plotting region (the viewport) that the annotation is drawn. If it is a column annotation,

 #        the width must be an absolute unit.

 #

 # == details

-# A normal R function defines how to draw the annotation graphics. As expected, the main part of the AnnotationFunction

-# class is this function. The function defines how to draw at specific positions which correspond to rows or columns

-# in the heatmap. The function should have three arguments: ``index``, ``k`` and ``n`` (the names of the arguments can

-# be arbitory) where ``k`` and ``n`` are optional. ``index`` corresponds to the indices of rows or columns of the heatmap.

-# The value of ``index`` is not necessarily to be the whole row indices or column indices. It can also be a subset of

-# the indices if the annotation is split into slices according to the split of the heatmap. The value in ``index`` is

-# always sorted according to the reordering of heatmap rows or columns (e.g. by clustering). So, ``index`` actually contains

-# a list of row or column indices for the current slice after row or column reordering. This type of design makes sure

-# the annotation graphics are drawn at the correct positions and can be correctly corresponded to the heatmap rows or columns.

+# We use a normal R function defines how to draw the annotation graphics. As

+# expected, the main part of the AnnotationFunction class is this function.

+# The function defines how to draw at specific positions which correspond to

+# rows or columns in the heatmap. The function should have three arguments:

+# ``index``, ``k`` and ``n`` (the names of the arguments can be arbitory)

+# where ``k`` and ``n`` are optional. ``index`` corresponds to the indices of

+# rows or columns of the heatmap. The value of ``index`` is not necessarily to

+# be the whole row indices or column indices of the heatmap. It can be a

+# subset of the indices if the annotation is split into slices according to

+# the split of the heatmap. ``index`` is always reordered according to the

+# reordering of heatmap rows or columns (e.g. by clustering). So, ``index``

+# actually contains a list of row or column indices for the current slice

+# after row or column reordering.

 # 

-# As mentioned, annotation can be split into slices. ``k`` corresponds to the current slice and ``n`` corresponds to

-# the total number of slices. The information of ``k`` and ``n`` sometimes can be useful, for example, we want to add axis

-# in the annotation, and if it is a column annotation and axis is drawn on the very right of the annotation area, the axis

-# is only drawn when ``k == n``.

+# As mentioned, annotation can be split into slices. ``k`` corresponds to the

+# current slice and ``n`` corresponds to the total number of slices. As you can image, 

+# when ``n > 1``, the annotation function will be executed for all ``k``s. The

+# information of ``k`` and ``n`` sometimes can be useful, for example, we want

+# to add axis ot the right side of a column annotation, if this column annotation

+# is split into several slices, the axis is only drawn when``k == n``.

 #

-# Since the function only allows ``index``, ``k`` and ``n``, the function sometimes uses several external variables which can

-# not be defined inside the function, e.g. the data points for the annotation. These variables should be imported

-# into the AnnotationFunction class so that the function can correctly find these variables. 

+# Since the function only allows ``index``, ``k`` and ``n``, the function

+# sometimes uses several external variables which can not be defined inside

+# the function, e.g. the data points for the annotation. These variables

+# should be imported into the AnnotationFunction class so that the function

+# can correctly find these variables (by ``var_import`` argument).

 #

-# One important feature for AnnotationFunction class is it can be subsetable. To allow subsetting of the object,

-# users need to define the rule for the imported variables if there is any. The rules are simple function which

-# accpets the variable and indices, and returns the subset of the variable. The subset rule functions implemented

-# in this package are `subset_gp`, `subset_matrix_by_row` and `subset_vector`. These three functions are enough for

-# most of the cases.

+# One important feature for AnnotationFunction class is it can be subsetable.

+# To allow subsetting of the object, users need to define the rules for the

+# imported variables. The rules are simple function which

+# accpets the variable and indices, and returns the subset of the variable.

+# The subset rule functions implemented in this package are `subset_gp`,

+# `subset_matrix_by_row` and `subset_vector`. These three functions are enough

+# for most of the cases.

 #

 # In following, we defined three AnnotationFunction objects: 

 #

@@ -155,7 +175,7 @@ anno_width_and_height = function(which, width = NULL, height = NULL,

 #		subsetable = TRUE

 #	)

 #

-# 3. The most compact way to only specify the function to the constructor.

+# 3. Only specify the function to the constructor. ``anno3`` is not subsettable.

 #

 #	anno3 = AnnotationFunction(

 #		fun = function(index) {

@@ -167,15 +187,20 @@ anno_width_and_height = function(which, width = NULL, height = NULL,

 #		}

 #	)

 #

-# Finally, you need to push a viewport for graphics and finally pop the viewport.

+# As you can see from the examples, you need to push a viewport for graphics and finally pop the viewport.

 #

-# In the package, quite a lot annotation function are constructed by `AnnotationFunction` constructor:

+# In the package, we have implemted quite a lot annotation function by `AnnotationFunction` constructor:

 # `anno_empty`, `anno_image`, `anno_points`, `anno_lines`, `anno_barplot`, `anno_boxplot`, `anno_histogram`,

-# `anno_density`, `anno_joyplot`, `anno_horizon`, `anno_text` and `anno_mark`. Thess built-in annotation functions

-# are all subsettable.

+# `anno_density`, `anno_joyplot`, `anno_horizon`, `anno_text` and `anno_mark`. These built-in annotation functions

+# support as both row annotations and column annotations and they are are all subsettable.

+#

+# == seealso

+# The build-in annotation functions are already enough for most of the analysis, nevertheless, if users

+# want to know more about how to construct the AnnotationFunction class manually, they can refer to

+# ComplexHeatmap Complete Reference ().

 AnnotationFunction = function(fun, fun_name = "", which = c("column", "row"), 

 	var_import = list(), n = NA, data_scale = c(0, 1), subset_rule = list(), 

-	subsetable = FALSE, show_name = TRUE, width = NULL, height = NULL) {

+	subsetable = length(subset_rule) > 0, show_name = TRUE, width = NULL, height = NULL) {

 	which = match.arg(which)[1]

@@ -263,7 +288,7 @@ AnnotationFunction = function(fun, fun_name = "", which = c("column", "row"),

 # -i A vector of indices.

 #

 # == details

-# One good thing for designing the `AnnotationFunction-class` object is it can be subsetted,

+# One good thing for designing the `AnnotationFunction-class` is it can be subsetted,

 # and this is the base for the splitting of the annotations.

 #

 # == example

@@ -368,17 +393,20 @@ setMethod(f = "draw",

 })

 # == title

-# Copy the AnnotationFunction object

+# Copy the AnnotationFunction Object

 #

 # == param

 # -object The `AnnotationFunction-class` object.

 #

-# == detail

-# In `AnnotationFunction-class`, there is an environment which stores some external variables

-# for the annotation function. This `copy_all,AnnotationFunction-method` hard copy all the variables

-# in that environment to a new environment.

+# == detail 

+# In `AnnotationFunction-class`, there is an environment which

+# stores some external variables for the annotation function (specified by the

+# ``var_import`` argument by constructing the `AnnotationFunction-class`

+# object. This `copy_all,AnnotationFunction-method` hard copies all the

+# variables into a new isolated environment.

 #

 # The environment is at ``object@var_env``.

+#

 setMethod(f = "copy_all",

 	signature = "AnnotationFunction",

 	definition = function(object) {

@@ -392,7 +420,7 @@ setMethod(f = "copy_all",

 })

 # == title

-# Print the AnnotationFunction object

+# Print the AnnotationFunction Object

 #

 # == param

 # -object The `AnnotationFunction-class` object.

@@ -434,10 +462,10 @@ setMethod(f = "show",

 #

 # == param

 # -object The `AnnotationFunction-class` object.

-# -... other arguments

+# -... Other arguments.

 #

-# == details

-# It returns the ``n`` slot in the object. If there does not exist, it returns ``NA``.

+# == details It returns the ``n`` slot in the object. If it does not exist, it

+# returns ``NA``.

 #

 # == example

 # anno = anno_points(1:10)

@@ -19,7 +19,7 @@ AnnotationFunction = setClass("AnnotationFunction",

 		fun_name = "character",

 		width = "ANY",

 		height = "ANY",

-		n = "numeric",

+		n = "ANY",

 		var_env = "environment",

 		fun = "function",

 		subset_rule = "list",

@@ -35,7 +35,7 @@ AnnotationFunction = setClass("AnnotationFunction",

 		subset_rule = list(),

 		subsetable = FALSE,

 		data_scale = c(0, 1),

-		n = 0,

+		n = NA_integer_,

 		extended = unit(c(0, 0, 0, 0), "mm"),

 		show_name = TRUE

 	)

@@ -50,7 +50,7 @@ anno_width_and_height = function(which, width = NULL, height = NULL,

 			height = default

 		} else {

 			if(!is_abs_unit(height)) {

-				stop("height can only be an absolute unit.")

+				stop_wrap("height of the annotation can only be an absolute unit.")

 			} else {

 				height = convertHeight(height, "mm")

 			}

@@ -64,7 +64,7 @@ anno_width_and_height = function(which, width = NULL, height = NULL,

 			width = default

 		} else {

 			if(!is_abs_unit(width)) {

-				stop("width can only be an absolute unit.")

+				stop_wrap("width of the annotation can only be an absolute unit.")

 			} else {

 				width = convertWidth(width, "mm")

 			}

@@ -174,7 +174,7 @@ anno_width_and_height = function(which, width = NULL, height = NULL,

 # `anno_density`, `anno_joyplot`, `anno_horizon`, `anno_text` and `anno_mark`. Thess built-in annotation functions

 # are all subsettable.

 AnnotationFunction = function(fun, fun_name = "", which = c("column", "row"), 

-	var_import = list(), n = 0, data_scale = c(0, 1), subset_rule = list(), 

+	var_import = list(), n = NA, data_scale = c(0, 1), subset_rule = list(), 

 	subsetable = FALSE, show_name = TRUE, width = NULL, height = NULL) {

 	which = match.arg(which)[1]

@@ -213,7 +213,7 @@ AnnotationFunction = function(fun, fun_name = "", which = c("column", "row"),

 				anno@var_env[[nm]] = var_import[[nm]]

 			}

 		} else {

-			stop_wrap("`var_import` needs to be a character vector which contains variable names or a list of variables")

+			stop_wrap("`var_import` needs to be a character vector which contains variable names or a list of variables.")

 		}

 		environment(fun) = anno@var_env

 	} else {

@@ -275,14 +275,14 @@ AnnotationFunction = function(fun, fun_name = "", which = c("column", "row"),

 		return(x)

 	} else {

 		if(!x@subsetable) {

-			stop("This object is not subsetable.")

+			stop_wrap("This object is not subsetable.")

 		}

 		x = copy_all(x)

 		for(var in names(x@subset_rule)) {

 			oe = try(x@var_env[[var]] <- x@subset_rule[[var]](x@var_env[[var]], i), silent = TRUE)

 			if(inherits(oe, "try-error")) {

 				message(paste0("An error when subsetting ", var))

-				stop(oe)

+				stop_wrap(oe)

 			}

 		}

 		if(is.logical(i)) {

@@ -357,7 +357,7 @@ setMethod(f = "draw",

 	}

 	vp_name2 = current.viewport()$name

 	if(vp_name1 != vp_name2) {

-		stop("Viewports are not the same before and after plotting the annotation graphics.")

+		stop_wrap("Viewports should be the same before and after plotting the annotation graphics.")

 	}

 	popViewport()

@@ -443,7 +443,9 @@ setMethod(f = "show",

 # anno = anno_points(1:10)

 # nobs(anno)

 nobs.AnnotationFunction = function(object, ...) {

-	if(object@n > 0) {

+	if(is.na(object@n)) {

+		return(NA)

+	} else if(object@n > 0) {

 		object@n

 	} else {

 		NA

@@ -25,7 +25,8 @@ AnnotationFunction = setClass("AnnotationFunction",

 		subset_rule = "list",

 		subsetable = "logical",

 		data_scale = "numeric",

-		extended = "ANY"

+		extended = "ANY",

+		show_name = "logical"

 	),

 	prototype = list(

 		fun_name = "",

@@ -35,7 +36,8 @@ AnnotationFunction = setClass("AnnotationFunction",

 		subsetable = FALSE,

 		data_scale = c(0, 1),

 		n = 0,

-		extended = unit(c(0, 0, 0, 0), "mm")

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

+		show_name = TRUE

 	)

 )

@@ -173,7 +175,7 @@ anno_width_and_height = function(which, width = NULL, height = NULL,

 # are all subsettable.

 AnnotationFunction = function(fun, fun_name = "", which = c("column", "row"), 

 	var_import = list(), n = 0, data_scale = c(0, 1), subset_rule = list(), 

-	subsetable = FALSE, width = NULL, height = NULL) {

+	subsetable = FALSE, show_name = TRUE, width = NULL, height = NULL) {

 	which = match.arg(which)[1]

@@ -190,6 +192,8 @@ AnnotationFunction = function(fun, fun_name = "", which = c("column", "row"),

 	anno@width = anno_size$width

 	anno@height = anno_size$height

+	anno@show_name = show_name

+

 	anno@n = n

 	anno@data_scale = data_scale

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

 		test2 = TRUE

 	} else {

 		test2 = test

+		test = ""

 	}

 	if(test2) {

         grid.newpage()

@@ -1,10 +1,17 @@

 # == title

-# AnnotationFunction class

+# The AnnotationFunction class

 #

 # == details

-# THe AnnotationFunction class is a wrapper of user-defined annotation functions.

-# See `AnnotationFunction` constructor for details

+# The heatmap annotation is basically graphics aligned to the columns or heatmap if it is column annotation

+# or heatmap rows if it is row annotation, while the type of the graphics can be arbitory, e.g.

+# it can be heatmap-like or points. Here the AnnotationFunction class is designed for creating

+# complex and flexible annotation graphics. As the main part, it uses a use-defined function

+# to define the graphics. It also keeps information of the size of the plotting regions of the annotation.

+# And most importantly, it allows subsetting of the annotation to draw a subset of the graphics, which

+# is the base for the splitting of the annotations.

+#

+# See `AnnotationFunction` constructor for details.

 #

 AnnotationFunction = setClass("AnnotationFunction",

 	slots = list(

@@ -69,16 +76,17 @@ anno_width_and_height = function(which, width = NULL, height = NULL,

 # == title

-# Constructor of AnnotationFunction class

+# Constructor of AnnotationFunction Class

 #

 # == param