@@ -4,6 +4,7 @@ setGeneric('add_heatmap', function(object, ...) standardGeneric('add_heatmap'))

 setGeneric('map_to_colors', function(object, ...) standardGeneric('map_to_colors'))

 setGeneric('set_component_height', function(object, ...) standardGeneric('set_component_height'))

+setGeneric('set_component_width', function(object, ...) standardGeneric('set_component_width'))

 setGeneric('draw_heatmap_body', function(object, ...) standardGeneric('draw_heatmap_body'))

@@ -72,3 +72,27 @@ AdditiveUnit = function(...) {

         add_heatmap(x, y)

     }

 }

+

+

+"%v%" = function(x, y) {

+    if(inherits(x, "HeatmapAnnotation")) {

+        if(x@which != "column") {

+            stop("You should specify `which` to `column` or use `columnAnnotation()` directly if you want to add column annotations vertically.")

+        }

+    }

+    if(inherits(y, "HeatmapAnnotation")) {

+        if(y@which != "column") {

+            stop("You should specify `which` to `column` or use `columnAnnotation()` directly if you want to add column annotations vertically.")

+        }

+    }

+    if(is.null(x)) {

+        ht_list = new("HeatmapList")

+        add_heatmap(ht_list, y, direction = "vertical")

+    } else if(is.null(y)) {

+        ht_list = new("HeatmapList")

+        add_heatmap(ht_list, x, direction = "vertical")

+    } else {

+        add_heatmap(x, y, direction = "vertical")

+    }

+}

+

