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

 Package: ComplexHeatmap

 Type: Package

-Title: Making Complex Heatmaps

+Title: Make Complex Heatmaps

 Version: 1.99.0

 Date: 2018-6-9

 Author: Zuguang Gu

@@ -15,7 +15,7 @@ VignetteBuilder: knitr

 Description: Complex heatmaps are efficient to visualize associations 

     between different sources of data sets and reveal potential structures. 

     Here the ComplexHeatmap package provides a highly flexible way to arrange 

-    multiple heatmaps and supports self-defined annotation graphics.

+    multiple heatmaps and supports various annotation graphics.

 biocViews: Software, Visualization, Sequencing

 URL: https://github.com/jokergoo/ComplexHeatmap

 License: MIT + file LICENSE

@@ -6,6 +6,8 @@ S3method("[", "Heatmap")

 export("[.Heatmap")

 S3method("[", "HeatmapAnnotation")

 export("[.HeatmapAnnotation")

+S3method("[", "HeatmapList")

+export("[.HeatmapList")

 S3method("[", "SingleAnnotation")

 export("[.SingleAnnotation")

 S3method("c", "HeatmapAnnotation")

@@ -38,10 +40,14 @@ S3method("heightDetails", "packed_legends")

 export("heightDetails.packed_legends")

 S3method("length", "HeatmapAnnotation")

 export("length.HeatmapAnnotation")

+S3method("length", "HeatmapList")

+export("length.HeatmapList")

 S3method("merge", "dendrogram")

 export("merge.dendrogram")

 S3method("names", "HeatmapAnnotation")

 export("names.HeatmapAnnotation")

+S3method("names", "HeatmapList")

+export("names.HeatmapList")

 S3method("names<-", "HeatmapAnnotation")

 export("names<-.HeatmapAnnotation")

 S3method("ncol", "Heatmap")

@@ -115,7 +121,9 @@ export("anno_mark")

 export("anno_oncoprint_barplot")

 export("anno_points")

 export("anno_simple")

+export("anno_summary")

 export("anno_text")

+export("annotation_axis_grob")

 export("cluster_within_group")

 export("columnAnnotation")

 export("convertXY_in_vp")

@@ -136,12 +144,14 @@ export("dend_xy")

 export("dendrogramGrob")

 export("densityHeatmap")

 export("dist2")

+export("grid.boxplot")

 export("grid.dendrogram")

 export("height")

 export("height<-")

 export("ht_global_opt")

 export("ht_opt")

 export("is_abs_unit")

+export("list_component")

 export("max_text_height")

 export("max_text_width")

 export("oncoPrint")

@@ -1,31 +1,31 @@

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

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

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

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

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

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

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

-setGeneric('component_height', function(object, ...) standardGeneric('component_height'))

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

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

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

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

-setGeneric('heatmap_legend_size', function(object, ...) standardGeneric('heatmap_legend_size'))

-setGeneric('get_legend_param_list', function(object, ...) standardGeneric('get_legend_param_list'))

-setGeneric('color_mapping_legend', function(object, ...) standardGeneric('color_mapping_legend'))

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

-setGeneric('column_dend', function(object, ...) standardGeneric('column_dend'))

-setGeneric('resize', function(object, ...) standardGeneric('resize'))

-setGeneric('row_order', function(object, ...) standardGeneric('row_order'))

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

-setGeneric('row_dend', function(object, ...) standardGeneric('row_dend'))

-setGeneric('add_heatmap', function(object, ...) standardGeneric('add_heatmap'))

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

-setGeneric('column_order', function(object, ...) standardGeneric('column_order'))

-setGeneric('draw_annotation_legend', function(object, ...) standardGeneric('draw_annotation_legend'))

-setGeneric('draw_heatmap_legend', function(object, ...) standardGeneric('draw_heatmap_legend'))

-setGeneric('annotation_legend_size', function(object, ...) standardGeneric('annotation_legend_size'))

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

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

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

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

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

-setGeneric('draw', function(object, ...) standardGeneric('draw'))

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

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

-setGeneric('make_row_cluster', function(object, ...) standardGeneric('make_row_cluster'))

-setGeneric('component_width', function(object, ...) standardGeneric('component_width'))

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

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

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

-setGeneric('draw_dend', function(object, ...) standardGeneric('draw_dend'))

-setGeneric('adjust_heatmap_list', function(object, ...) standardGeneric('adjust_heatmap_list'))

-setGeneric('copy_all', function(object, ...) standardGeneric('copy_all'))

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

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

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

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

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

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

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

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

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

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

@@ -1,79 +1,79 @@

 # == title

-# Generic method for width

+# Generic Method for width()

 #

 # == param

-# -x x

-# -... other arguments

+# -x An object.

+# -... Other arguments.

 #

 width = function (x, ...) {

 	UseMethod("width", x)

 }

 # == title

-# Generic method for height

+# Generic Method for height()

 #

 # == param

-# -x x

-# -... other arguments

+# -x An object.

+# -... Other arguments.

 #

 height = function (x, ...) {

 	UseMethod("height", x)

 }

 # == title

-# Generic method for size

+# Generic Method for size()

 #

 # == param

-# -x x

-# -... other arguments

+# -x An object.

+# -... Other arguments.

 #

 size = function (x, ...) {

 	UseMethod("size", x)

 }

 # == title

-# Generic assignment method for width

+# Generic Assignment Method for width()

 #

 # == param

-# -x x

-# -value value

-# -... other arguments

+# -x An object.

+# -value The value

+# -... Other arguments.

 #

 "width<-" = function (x, ..., value) {

 	UseMethod("width<-", x)

 }

 # == title

-# Generic assignment method for height

+# Generic Assignment Method for height()

 #

 # == param

-# -x x

-# -value value

-# -... other arguments

+# -x An object.

+# -value The value

+# -... Other arguments.

 #

 "height<-" = function (x, ..., value) {

 	UseMethod("height<-", x)

 }

 # == title

-# Generic assignment method for size

+# Generic Assignment Method for size()

 #

 # == param

-# -x x

-# -value value

-# -... other arguments

+# -x An object.

+# -value The value

+# -... Other arguments.

 #

 "size<-" = function (x, ..., value) {

 	UseMethod("size<-", x)

 }

 # == title

-# Width of the AnnotationFunction x

+# Width of the AnnotationFunction Object

 #

 # == param

-# -x The `AnnotationFunction-class` x.

-# -... other arguments

+# -x A `AnnotationFunction-class` object.

+# -... Other arguments

 #

 # == example

 # anno = anno_points(1:10)

@@ -85,12 +85,12 @@ width.AnnotationFunction = function(x, ...) {

 }

 # == title

-# Assign the Width to the AnnotationFunction x

+# Assign the Width to the AnnotationFunction Object

 #

 # == param

-# -x The `AnnotationFunction-class` x.

-# -value A `grid::unit` x.

-# -... other arguments

+# -x The `AnnotationFunction-class` object.

+# -... Other arguments.