@@ -89,6 +89,9 @@ anno_width_and_height = function(which, width = NULL, height = NULL,

 #

 # == details

 # The AnnotationFunction class is a wrapper of the function which draws heatmap annotation.

+#

+# If the annotation function is subsetable, the annotation graphics can be split by rows or by columns

+# according to the split of the heatmap.

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

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

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

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

 #

 # == param

 # -x An `AnnotationFunction-class` object.

-# -i Index

+# -i A vector of indices.

 #

 # == details

 # One good thing for designing the `AnnotationFunction-class` can be subsetted.

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

     # names should be passed to the data viewport

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

+	vp_name1 = current.viewport()$name

 	object@fun(index)

 	if(test2) {

 		grid.text(test, y = unit(1, "npc") + unit(2, "mm"), just = "bottom")

@@ -257,6 +261,10 @@ 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.")

+	}

 	popViewport()

 	if(test2) {

@@ -4,7 +4,7 @@

 #

 # == title

-# Class to map values to colors

+# Class for Mapping Values to Colors

 #

 # == details

 # The `ColorMapping-class` handles color mapping with both discrete values and continuous values.

@@ -33,17 +33,17 @@ ColorMapping = setClass("ColorMapping",

 )

 # == title

-# Constructor methods for ColorMapping class

+# Constructor Method for ColorMapping Class

 #

 # == param

-# -name name for this color mapping. The name is automatically generated if it is not specified.

-# -colors discrete colors.

-# -levels levels that correspond to ``colors``. If ``colors`` is name indexed,

+# -name Name for this color mapping. The name is automatically generated if it is not specified.

+# -colors Discrete colors.

+# -levels Levels that correspond to ``colors``. If ``colors`` is name indexed,

 #         ``levels`` can be ignored.

-# -col_fun color mapping function that maps continuous values to colors.

-# -breaks breaks for the continuous color mapping. If ``col_fun`` is

+# -col_fun Color mapping function that maps continuous values to colors.

+# -breaks Breaks for the continuous color mapping. If ``col_fun`` is

 #         generated by `circlize::colorRamp2`, ``breaks`` can be ignored.

-# -na_col colors for ``NA`` values.

+# -na_col Colors for ``NA`` values.

 #

 # == detail

 # ``colors`` and ``levels`` are used for discrete color mapping, ``col_fun`` and

@@ -118,10 +118,10 @@ ColorMapping = function(name, colors = NULL, levels = NULL,

 }

 # == title

-# Print ColorMapping object

+# Print ColorMapping Object

 #

 # == param

-# -object a `ColorMapping-class` object.

+# -object A `ColorMapping-class` object.

 #

 # == value

 # This function returns no value.

@@ -156,11 +156,11 @@ setMethod(f = "show",

 })

 # == title

-# Map values to colors

+# Map Values to Colors

 #

 # == param

-# -object a `ColorMapping-class` object.

-# -x input values.

+# -object A `ColorMapping-class` object.

+# -x Input values.

 #

 # == details

 # It maps a vector of values to a vector of colors.

@@ -204,27 +204,27 @@ setMethod(f = "map_to_colors",

 # == title

-# Draw legend based on color mapping

+# Draw Legend Based on Color Mapping

 #

 # == param

-# -object a `ColorMapping-class` object.

-# -plot whether to plot or just return the size of the legend viewport.

-# -title title of the legend, by default it is the name of the legend

-# -title_gp graphical parameters for legend title

-# -title_position position of the title

-# -color_bar a string of "continous" or "discrete". If the mapping is continuous, whether show the legend as discrete color bar or continuous color bar

-# -grid_height height of each legend grid.

-# -grid_width width of each legend grid.

-# -border color for legend grid borders.

-# -at break values of the legend

-# -labels labels corresponding to break values

-# -labels_gp graphcial parameters for legend labels

-# -nrow if there are too many legend grids, they can be put as an array, this controls number of rows

-# -ncol if there are too many legend grids, they can be put as an array, this controls number of columns

-# -by_row when there are multiple columns for legends, whether to arrange them by rows.

-# -legend_height height of the legend, only works when ``color_bar`` is ``continuous`` and ``direction`` is ``vertical``

-# -legend_width width of the legend, only works when ``color_bar`` is ``continuous`` and ``direction`` is ``horizontal``

-# -legend_direction when ``color_bar`` is ``continuous``, should the legend be vertical or horizontal? When ``color_bar`` is ``discrete``, should the items in the legend proceed vertically or horizontally?

+# -object A `ColorMapping-class` object.

+# -plot Whether to plot or just return legend object?

+# -title Title of the legend, by default it is the name of the legend

+# -title_gp Traphical parameters for legend title

+# -title_position Position of the title

+# -color_bar A string of "continous" or "discrete". If the mapping is continuous, whether show the legend as discrete color bar or continuous color bar

+# -grid_height Height of each legend grid.

+# -grid_width Width of each legend grid.

+# -border Color for legend grid borders.

+# -at Break values of the legend

+# -labels Labels corresponding to break values

+# -labels_gp Graphcial parameters for legend labels

+# -nrow If there are too many legend grids, they can be put as an array, this controls number of rows

+# -ncol If there are too many legend grids, they can be put as an array, this controls number of columns

+# -by_row When there are multiple columns for legends, whether to arrange them by rows.

+# -legend_height Height of the legend, only works when ``color_bar`` is ``continuous`` and ``direction`` is ``vertical``

+# -legend_width Width of the legend, only works when ``color_bar`` is ``continuous`` and ``direction`` is ``horizontal``

+# -legend_direction When ``color_bar`` is ``continuous``, should the legend be vertical or horizontal? When ``color_bar`` is ``discrete``, should the items in the legend proceed vertically or horizontally?

 # -param will be parsed if the parameters are specified as a list

 # -... pass to `grid::viewport`.

 #

@@ -97,6 +97,10 @@ Heatmap = setClass("Heatmap",

         top_annotation_param = "list",

         bottom_annotation = "ANY",

         bottom_annotation_param = "list",

+        left_annotation = "ANY", # NULL or a `HeatmapAnnotation` object

+        left_annotation_param = "list",

+        right_annotation = "ANY",

+        right_annotation_param = "list",

         heatmap_param = "list",

@@ -121,6 +125,7 @@ Heatmap = setClass("Heatmap",

 # -rect_gp graphic parameters for drawing rectangles (for heatmap body).

 # -color_space the color space in which colors are interpolated. Only used if ``matrix`` is numeric and 

 #            ``col`` is a vector of colors. Pass to `circlize::colorRamp2`.

+# -border

 # -cell_fun self-defined function to add graphics on each cell. Seven parameters will be passed into 

 #           this function: ``i``, ``j``, ``x``, ``y``, ``width``, ``height``, ``fill`` which are row index,

 #           column index in ``matrix``, coordinate of the middle points in the heatmap body viewport,

@@ -152,11 +157,7 @@ Heatmap = setClass("Heatmap",

 #                object with edges rendered, this argument will be ignored.

 # -row_dend_reorder apply reordering on rows. The value can be a logical value or a vector which contains weight 

 #               which is used to reorder rows

-# -row_hclust_side deprecated, use ``row_dend_side`` instead

-# -row_hclust_width deprecated, use ``row_dend_width`` instead

-# -show_row_hclust deprecated, use ``show_row_dend`` instead

-# -row_hclust_gp deprecated, use ``row_dend_gp`` instead

-# -row_hclust_reorder deprecated, use ``row_dend_reorder`` instead

+# -row_dend_gp

 # -cluster_columns whether make cluster on columns. Same settings as ``cluster_rows``.

 # -clustering_distance_columns same setting as ``clustering_distance_rows``.

 # -clustering_method_columns method to make cluster, pass to `stats::hclust`.

@@ -166,38 +167,43 @@ Heatmap = setClass("Heatmap",

 # -column_dend_gp graphic parameters for drawling lines. Same settings as ``row_dend_gp``.

 # -column_dend_reorder apply reordering on columns. The value can be a logical value or a vector which contains weight 

 #               which is used to reorder columns

-# -column_hclust_side deprecated, use ``column_dend_side`` instead

-# -column_hclust_height deprecated, use ``column_dend_height`` instead

-# -show_column_hclust deprecated, use ``show_column_dend`` instead

-# -column_hclust_gp deprecated, use ``column_dend_gp`` instead

-# -column_hclust_reorder deprecated, use ``column_dend_reorder`` instead

+# -column_dend_gp

 # -row_order order of rows. It makes it easy to adjust row order for a list of heatmaps if this heatmap 

 #      is selected as the main heatmap. Manually setting row order should turn off clustering

 # -column_order order of column. It makes it easy to adjust column order for both matrix and column annotations.

+# -row_labels

 # -row_names_side should the row names be put on the left or right of the heatmap?

 # -show_row_names whether show row names.

 # -row_names_max_width maximum width of row names viewport. Because some times row names can be very long, it is not reasonable

 #                      to show them all.

 # -row_names_gp graphic parameters for drawing text.

+# -row_names_rot

+# -column_labels

 # -column_names_side should the column names be put on the top or bottom of the heatmap?

 # -column_names_max_height maximum height of column names viewport.

 # -show_column_names whether show column names.

 # -column_names_gp graphic parameters for drawing text.

+# -column_names_rot

 # -top_annotation a `HeatmapAnnotation` object which contains a list of annotations.

-# -top_annotation_height total height of the column annotations on the top.

 # -bottom_annotation a `HeatmapAnnotation` object.

-# -bottom_annotation_height total height of the column annotations on the bottom.

+# -left_annotation

+# -right_annotation

 # -km do k-means clustering on rows. If the value is larger than 1, the heatmap will be split by rows according to the k-means clustering.

 #     For each row-clusters, hierarchical clustering is still applied with parameters above.

-# -km_title row title for each cluster when ``km`` is set. It must a text with format of ".*\%i.*" where "\%i" is replaced by the index of the cluster.

 # -split a vector or a data frame by which the rows are split. But if ``cluster_rows`` is a clustering object, ``split`` can be a single number

 #        indicating rows are to be split according to the split on the tree.

+# -row_km

+# -row_split

+# -column_km

+# -column_split

 # -gap gap between row-slices if the heatmap is split by rows, should be `grid::unit` object. If it is a vector, the order corresponds

 #   to top to bottom in the heatmap

-# -combined_name_fun if the heatmap is split by rows, how to make a combined row title for each slice?

-#                 The input parameter for this function is a vector which contains level names under each column in ``split``.

-# -width the width of the single heatmap, should be a fixed `grid::unit` object. It is used for the layout when the heatmap

-#        is appended to a list of heatmaps.

+# -row_gap

+# -column_gap

+# -width

+# -height

+# -heatmap_body_width

+# -heatmap_body_height

 # -show_heatmap_legend whether show heatmap legend?

 # -heatmap_legend_param a list contains parameters for the heatmap legend. See `color_mapping_legend,ColorMapping-method` for all available parameters.

 # -use_raster whether render the heatmap body as a raster image. It helps to reduce file size when the matrix is huge. Note if ``cell_fun``

@@ -276,6 +282,8 @@ Heatmap = function(matrix, col, name,

     top_annotation = NULL,

     bottom_annotation = NULL,

+    left_annotation = NULL,

+    right_annotation = NULL,

     km = 1, 

     split = NULL, 

@@ -699,6 +707,46 @@ Heatmap = function(matrix, col, name,

         }

     }

+    .Object@left_annotation = left_annotation # a `rowAnnotation` object

+    if(is.null(left_annotation)) {

+        .Object@left_annotation_param$width = unit(0, "mm")

+    } else {

+        .Object@left_annotation_param$width = width(left_annotation) + ROW_ANNO_PADDING*2  # append the gap

+    }

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

+        if(length(left_annotation) > 0) {

+            if(!.Object@left_annotation@which == "row") {

+                stop("`which` in `left_annotation` should only be `row`, or consider using `rowAnnotation()`.")

+            }

+        }

+        nb = nobs(left_annotation)

+        if(!is.na(nb)) {

+            if(nb != ncol(.Object@matrix)) {

+                stop("number of items in left anntotion should be same as number of columns of the matrix.")

+            }

+        }

+    }

+

+    .Object@right_annotation = right_annotation # a `rowAnnotation` object

+    if(is.null(right_annotation)) {

+        .Object@right_annotation_param$width = unit(0, "mm")

+    } else {

+        .Object@right_annotation_param$width = width(right_annotation) + ROW_ANNO_PADDING*2  # append the gap

+    }

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

+        if(length(right_annotation) > 0) {

+            if(!.Object@right_annotation@which == "row") {

+                stop("`which` in `right_annotation` should only be `row`, or consider using `rowAnnotation()`.")

+            }

+        }

+        nb = nobs(right_annotation)

+        if(!is.na(nb)) {

+            if(nb != ncol(.Object@matrix)) {

+                stop("number of items in left anntotion should be same as number of columns of the matrix.")

+            }

+        }

+    }

+

     .Object@layout = list(

         layout_size = list(

             column_title_top_height = unit(0, "mm"),

@@ -715,10 +763,12 @@ Heatmap = function(matrix, col, name,

             row_names_left_width = unit(0, "mm"),

             row_dend_right_width = unit(0, "mm"),

             row_names_right_width = unit(0, "mm"),

-            row_title_right_width = unit(0, "mm")

+            row_title_right_width = unit(0, "mm"),

+            row_anno_left_width = unit(0, "mm"),

+            row_anno_right_width = unit(0, "mm")

         ),

-        layout_index = data.frame(),

+        layout_index = NULL,

         graphic_fun_list = list()

     )

@@ -737,10 +787,10 @@ Heatmap = function(matrix, col, name,

 # == title

-# Make cluster on rows

+# Make Cluster on Rows

 #

 # == param

-# -object a `Heatmap-class` object.

+# -object A `Heatmap-class` object.

 #

 # == details

 # The function will fill or adjust ``row_dend_list``, ``row_order_list``, ``row_title`` and ``matrix_param`` slots.

@@ -1185,16 +1235,16 @@ make_cluster = function(object, which = c("row", "column")) {

 }

 # == title

-# Make the layout of a single heatmap

+# Make the Layout of a Single Heatmap

 #

 # == param

-# -object a `Heatmap-class` object.

+# -object A `Heatmap-class` object.

 # 

 # == detail

 # The layout of the single heatmap will be established by setting the size of each heatmap components.

-# Also functions that make graphics for heatmap components will be recorded.

+# Also functions that make graphics for heatmap components will be recorded by saving as functions.

 #

-# Whether apply row clustering or column clustering affects the layout, so clustering should be applied 

+# Whether to apply row clustering or column clustering affects the layout, so clustering should be applied 

 # first before making the layout.

 #

 # This function is only for internal use.

@@ -1254,7 +1304,7 @@ setMethod(f = "make_layout",

         ###########################################

         ## heatmap body

-        object@layout$layout_index = rbind(c(5, 4))

+        object@layout$layout_index = rbind(heatmapb_body = heatmap_layout_index("heatmap_body"))

         object@layout$graphic_fun_list = list(function(object) {

             for(i in seq_len(nr_slice)) {

                 for(j in seq_len(nc_slice)) {

@@ -1277,14 +1327,14 @@ setMethod(f = "make_layout",

             } else {

                 object@layout$layout_size$column_title_top_height = grobWidth(textGrob(column_title, gp = column_title_gp)) + TITLE_PADDING*2

             }

-            object@layout$layout_index = rbind(object@layout$layout_index, c(1, 4))

+            object@layout$layout_index = rbind(object@layout$layout_index, column_title_top = heatmap_layout_index("column_title_top"))

         } else {

             if(column_title_rot %in% c(0, 180)) {

                 object@layout$layout_size$column_title_bottom_height = grobHeight(textGrob(column_title, gp = column_title_gp)) + TITLE_PADDING*2

             } else {

                 object@layout$layout_size$column_title_bottom_height = grobWidth(textGrob(column_title, gp = column_title_gp)) + TITLE_PADDING*2

             }

-            object@layout$layout_index = rbind(object@layout$layout_index, c(9, 4))

+            object@layout$layout_index = rbind(object@layout$layout_index, column_title_bottom = heatmap_layout_index("column_title_bottom"))

         }

         object@layout$graphic_fun_list = c(object@layout$graphic_fun_list, function(object) {

             if(length(column_title) == 1 && nc_slice > 1) {

@@ -1310,14 +1360,14 @@ setMethod(f = "make_layout",

             } else {

                 object@layout$layout_size$row_title_left_width = max_text_height(row_title, gp = row_title_gp) + TITLE_PADDING*2

             }

-            object@layout$layout_index = rbind(object@layout$layout_index, c(5, 1))

+            object@layout$layout_index = rbind(object@layout$layout_index, row_title_left = heatmap_layout_index("row_title_left"))

         } else {

             if(row_title_rot %in% c(0, 180)) {

                 object@layout$layout_size$row_title_right_width = max_text_width(row_title, gp = row_title_gp) + TITLE_PADDING*2

             } else {

                 object@layout$layout_size$row_title_right_width = max_text_height(row_title, gp = row_title_gp) + TITLE_PADDING*2

             }

-            object@layout$layout_index = rbind(object@layout$layout_index, c(5, 7))

+            object@layout$layout_index = rbind(object@layout$layout_index, row_title_right = heatmap_layout_index("row_title_right"))

         }

         object@layout$graphic_fun_list = c(object@layout$graphic_fun_list, function(object) {

             if(length(row_title) == 1 && nr_slice > 1) {

@@ -1339,10 +1389,10 @@ setMethod(f = "make_layout",

     if(show_row_dend) {

         if(row_dend_side == "left") {

             object@layout$layout_size$row_dend_left_width = row_dend_width

-            object@layout$layout_index = rbind(object@layout$layout_index, c(5, 2))

+            object@layout$layout_index = rbind(object@layout$layout_index, row_dend_left = heatmap_layout_index("row_dend_left"))

         } else {

             object@layout$layout_size$row_dend_right_width = row_dend_width

-            object@layout$layout_index = rbind(object@layout$layout_index, c(5, 6))

+            object@layout$layout_index = rbind(object@layout$layout_index, row_dend_right = heatmap_layout_index("row_dend_right"))

         }

         row_dend_max_height = dend_heights(row_dend_slice) + max(dend_heights(object@row_dend_list))

         object@layout$graphic_fun_list = c(object@layout$graphic_fun_list, function(object) {

@@ -1380,10 +1430,10 @@ setMethod(f = "make_layout",

     if(show_column_dend) {

         if(column_dend_side == "top") {

             object@layout$layout_size$column_dend_top_height = column_dend_height

-            object@layout$layout_index = rbind(object@layout$layout_index, c(2, 4))

+            object@layout$layout_index = rbind(object@layout$layout_index, column_dend_top = heatmap_layout_index("column_dend_top"))

         } else {

             object@layout$layout_size$column_dend_bottom_height = column_dend_height

-            object@layout$layout_index = rbind(object@layout$layout_index, c(8, 4))

+            object@layout$layout_index = rbind(object@layout$layout_index, column_dend_bottom = heatmap_layout_index("column_dend_bottom"))

         }

         column_dend_max_height = dend_heights(column_dend_slice) + max(dend_heights(object@column_dend_list))

         object@layout$graphic_fun_list = c(object@layout$graphic_fun_list, function(object) {

@@ -1422,10 +1472,10 @@ setMethod(f = "make_layout",

         row_names_width = min(row_names_width, object@row_names_param$max_width)

         if(row_names_side == "left") {

             object@layout$layout_size$row_names_left_width = row_names_width

-            object@layout$layout_index = rbind(object@layout$layout_index, c(5, 3))

+            object@layout$layout_index = rbind(object@layout$layout_index, row_names_left = heatmap_layout_index("row_names_left"))

         } else {

             object@layout$layout_size$row_names_right_width = row_names_width

-            object@layout$layout_index = rbind(object@layout$layout_index, c(5, 5))

+            object@layout$layout_index = rbind(object@layout$layout_index, row_names_right = heatmap_layout_index("row_names_right"))

         }

         object@layout$graphic_fun_list = c(object@layout$graphic_fun_list, function(object) {

             for(i in seq_len(nr_slice)) {

@@ -1445,10 +1495,10 @@ setMethod(f = "make_layout",

         column_names_height = min(column_names_height, object@column_names_param$max_height)

         if(column_names_side == "top") {

             object@layout$layout_size$column_names_top_height = column_names_height

-            object@layout$layout_index = rbind(object@layout$layout_index, c(3, 4))

+            object@layout$layout_index = rbind(object@layout$layout_index, column_names_top = heatmap_layout_index("column_names_top"))

         } else {

             object@layout$layout_size$column_names_bottom_height = column_names_height

-            object@layout$layout_index = rbind(object@layout$layout_index, c(7, 4))

+            object@layout$layout_index = rbind(object@layout$layout_index, column_names_bottom = heatmap_layout_index("column_names_bottom"))

         }

         object@layout$graphic_fun_list = c(object@layout$graphic_fun_list, function(object) {

             for(i in seq_len(nc_slice)) {

@@ -1465,7 +1515,7 @@ setMethod(f = "make_layout",

     if(!is.null(annotation)) {

         if(length(annotation@anno_list) > 0) {

             object@layout$layout_size$column_anno_top_height = annotation_height

-            object@layout$layout_index = rbind(object@layout$layout_index, c(4, 4))

+            object@layout$layout_index = rbind(object@layout$layout_index, column_anno_top = heatmap_layout_index("column_anno_top"))

             object@layout$graphic_fun_list = c(object@layout$graphic_fun_list, function(object) {

                 for(i in seq_len(nc_slice)) {

@@ -1483,7 +1533,7 @@ setMethod(f = "make_layout",

     if(!is.null(annotation)) {

         if(length(annotation@anno_list) > 0) {

             object@layout$layout_size$column_anno_bottom_height = annotation_height

-            object@layout$layout_index = rbind(object@layout$layout_index, c(6, 4))

+            object@layout$layout_index = rbind(object@layout$layout_index, column_anno_bottom = heatmap_layout_index("column_anno_bottom"))

             object@layout$graphic_fun_list = c(object@layout$graphic_fun_list, function(object) {

                 for(i in seq_len(nc_slice)) {

                     draw_annotation(object, k = i, which = "bottom", x = slice_x[i], 

@@ -1493,14 +1543,51 @@ setMethod(f = "make_layout",

         }

     }

+    ##########################################

+    ## annotation on left

+    annotation = object@left_annotation

+    annotation_width = object@left_annotation_param$width

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

+        if(length(annotation@anno_list) > 0) {

+            object@layout$layout_size$row_anno_left_width = annotation_width

+            object@layout$layout_index = rbind(object@layout$layout_index, row_anno_left = heatmap_layout_index("row_anno_left"))

+            object@layout$graphic_fun_list = c(object@layout$graphic_fun_list, function(object) {

+                    for(i in seq_len(nr_slice)) {

+                        draw_annotation(object, k = i, which = "left",  y = slice_y[i], 

+                            height = slice_height[i], width = unit(1, "npc"), just = "top") 

+                    }

+                }

+            )

+        }

+    }

+

+    ##########################################

+    ## annotation on right

+    annotation = object@right_annotation

+    annotation_width = object@right_annotation_param$width

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

+        if(length(annotation@anno_list) > 0) {

+            object@layout$layout_size$row_anno_right_width = annotation_width

+            object@layout$layout_index = rbind(object@layout$layout_index, row_anno_right = heatmap_layout_index("row_anno_right"))

+            object@layout$graphic_fun_list = c(object@layout$graphic_fun_list, function(object) {

+                for(i in seq_len(nr_slice)) {

+                    draw_annotation(object, k = i, which = "right", y = slice_y[i], 

+                        height = slice_height[i], width = unit(1, "npc"), just = "top")

+                }

+            })

+        }

+    }

+

     layout_size = object@layout$layout_size

     if(is_abs_unit(object@heatmap_param$width)) {

         # recalcualte the width of heatmap body

         object@matrix_param$width = object@heatmap_param$width -

             sum(layout_size$row_title_left_width,

                 layout_size$row_dend_left_width,

+                layout_size$row_anno_left_width,

                 layout_size$row_names_left_width,

                 layout_size$row_dend_right_width,

+                layout_size$row_anno_right_width,

                 layout_size$row_names_right_width,

                 layout_size$row_title_right_width)   

     } else if(is_abs_unit(object@matrix_param$width)) {  # e.g. unit(1, "npc")

@@ -1510,7 +1597,9 @@ setMethod(f = "make_layout",

             layout_size$row_names_left_width,

             layout_size$row_dend_right_width,

             layout_size$row_names_right_width,

-            layout_size$row_title_right_width

+            layout_size$row_title_right_width,

+            layout_size$row_anno_left_width,

+            layout_size$row_anno_right_width

         ) + object@matrix_param$width

         if(nr_slice > 1) {

             object@heatmap_param$width = object@heatmap_param$width + sum(row_gap[seq_len(nr_slice-1)])

@@ -1557,17 +1646,17 @@ setMethod(f = "make_layout",

 })

 # == title

-# Draw the single heatmap with default parameters

+# Draw the Single Heatmap with Defaults

 #

 # == param

-# -object a `Heatmap-class` object.

+# -object A `Heatmap-class` object.

 #

 # == details

-# Actually it calls `draw,Heatmap-method`, but only with default parameters. If users want to customize the heatmap,

+# It actually calls `draw,Heatmap-method`, but only with default parameters. If users want to customize the heatmap,

 # they can pass parameters directly to `draw,Heatmap-method`.

 #

 # == value

-# This function returns no value.

+# The `HeatmapList-class` object.

 #

 # == author

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

@@ -1576,18 +1665,16 @@ setMethod(f = "show",

     signature = "Heatmap",

     definition = function(object) {

-    # cat("A Heatmap object:\n")

-    # cat("name:", object@name, "\n")

-    # cat("dim:", nrow(object@matrix), "x", ncol(object@matrix), "\n")

     draw(object)

 })

 # == title

-# Add heatmaps or row annotations as a heatmap list

+# Add Heatmap to the Heatmap List

 #

 # == param

-# -object a `Heatmap-class` object.

+# -object A `Heatmap-class` object.

 # -x a `Heatmap-class` object, a `HeatmapAnnotation-class` object or a `HeatmapList-class` object.

+# -direction Whether the heatmap is added horizontal or vertically?

 #

 # == details

 # There is a shortcut function ``+.AdditiveUnit``.

@@ -1600,11 +1687,15 @@ setMethod(f = "show",

 #

 setMethod(f = "add_heatmap",

     signature = "Heatmap",

-    definition = function(object, x) {

+    definition = function(object, x, direction = c("horizontal", "vertical")) {

+

+    direction = match.arg(direction)[1]

     ht_list = new("HeatmapList")

-    ht_list = add_heatmap(ht_list, object)

-    ht_list = add_heatmap(ht_list, x)

+    ht_list@direction = direction

+    

+    ht_list = add_heatmap(ht_list, object, direction = direction)

+    ht_list = add_heatmap(ht_list, x, direction = direction)

     return(ht_list)

 })

@@ -1613,16 +1704,13 @@ setMethod(f = "add_heatmap",

 # Draw the heatmap body

 #

 # == param

-# -object a `Heatmap-class` object.

-# -k a matrix may be split by rows, the value identifies which row-slice.

-# -... pass to `grid::viewport`, basically for defining the position of the viewport.

+# -object A `Heatmap-class` object.

+# -kr Row slice index.

+# -kc Column slice index.

+# -... Pass to `grid::viewport` which includes the subset of heatmap body.

 #

 # == details

-# The matrix can be split into several parts by rows if ``km`` or ``split`` is 

-# specified when initializing the `Heatmap` object. If the matrix is split, 

-# there will be gaps between rows to identify different row-slice.

-#

-# A viewport is created which contains subset rows of the heatmap.

+# A viewport is created which contains subset rows and columns of the heatmap.

 #

 # This function is only for internal use.

 #

@@ -1784,19 +1872,15 @@ R_binary = function() {

 }

 # == title

-# Draw dendrogram on row or column

+# Draw Heatmap Dendrograms

 #

 # == param

-# -object a `Heatmap-class` object.

-# -which is dendrogram put on the row or on the column of the heatmap?

-# -k a matrix may be splitted by rows, the value identifies which row-slice.

-# -max_height maximum height of the dendrograms.

-# -... pass to `grid::viewport`, basically for defining the position of the viewport.

+# -object A `Heatmap-class` object.

+# -which Are the dendrograms put on the row or on the column of the heatmap?

+# -k Slice index.

+# -... Pass to `grid::viewport` which includes the complete heatmap dendrograms.

 #

 # == details

-# If the matrix is split into several row slices, a list of dendrograms will be drawn by 

-# the heatmap that each dendrogram corresponds to its row slices.

-#

 # A viewport is created which contains dendrograms.

 #

 # This function is only for internal use.

@@ -1813,7 +1897,7 @@ R_binary = function() {

 setMethod(f = "draw_dend",

     signature = "Heatmap",

     definition = function(object,

-    which = c("row", "column"), k = 1, max_height, ...) {

+    which = c("row", "column"), k = 1, ...) {

     which = match.arg(which)[1]

@@ -1839,7 +1923,7 @@ setMethod(f = "draw_dend",

         return(invisible(NULL))

     }

-    if(missing(max_height)) max_height = dend_heights(dend)

+    max_height = dend_heights(dend)

     dend_padding = unit(1, "mm")

     if(side %in% c("left", "right")) {

@@ -1878,11 +1962,10 @@ setMethod(f = "draw_dend",

 # Draw row names or column names

 #

 # == param

-# -object a `Heatmap-class` object.

-# -which are names put on the row or on the column of the heatmap?

-# -k a matrix may be split by rows, the value identifies which row-slice.

-# -dimname_padding padding for the row/column names

-# -... pass to `grid::viewport`, basically for defining the position of the viewport.

+# -object A `Heatmap-class` object.

+# -which Are the names put on the row or on the column of the heatmap?

+# -k Slice index.

+# -... Pass to `grid::viewport` which includes the complete heatmap row/column names.

 #

 # == details

 # A viewport is created which contains row names or column names.

@@ -1916,13 +1999,13 @@ setMethod(f = "draw_dimnames",

 })

 # == title

-# Draw heatmap title

+# Draw Heatmap Title

 #

 # == param

-# -object a `Heatmap-class` object.

-# -which is title put on the row or on the column of the heatmap?

-# -k a matrix may be split by rows, the value identifies which row-slice.

-# -... pass to `grid::viewport`, basically for defining the position of the viewport.

+# -object A `Heatmap-class` object.

+# -which Is title put on the row or on the column of the heatmap?

+# -k Slice index.

+# -... Pass to `grid::viewport` which includes the complete heatmap title

 #

 # == details

 # A viewport is created which contains heatmap title.

@@ -1991,17 +2074,18 @@ setMethod(f = "draw_title",

 })

 # == title

-# Draw column annotations

+# Draw Heatmap Annotations on the Heatmap

 #

 # == param

-# -object a `Heatmap-class` object.

-# -which are the annotations put on the top or bottom of the heatmap?

+# -object A `Heatmap-class` object.

+# -which The position of the heamtap annotation.

+# -k Slice index.

+# -... Pass to `grid::viewport` which includes the complete heatmap annotation.

 #

 # == details

-# A viewport is created which contains column annotations.

+# A viewport is created which contains column/top annotations.

 #

-# Since the column annotations is a `HeatmapAnnotation-class` object, the function

-# calls `draw,HeatmapAnnotation-method` to draw the annotations.

+# The function calls `draw,HeatmapAnnotation-method` to draw the annotations.

 #

 # This function is only for internal use.

 #

@@ -2013,21 +2097,28 @@ setMethod(f = "draw_title",

 #

 setMethod(f = "draw_annotation",

     signature = "Heatmap",

-    definition = function(object, which = c("top", "bottom"), k = 1, ...) {

+    definition = function(object, which = c("top", "bottom", "left", "right"), k = 1, ...) {

     which = match.arg(which)[1]

     annotation = switch(which,

         top = object@top_annotation,

-        bottom = object@bottom_annotation)

+        bottom = object@bottom_annotation,

+        left = object@left_annotation,

+        right = object@right_annotation)

     # if there is no annotation, draw nothing

     if(is.null(annotation)) {

         return(invisible(NULL))

     }

-    index = object@column_order_list[[k]]

-    n = length(object@column_order_list)

+    if(which %in% c("top", "bottom")) {

+        index = object@column_order_list[[k]]

+        n = length(object@column_order_list)

+    } else {

+        index = object@row_order_list[[k]]

+        n = length(object@row_order_list)

+    }

     pushViewport(viewport(...))

     draw(annotation, index = index, k = k, n = n)

@@ -2035,13 +2126,16 @@ setMethod(f = "draw_annotation",

 })

 # == title

-# Width of each heatmap component

+# Widths of Heatmap Components

 #

 # == param

-# -object a `Heatmap-class` object.

-# -k which component in the heatmap, see `Heatmap-class`.

+# -object A `Heatmap-class` object.

+# -k Which components in the heatmap. The value should numeric indices or the names

+#    of the corresponding row component. See **Detials**.

 #

 # == details

+# All row components are: ``row_title_left``, ``row_dend_left``, ``row_names_left``, ``row_anno_left``,

+# ``heatmap_body``, ``row_anno_right``, ``row_names_right``, ``row_dend_right``, ``row_title_right``.

 #

 # This function is only for internal use.

 #

@@ -2053,40 +2147,37 @@ setMethod(f = "draw_annotation",

 #

 setMethod(f = "component_width",

     signature = "Heatmap",

-    definition = function(object, k = 1:7) {

+    definition = function(object, k = HEATMAP_LAYOUT_ROW_COMPONENT) {

+    if(is.numeric(k)) {

+        component_name = names(HEATMAP_LAYOUT_ROW_COMPONENT)[k]

+    } else {

+        component_name = k

+    }

     # this function is used for grid.layout, so null unit is allowed

-    .single_unit = function(k) {

-        if(k == 1) {

-            object@layout$layout_size$row_title_left_width

-        } else if(k == 2) {

-            object@layout$layout_size$row_dend_left_width

-        } else if(k == 3) {

-            object@layout$layout_size$row_names_left_width

-        } else if(k == 4) {

+    .single_unit = function(nm) {

+        if(nm == "heatmap_body") {

             object@matrix_param$width

-        } else if(k == 5) {

-            object@layout$layout_size$row_names_right_width

-        } else if(k == 6) {

-            object@layout$layout_size$row_dend_right_width

-        } else if(k == 7) {

-            object@layout$layout_size$row_title_right_width

         } else {

-            stop("wrong 'k'")

+            object@layout$layout_size[[paste0(nm, "_width")]]

         }

     }

-

-    do.call("unit.c", lapply(k, function(i) .single_unit(i)))

+    

+    do.call("unit.c", lapply(component_name, .single_unit))

 })

 # == title

-# Height of each heatmap component

+# Heights of Heatmap Components

 #

 # == param

-# -object a `Heatmap-class` object.

-# -k which component in the heatmap, see `Heatmap-class`.

+# -object A `Heatmap-class` object.

+# -k Which components in the heatmap. The value should numeric indices or the names

+#    of the corresponding column component. See **Detials**.

 #

 # == detail

+# All column components are: ``column_title_top``, ``column_dend_top``, ``column_names_top``, 

+# ``column_anno_top``, ``heatmap_body``, ``column_anno_bottom``, ``column_names_bottom``, 

+# ``column_dend_bottom``, ``column_title_bottom``.

 #

 # This function is only for internal use.

 #

@@ -2098,62 +2189,109 @@ setMethod(f = "component_width",

 #

 setMethod(f = "component_height",

     signature = "Heatmap",

-    definition = function(object, k = 1:9) {

+    definition = function(object, k = HEATMAP_LAYOUT_COLUMN_COMPONENT) {

+    if(is.numeric(k)) {

+        component_name = names(HEATMAP_LAYOUT_COLUMN_COMPONENT)[k]

+    } else {

+        component_name = k

+    }

     # this function is used for grid.layout, so null unit is allowed

-    .single_unit = function(k) {

-        if(k == 1) {

-            object@layout$layout_size$column_title_top_height

-        } else if(k == 2) {

-            object@layout$layout_size$column_dend_top_height

-        } else if(k == 4) {

-            object@layout$layout_size$column_anno_top_height

-        } else if(k == 3) {

-            object@layout$layout_size$column_names_top_height

-        } else if(k == 5) {

+    .single_unit = function(nm) {

+        if(nm == "heatmap_body") {

             object@matrix_param$height

-        } else if(k == 7) {

-            object@layout$layout_size$column_names_bottom_height

-        } else if(k == 6) {

-            object@layout$layout_size$column_anno_bottom_height

-        } else if(k == 8) {

-            object@layout$layout_size$column_dend_bottom_height

-        } else if(k == 9) {

-            object@layout$layout_size$column_title_bottom_height

         } else {

-            stop("wrong 'k'")

+            object@layout$layout_size[[paste0(nm, "_height")]]

         }

     }

-    do.call("unit.c", lapply(k, function(i) .single_unit(i)))