+# -value A `grid::unit` object.

 #

 "width<-.AnnotationFunction" = function(x, ..., value) {

 	x@width = value

@@ -98,11 +98,11 @@ width.AnnotationFunction = function(x, ...) {

 }

 # == title

-# Height of the AnnotationFunction x

+# Height of the AnnotationFunction Object

 #

 # == param

-# -x The `AnnotationFunction-class` x.

-# -... other arguments

+# -x The `AnnotationFunction-class` object.

+# -... Other arguments

 #

 # == example

 # anno = anno_points(1:10)

@@ -114,12 +114,12 @@ height.AnnotationFunction = function(x, ...) {

 }

 # == title

-# Assign the Height to the AnnotationFunction x

+# Assign the Height to the AnnotationFunction Object

 #

 # == param

-# -x The `AnnotationFunction-class` x.

-# -value A `grid::unit` x.

-# -... other arguments

+# -x The `AnnotationFunction-class` object.

+# -value A `grid::unit` object.

+# -... Other arguments.

 #

 "height<-.AnnotationFunction" = function(x, ..., value) {

 	x@height = value

@@ -127,11 +127,11 @@ height.AnnotationFunction = function(x, ...) {

 }

 # == title

-# Size of the AnnotationFunction x

+# Size of the AnnotationFunction Object

 #

 # == param

-# -x The `AnnotationFunction-class` x.

-# -... other arguments

+# -x The `AnnotationFunction-class` object.

+# -... Other arguments.

 #

 # == detail

 # It returns the width if it is a row annotation and the height if it is a column annotation.

@@ -150,15 +150,15 @@ size.AnnotationFunction = function(x, ...) {

 }

 # == title

-# Assign the Size to the AnnotationFunction x

+# Assign the Size to the AnnotationFunction Object

 #

 # == param

-# -x The `AnnotationFunction-class` x.

-# -value A `grid::unit` x.

-# -... other arguments

+# -x The `AnnotationFunction-class` object.

+# -value A `grid::unit` object.

+# -... Other arguments.

 #

 # == detail

-# It assigns the width if it is a row annotation and the height if it is a column annotation.

+# It assigns to the width if it is a row annotation and the height if it is a column annotation.

 #

 # == example

 # anno = anno_points(1:10)

@@ -176,23 +176,23 @@ size.AnnotationFunction = function(x, ...) {

 # == title

-# Width of the SingleAnnotation x

+# Width of the SingleAnnotation Object

 #

 # == param

-# -x The `SingleAnnotation-class` x.

-# -... other arguments

+# -x The `SingleAnnotation-class` object.

+# -... Other arguments.

 #

 width.SingleAnnotation = function(x, ...) {

     x@width

 }

 # == title

-# Assign the Width to the SingleAnnotation x

+# Assign the Width to the SingleAnnotation Object

 #

 # == param

-# -x The `SingleAnnotation-class` x.

-# -value A `grid::unit` x.

-# -... other arguments

+# -x The `SingleAnnotation-class` object.

+# -value A `grid::unit` object.

+# -... Other arguments.

 #

 "width<-.SingleAnnotation" = function(x, ..., value) {

     x@width = value

@@ -203,23 +203,23 @@ width.SingleAnnotation = function(x, ...) {

 }

 # == title

-# Height of the SingleAnnotation x

+# Height of the SingleAnnotation object

 #

 # == param

-# -x The `SingleAnnotation-class` x.

-# -... other arguments

+# -x The `SingleAnnotation-class` object.

+# -... Other arguments.

 #

 height.SingleAnnotation = function(x, ...) {

     x@height

 }

 # == title

-# Assign the Height to the SingleAnnotation x

+# Assign the Height to the SingleAnnotation Object

 #

 # == param

-# -x The `SingleAnnotation-class` x.

-# -value A `grid::unit` x.

-# -... other arguments

+# -x The `SingleAnnotation-class` object.

+# -value A `grid::unit` object.

+# -... Other arguments.

 #

 "height<-.SingleAnnotation" = function(x, ..., value) {

     x@height = value

@@ -230,11 +230,11 @@ height.SingleAnnotation = function(x, ...) {

 }

 # == title

-# Size of the SingleAnnotation x

+# Size of the SingleAnnotation Object

 #

 # == param

-# -x The `SingleAnnotation-class` x.

-# -... other arguments

+# -x The `SingleAnnotation-class` object.

+# -... Other arguments.

 #

 # == detail

 # It returns the width if it is a row annotation and the height if it is a column annotation.

@@ -248,15 +248,15 @@ size.SingleAnnotation = function(x, ...) {

 }

 # == title

-# Assign the Size of the SingleAnnotation x

+# Assign the Size to the SingleAnnotation Object

 #

 # == param

-# -x The `SingleAnnotation-class` x.

-# -value A `grid::unit` x.

-# -... other arguments

+# -x The `SingleAnnotation-class` object.

+# -value A `grid::unit` object.

+# -... Other arguments.

 #

 # == detail

-# It assigns the width if it is a row annotation and the height if it is a column annotation.

+# It assigns to the width if it is a row annotation and the height if it is a column annotation.

 #

 "size<-.SingleAnnotation" = function(x, ..., value) {

     if(x@which == "row") {

@@ -270,23 +270,23 @@ size.SingleAnnotation = function(x, ...) {

 # == title

-# Width of the HeatmapAnnotation x

+# Width of the HeatmapAnnotation Object

 #

 # == param

-# -x The `HeatmapAnnotation-class` x.

-# -... other arguments

+# -x The `HeatmapAnnotation-class` object.

+# -... Other arguments.

 #

 width.HeatmapAnnotation = function(x, ...) {

     x@width

 }

 # == title

-# Assign the Width to the HeatmapAnnotation x

+# Assign the Width to the HeatmapAnnotation Object

 #

 # == param

-# -x The `HeatmapAnnotation-class` x.

-# -value A `grid::unit` x.

-# -... other arguments

+# -x The `HeatmapAnnotation-class` object.

+# -value A `grid::unit` object.

+# -... Other arguments.

 #

 "width<-.HeatmapAnnotation" = function(x, ..., value) {

@@ -303,23 +303,23 @@ width.HeatmapAnnotation = function(x, ...) {

 # == title

-# Height of the HeatmapAnnotation x

+# Height of the HeatmapAnnotation Object

 #

 # == param

-# -x The `HeatmapAnnotation-class` x.

-# -... other arguments

+# -x The `HeatmapAnnotation-class` object.

+# -... Other arguments.

 #

 height.HeatmapAnnotation = function(x, ...) {

     x@height

 }

 # == title

-# Assign the Height to the HeatmapAnnotation x

+# Assign the Height to the HeatmapAnnotation Object

 #

 # == param

-# -x The `HeatmapAnnotation-class` x.

-# -value A `grid::unit` x.

-# -... other arguments

+# -x The `HeatmapAnnotation-class` object.

+# -value A `grid::unit` object.

+# -... Other arguments.

 #

 "height<-.HeatmapAnnotation" = function(x, ..., value) {

@@ -335,11 +335,11 @@ height.HeatmapAnnotation = function(x, ...) {

 }

 # == title

-# Size of the HeatmapAnnotation x

+# Size of the HeatmapAnnotation Object

 #

 # == param

-# -x The `HeatmapAnnotation-class` x.

-# -... other arguments

+# -x The `HeatmapAnnotation-class` object.

+# -... Other arguments.

 #

 # == detail

 # It returns the width if it is a row annotation and the height if it is a column annotation.

@@ -353,12 +353,12 @@ size.HeatmapAnnotation = function(x, ...) {

 }

 # == title

-# Assign the Size to the HeatmapAnnotation x

+# Assign the Size to the HeatmapAnnotation Object

 #

 # == param

-# -x The `HeatmapAnnotation-class` x.

-# -value A `grid::unit` x.

-# -... other arguments

+# -x The `HeatmapAnnotation-class` object.

+# -value A `grid::unit` object.

+# -... Other arguments.

 #

 # == detail

 # It assigns the width if it is a row annotation and the height if it is a column annotation.

@@ -377,11 +377,11 @@ size.HeatmapAnnotation = function(x, ...) {

 # Width of the Legends

 #

 # == param

-# -x The `grid::grob` x returned by `Legend` or `packLegend`.

-# -... other arguments

+# -x The `grid::grob` object returned by `Legend` or `packLegend`.

+# -... Other arguments.

 #

 # == value

-# The returned unit x is in ``mm``.

+# The returned unit x is always in ``mm``.

 #

 width.Legends = function(x, ...) {

 	s = attr(x@grob, "width")

@@ -393,11 +393,11 @@ width.Legends = function(x, ...) {

 # Height of the Legends

 #

 # == param

-# -x The `grid::grob` x returned by `Legend` or `packLegend`.

-# -... other arguments

+# -x The `grid::grob` object returned by `Legend` or `packLegend`.

+# -... Other arguments.

 #

 # == value

-# The returned unit x is in ``mm``.

+# The returned unit x is always in ``mm``.

 #

 height.Legends = function(x, ...) {

 	s = attr(x@grob, "height")

@@ -1,10 +1,11 @@

 # == title

-# An internal class

+# Class for Concatenating Heatmaps and Annotations

 #

-# == detail

-# This class is a super class for `Heatmap-class`, `HeatmapList-class` and `HeatmapAnnotation-class` classes.

-# It is only designed for ``+`` generic method so that above three classes can be appended to each other.

+# == detail 

+# This class is a super class for `Heatmap-class`, `HeatmapList-class` and

+# `HeatmapAnnotation-class` classes. It is only designed for ``+`` generic

+# method so that above three classes can be appended to each other.

 #

 AdditiveUnit = setClass("AdditiveUnit")

@@ -12,7 +13,7 @@ AdditiveUnit = setClass("AdditiveUnit")

 # Constructor Method for AdditiveUnit Class

 #

 # == param

-# -... black hole arguments.

+# -... Black hole arguments.

 #

 # == details

 # This method is not used in the package.

@@ -36,10 +37,16 @@ AdditiveUnit = function(...) {

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

 #

 # == detail

-# It is only a helper function. It actually calls `add_heatmap,Heatmap-method`, `add_heatmap,HeatmapList-method`

-# or `add_heatmap,HeatmapAnnotation-method` depending on the class of the input objects.

+# It is only a helper function. It actually calls

+# `add_heatmap,Heatmap-method`, `add_heatmap,HeatmapList-method` or

+# `add_heatmap,HeatmapAnnotation-method` depending on the class of the input

+# objects.

+#

+# The `HeatmapAnnotation-class` object to be added should only be row

+# annotations. Column annotations should be added to the heatmap list by

+# `\%v\%`.

 #

-# The `HeatmapAnnotation-class` object to be added should only be row annotations.

+# ``x`` and ``y`` can also be ``NULL``.

 #

 # == value

 # A `HeatmapList-class` object.

@@ -83,16 +90,21 @@ AdditiveUnit = function(...) {

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

 #

 # == detail

-# It is only a helper function. It actually calls `add_heatmap,Heatmap-method`, `add_heatmap,HeatmapList-method`

-# or `add_heatmap,HeatmapAnnotation-method` depending on the class of the input objects.

+# It is only a helper function. It actually calls

+# `add_heatmap,Heatmap-method`, `add_heatmap,HeatmapList-method` or

+# `add_heatmap,HeatmapAnnotation-method` depending on the class of the input

+# objects.

+#

+# The `HeatmapAnnotation-class` object to be added should only be column

+# annotations.

 #

-# The `HeatmapAnnotation-class` object to be added should only be column annotations.

+# ``x`` and ``y`` can also be ``NULL``.

 #

 # == value

 # A `HeatmapList-class` object.

 #

 # == seealso

-# `+.AdditiveUnit` operator is used for vertical heatmap list.

+# `+.AdditiveUnit` operator is used for horizontal heatmap list.

 #

 # == author

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

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

@@ -4,9 +4,9 @@

 #

 # == param

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

-# -border Wether draw borders of the annotation region?