@@ -2,7 +2,7 @@ Package: ComplexHeatmap

 Type: Package

 Title: Make Complex Heatmaps

 Version: 1.99.0

-Date: 2018-6-9

+Date: 2018-10-23

 Author: Zuguang Gu

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

 Depends: R (>= 3.1.2), methods, grid, graphics, stats, grDevices

@@ -17,5 +17,5 @@ Description: Complex heatmaps are efficient to visualize associations

     Here the ComplexHeatmap package provides a highly flexible way to arrange 

     multiple heatmaps and supports various annotation graphics.

 biocViews: Software, Visualization, Sequencing

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

+URL: https://github.com/jokergoo/ComplexHeatmap, https://jokergoo.github.io/ComplexHeatmap-reference/book/

 License: MIT + file LICENSE

@@ -18,8 +18,12 @@ S3method("grid.draw", "Legends")

 export("grid.draw.Legends")

 S3method("height", "AnnotationFunction")

 export("height.AnnotationFunction")

+S3method("height", "Heatmap")

+export("height.Heatmap")

 S3method("height", "HeatmapAnnotation")

 export("height.HeatmapAnnotation")

+S3method("height", "HeatmapList")

+export("height.HeatmapList")

 S3method("height", "Legends")

 export("height.Legends")

 S3method("height", "SingleAnnotation")

@@ -72,10 +76,16 @@ S3method("size<-", "SingleAnnotation")

 export("size<-.SingleAnnotation")

 S3method("summary", "Heatmap")

 export("summary.Heatmap")

+S3method("summary", "HeatmapList")

+export("summary.HeatmapList")

 S3method("width", "AnnotationFunction")

 export("width.AnnotationFunction")

+S3method("width", "Heatmap")

+export("width.Heatmap")

 S3method("width", "HeatmapAnnotation")

 export("width.HeatmapAnnotation")

+S3method("width", "HeatmapList")

+export("width.HeatmapList")

 S3method("width", "Legends")

 export("width.Legends")

 S3method("width", "SingleAnnotation")

@@ -125,7 +135,6 @@ export("anno_text")

 export("annotation_axis_grob")

 export("cluster_within_group")

 export("columnAnnotation")

-export("convertXY_in_vp")

 export("decorate_annotation")

 export("decorate_column_dend")

 export("decorate_column_names")

@@ -143,6 +152,7 @@ export("dend_xy")

 export("dendrogramGrob")

 export("densityHeatmap")

 export("dist2")

+export("getXY_in_parent_vp")

 export("grid.boxplot")

 export("grid.dendrogram")

 export("ht_global_opt")

@@ -387,8 +387,8 @@ size.HeatmapAnnotation = function(x, ...) {

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

 #

 # == example

-# lgd = Legend(labels = 1:10, title = "foo", gp = gpar(fill = "red"))

-# width(lgd)

+# lgd = Legend(labels = 1:10, title = "foo", legend_gp = gpar(fill = "red"))

+# ComplexHeatmap:::width(lgd)

 #

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

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

@@ -407,8 +407,8 @@ width.Legends = function(x, ...) {

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

 #

 # == example

-# lgd = Legend(labels = 1:10, title = "foo", gp = gpar(fill = "red"))

-# height(lgd)

+# lgd = Legend(labels = 1:10, title = "foo", legend_gp = gpar(fill = "red"))

+# ComplexHeatmap:::height(lgd)

 #

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

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

@@ -424,7 +424,7 @@ height.Legends = function(x, ...) {

 # -... Other arguments.

 #

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

-    if(object@layout$initialized) {

+    if(x@layout$initialized) {

         x@ht_list_param$width

     } else {

         stop_wrap("width() can only be applied to the heatmap list object returned by draw().")

@@ -440,7 +440,7 @@ width.HeatmapList = function(x, ...) {

 # -... Other arguments.

 #

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

-    if(object@layout$initialized) {

+    if(x@layout$initialized) {

         x@ht_list_param$height

     } else {

         stop_wrap("height() can only be applied to the heatmap list object returned by draw().")

@@ -5,7 +5,7 @@

 # == detail 

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

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

-# method and the `\%v\%v` method so that above three classes can be appended to each other.

+# method and the ``\%v\%v`` method so that above three classes can be appended to each other.

 #

 AdditiveUnit = setClass("AdditiveUnit")

@@ -3,23 +3,20 @@

 # class for single heatmap

 #

-

-# the layout of the heatmap is 7 x 9

-

 # == title

-# Class for a single heatmap

+# Class for a Single Heatmap

 #

 # == details

 # The `Heatmap-class` is not responsible for heatmap legend and annotation legends. The `draw,Heatmap-method` method

-# will construct a `HeatmapList-class` object which only contains one single heatmap

-# and call `draw,HeatmapList-method` to make a complete heatmap.

+# constructs a `HeatmapList-class` object which only contains one single heatmap

+# and call `draw,HeatmapList-method` to make the complete heatmap.

 #

 # == methods

 # The `Heatmap-class` provides following methods:

 #

 # - `Heatmap`: constructor method.

 # - `draw,Heatmap-method`: draw a single heatmap.

-# - `add_heatmap,Heatmap-method` append heatmaps and row annotations to a list of heatmaps.

+# - `add_heatmap,Heatmap-method` append heatmaps and annotations to a list of heatmaps.

 # - `row_order,HeatmapList-method`: get order of rows

 # - `column_order,HeatmapList-method`: get order of columns

 # - `row_dend,HeatmapList-method`: get row dendrograms

@@ -79,115 +76,114 @@ Heatmap = setClass("Heatmap",

 # Constructor method for Heatmap class

 #

 # == param

-# -matrix a matrix. Either numeric or character. If it is a simple vector, it will be

+# -matrix A matrix. Either numeric or character. If it is a simple vector, it will be

 #         converted to a one-column matrix.

-# -col a vector of colors if the color mapping is discrete or a color mapping 

-#      function if the matrix is continuous numbers (should be generated by `circlize::colorRamp2`. If the matrix is continuous,

-#      the value can also be a vector of colors so that colors will be interpolated. Pass to `ColorMapping`.

-# -name name of the heatmap. The name is used as the title of the heatmap legend.

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

-# -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 A vector of colors if the color mapping is discrete or a color mapping 

+#      function if the matrix is continuous numbers (should be generated by `circlize::colorRamp2`). If the matrix is continuous,

+#      the value can also be a vector of colors so that colors can be interpolated. Pass to `ColorMapping`. For more details

+#      and examples, please refer to https://jokergoo.github.io/ComplexHeatmap-reference/book/a-single-heatmap.html#colors .

+# -name Name of the heatmap. By default the heatmap name is used as the title of the heatmap legend.

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

+# -rect_gp Graphic parameters for drawing rectangles (for heatmap body). The value should be specified by `grid::gpar` and ``fill`` parameter is ignored.

+# -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 whether draw border or the color of 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,

+# -border Whether draw border. The value can be logical or a string of color.

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

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

+#           row index in ``matrix``, coordinate of the cell,

 #           the width and height of the cell and the filled color. ``x``, ``y``, ``width`` and ``height`` are all `grid::unit` objects.

-# -layer_fun similar as ``cell_fun``, but is vectorized. 

-# -row_title title on row.

-# -row_title_side will the title be put on the left or right of the heatmap?

-# -row_title_gp graphic parameters for drawing text.

-# -row_title_rot rotation of row titles. Only 0, 90, 270 are allowed to set.

-# -column_title title on column.

-# -column_title_side will the title be put on the top or bottom of the heatmap?

-# -column_title_gp graphic parameters for drawing text.

-# -column_title_rot rotation of column titles. Only 0, 90, 270 are allowed to set.

-# -cluster_rows If the value is a logical, it means whether make cluster on rows. The value can also

-#               be a `stats::hclust` or a `stats::dendrogram` that already contains clustering information.

-#               This means you can use any type of clustering methods and render the `stats::dendrogram`

-#               object with self-defined graphic settings.

-# -clustering_distance_rows it can be a pre-defined character which is in 

+# -layer_fun Similar as ``cell_fun``, but is vectorized. Check https://jokergoo.github.io/ComplexHeatmap-reference/book/a-single-heatmap.html#customize-the-heatmap-body .

+# -row_title Title on the row.

+# -row_title_side Will the title be put on the left or right of the heatmap?

+# -row_title_gp Graphic parameters for row title.

+# -row_title_rot Rotation of row title. Only 0, 90, 270 are allowed to set.

+# -column_title Title on the column.

+# -column_title_side Will the title be put on the top or bottom of the heatmap?

+# -column_title_gp Graphic parameters for column title.

+# -column_title_rot Rotation of column titles. Only 0, 90, 270 are allowed to set.

+# -cluster_rows If the value is a logical, it controls whether to make cluster on rows. The value can also

+#               be a `stats::hclust` or a `stats::dendrogram` which already contains clustering.

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

+# -clustering_distance_rows It can be a pre-defined character which is in 

 #                ("euclidean", "maximum", "manhattan", "canberra", "binary", 

 #                "minkowski", "pearson", "spearman", "kendall"). It can also be a function.

 #                If the function has one argument, the input argument should be a matrix and 

 #                the returned value should be a `stats::dist` object. If the function has two arguments,

 #                the input arguments are two vectors and the function calculates distance between these

 #                two vectors.

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

-# -row_dend_side should the row cluster be put on the left or right of the heatmap?

-# -row_dend_width width of the row cluster, should be a `grid::unit` object.

-# -show_row_dend whether show row clusters. 

-# -row_dend_gp graphics parameters for drawing lines. If users already provide a `stats::dendrogram`

+# -clustering_method_rows Method to perform hierarchical clustering, pass to `stats::hclust`.

+# -row_dend_side Should the row dendrogram be put on the left or right of the heatmap?

+# -row_dend_width Width of the row dendrogram, should be a `grid::unit` object.

+# -show_row_dend Whether show row dendrogram?

+# -row_dend_gp Graphic parameters for the dendrogram segments. If users already provide a `stats::dendrogram`

 #                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

-# -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`.

-# -column_dend_side should the column cluster be put on the top or bottom of the heatmap?

+# -row_dend_reorder Apply reordering on row dendrograms. The value can be a logical value or a vector which contains weight 

+#               which is used to reorder rows. The reordering is applied by `stats::reorder.dendrogram`.

+# -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 perform hierarchical clustering, pass to `stats::hclust`.

+# -column_dend_side Should the column dendrogram be put on the top or bottom of the heatmap?

 # -column_dend_height height of the column cluster, should be a `grid::unit` object.

-# -show_column_dend whether show column clusters.

-# -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

-# -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 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 rotation of row labels

-# -column_labels 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 rotation of column labels

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

-# -bottom_annotation a `HeatmapAnnotation` object.

-# -left_annotation should specified in `rowAnnotation`

-# -right_annotation should shpecified in `rowAnnotation`

-# -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.

-# -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 km

-# -row_split row split

-# -column_km column km

-# -column_split 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

-# -row_gap row gap

-# -column_gap column gap

-# -width width of the heatmap body

-# -height height of the heatmap body

-# -heatmap_width width of the whole heatmap (including heatmap components)

-# -heatmap_height height of the whole heatmap (including heatmap components)

-# -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``

+# -show_column_dend Whether show column dendrogram?

+# -column_dend_gp Graphic parameters for dendrogram segments. Same settings as ``row_dend_gp``.

+# -column_dend_reorder Apply reordering on column dendrograms. Same settings as ``row_dend_reorder``.

+# -row_order Order of rows. Manually setting row order turns off clustering.

+# -column_order Order of column.

+# -row_labels Optional row labels which are put as row names in the heatmap.

+# -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.

+# -row_names_gp Graphic parameters for row names.

+# -row_names_rot Rotation of row names.

+# -column_labels Optional column labels which are put as column names in the heatmap.

+# -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 Rotation of column names.

+# -top_annotation A `HeatmapAnnotation` object.

+# -bottom_annotation A `HeatmapAnnotation` object.

+# -left_annotation It should be specified by `rowAnnotation`.

+# -right_annotation it should be specified by `rowAnnotation`.

+# -km Apply 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 slice, hierarchical clustering is still applied with parameters above.

+# -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 to split the dendrogram by `stats::cutree`.

+# -row_km Same as ``km``.

+# -row_split Same as ``split``.

+# -column_km K-means clustering on columns.

+# -column_split Split on columns. For heatmap splitting, please refer to https://jokergoo.github.io/ComplexHeatmap-reference/book/a-single-heatmap.html#heatmap-split .

+# -gap Gap between row slices if the heatmap is split by rows. The value should be a `grid::unit` object.

+# -row_gap Same as ``gap``.

+# -column_gap Gap between column slices.

+# -width Width of the heatmap body.

+# -height Height of the heatmap body.

+# -heatmap_width Width of the whole heatmap (including heatmap components)

+# -heatmap_height Height of the whole heatmap (including heatmap components). Check https://jokergoo.github.io/ComplexHeatmap-reference/book/a-single-heatmap.html#size-of-the-heatmap .

+# -show_heatmap_legend Whether show heatmap legend?

+# -heatmap_legend_param A list contains parameters for the heatmap legends. 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``

 #       is set, ``use_raster`` is enforced to be ``FALSE``.

-# -raster_device graphic device which is used to generate the raster image

-# -raster_quality a value set to larger than 1 will improve the quality of the raster image.

-# -raster_device_param a list of further parameters for the selected graphic device

-# -post_fun a function which will be executed after the plot is drawn.

+# -raster_device Graphic device which is used to generate the raster image.

+# -raster_quality A value set to larger than 1 will improve the quality of the raster image.

+# -raster_device_param A list of further parameters for the selected graphic device. For raster image support, please check https://jokergoo.github.io/ComplexHeatmap-reference/book/a-single-heatmap.html#heatmap-as-raster-image .

+# -post_fun A function which will be executed after the heatmap list is drawn.

 #

 # == details

-# The initialization function only applies parameter checking and fill values to the slots with proper values.

+# The initialization function only applies parameter checking and fill values to the slots with some validation.

 # 

-# Following methods can be applied on the `Heatmap-class` object:

+# Following methods can be applied to the `Heatmap-class` object:

 #

 # - `show,Heatmap-method`: draw a single heatmap with default parameters

 # - `draw,Heatmap-method`: draw a single heatmap.

-# - ``+`` or `\%v\%` append heatmaps and row annotations to a list of heatmaps.

+# - ``+`` or `\%v\%` append heatmaps and annotations to a list of heatmaps.

 #

 # The constructor function pretends to be a high-level graphic function because the ``show`` method

 # of the `Heatmap-class` object actually plots the graphics.

 #

+# == seealso

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

+#

 # == value

 # A `Heatmap-class` object.

 #

@@ -3,15 +3,15 @@

 # Class for Heatmap Annotations

 #

 # == details

-# A complex heatmap contains a list of annotations which are represented as different graphics

+# A complex heatmap contains a list of annotations which are represented as graphics

 # placed on rows and columns. The `HeatmapAnnotation-class` contains a list of single annotations which are

-# represented as a list of `SingleAnnotation-class` objects with same number of rows or columns.

+# represented as a list of `SingleAnnotation-class` objects.

 #

 # == methods

 # The `HeatmapAnnotation-class` provides following methods:

 #

-# - `HeatmapAnnotation`: constructor method

-# - `draw,HeatmapAnnotation-method`: draw the annotations

+# - `HeatmapAnnotation`: constructor method.

+# - `draw,HeatmapAnnotation-method`: draw the annotations.

 #

 # == author

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

@@ -39,47 +39,53 @@ HeatmapAnnotation = setClass("HeatmapAnnotation",

 )

 # == title

-# Constructor method for HeatmapAnnotation class

+# Constructor Method for HeatmapAnnotation class

 #

 # == param

 # -... Name-value pairs where the names correspond to annotation names and values can be a vector, a matrix and an

 #      annotation function. Each pair is sent to `SingleAnnotation` to contruct a single annotation.

 # -df A data frame. Each column will be treated as a simple annotation. The data frame must have column names.

 # -name Name of the heatmap annotation, optional.

-# -col A list of colors which contain color mapping to columns in ``df`` and simple annotations define din ``...``. 

+# -col A list of colors which contain color mapping to ``df`` or simple annotations defined in ``...``. 

 #      See `SingleAnnotation` for how to set colors.

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

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

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

-# -which Are the annotations row annotations or column annotations?

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

+# -which Are these row annotations or column annotations?

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

 # -border border of single annotations.

-# -gap Gap between each two annotation. It can be a single value or a vector of `grid::unit` objects.

+# -gap Gap between annotations. It can be a single value or a vector of `grid::unit` objects.

 # -show_annotation_name Whether show annotation names? For column annotation, annotation names are drawn either on the left

-#   or the right, and for row annotations, names are draw either on top to at bottom. The value can be a vector.

+#   or the right, and for row annotations, names are draw either on top or at the bottom. The value can be a vector.

 # -annotation_name_gp Graphic parameters for anntation names. Graphic paramters can be vectors.

 # -annotation_name_offset Offset to the annotations, `grid::unit` object. The value can be a vector.

 # -annotation_name_side Side of the annotation names.

-# -annotation_name_rot Rotation of the annotation names, can only take values in ``c(00, 90, 180, 270)``. The value can be a vector.

+# -annotation_name_rot Rotation of the annotation names, it can only take values in ``c(00, 90, 180, 270)``. The value can be a vector.

 # -annotation_height Height of each annotation if annotations are column annotations.

 # -annotation_width Width of each annotation if annotations are row annotations.

-# -height Height of the complete column annotations.

-# -width Width of the complete heatmap annotations.

-# -anno_simple_size size of the simple annotation.

-# -simple_anno_size_adjust whether also adjust the size of simple annotations when adjust the whole heatmap annotation.

+# -height Height of the whole column annotations.

+# -width Width of the whole heatmap annotations.

+# -anno_simple_size Size of the simple annotation.

+# -simple_anno_size_adjust Whether also adjust the size of simple annotations when adjusting the whole heatmap annotation.

 #

 # == details

+# For arguments ``border``, ``annotation_name_offset``, ``annotation_name_side``, ``annotation_name_rot``,

+# ``show_annotation_name``, they can be set as named vectors to modify values for some of the annotations,

+# e.g. assuming you have an annotation with name ``foo``, you can specify ``border = c(foo = TRUE)`` in `HeatmapAnnotation`.

+# 

 # There are three ways to specify heatmap annotations:

 #

-# 1. If the annotation is simply a vector or a matrix, it can be specified as ``HeatmapAnnotation(foo = 1:10)``.

-# 2. If the annotations are already stored as a data frame, it can be specified as ``HeatmapAnnotation(df = df)``.

-# 3. For complex annotation, users can use the pre-defined annotation functions such as `anno_points`: ``HeatmapAnnotation(foo = anno_points(1:10))``.

+# 1. If the annotation is simply a vector or a matrix, it can be specified like ``HeatmapAnnotation(foo = 1:10)``.

+# 2. If the annotations are already stored as a data frame, it can be specified like ``HeatmapAnnotation(df = df)``.

+# 3. For complex annotations, users can use the pre-defined annotation functions such as `anno_points`: ``HeatmapAnnotation(foo = anno_points(1:10))``.

+#

+# For more details and examples, please check https://jokergoo.github.io/ComplexHeatmap-reference/book/heatmap-annotations.html.

 #

 # == value

 # A `HeatmapAnnotation-class` object.

 #

 # == seealso

-# There are two shortcut functions: `rowAnnotation` and `columnAnnotation`.

+# There are two helper functions: `rowAnnotation` and `columnAnnotation`.

 #

 # == author

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

@@ -427,7 +433,7 @@ HeatmapAnnotation = function(...,

 # Construct Row Annotations

 #

 # == param

-# -... Pass to `HeatmapAnnotation`

+# -... Pass to `HeatmapAnnotation`.

 #

 # == details

 # The function is identical to 

@@ -448,7 +454,7 @@ rowAnnotation = function(...) {

 # Construct Column Annotations

 #

 # == param

-# -... Pass to `HeatmapAnnotation`

+# -... Pass to `HeatmapAnnotation`.

 #

 # == details

 # The function is identical to

@@ -721,6 +727,10 @@ setMethod(f = "show",

 # -object The `HeatmapAnnotation-class` object.

 # -... other arguments.

 #

+# == value

+# If there is no ``nobs`` information for any of its `SingleAnnotation-class` object,

+# it returns ``NA``.

+#

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

 	n_anno = length(object@anno_list)

 	len = sapply(seq_len(n_anno), function(i) {

@@ -740,12 +750,12 @@ nobs.HeatmapAnnotation = function(object, ...) {

 }

 # == title

-# Add row annotations or heatmaps as a heatmap list

+# Add Annotations or Heatmaps as a Heatmap List

 #

 # == param

 # -object A `HeatmapAnnotation-class` object.

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

-# -direction Whether it is a horizontal add or a vertical add?

+# -direction Whether it is horizontal list or a vertical list?

 #

 # == details

 # Normally we directly use ``+`` for horizontal concatenation and `\%v\%` for vertical concatenation.

@@ -776,10 +786,10 @@ setMethod(f = "add_heatmap",

 #

 # == param

 # -... `HeatmapAnnotation-class` objects.

-# -gap gap between the annotations.

+# -gap Gap between the groups of annotations.

 #

 # == details

-# The heatmap annotations should be same number of observations.

+# The heatmap annotations should have same number of observations.

 # 

 # == example

 # ha1 = HeatmapAnnotation(foo = 1:10)

@@ -977,14 +987,15 @@ length.HeatmapAnnotation = function(x) {

 # == details

 # The function only adjust height for column annotations and width for row annotations.

 #

-# the basic rule is:

-# 1. if ``annotation_height`` is set, it needs to be a vector and ``height`` is disabled. If all

+# The basic rules are (take ``height`` and ``annotation_height`` for example:

+#

+# 1. If ``annotation_height`` is set and all

 #    ``annotation_height`` are absolute units, ``height`` is ignored.

-# 2. if ``annotation_height`` contains non-absolute units, ``height`` also need to be set and the

-#    non-absolute unit should be set in a simple form such as 1:10 or ``unit(1, "null")``.

+# 2. If ``annotation_height`` contains non-absolute units, ``height`` also need to be set and the

+#    non-absolute units should be set in a simple form such as 1:10 or ``unit(1, "null")``.

 # 3. ``anno_simple_size`` is only used when ``annotation_height`` is NULL.

-# 4. if only ``height`` is set, non-simple annotation is adjusted while keep simple anntation unchanged.

-# 5. if only ``height`` is set and all annotations are simple annotations, all anntations are adjusted.

+# 4. If only ``height`` is set, non-simple annotation is adjusted while keeps simple anntation unchanged.

+# 5. If only ``height`` is set and all annotations are simple annotations, all anntations are adjusted,

 #      and ``anno_simple_size`` is disabled.

 # 6. If ``simple_anno_size_adjust`` is ``FALSE``, the size of the simple annotations will not change.

 #

@@ -245,6 +245,9 @@ setMethod(f = "add_heatmap",

 # then makes the plot by re-calling the graphic functions which are already recorded

 # in the layout.

 #

+# == seealso

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

+#

 # == value

 # This function returns a `HeatmapList-class` object for which the layout has been created.

 #

@@ -569,8 +572,25 @@ setMethod(f = "show",

 # -j column indices

 #

 # == details

-# If the heatmap list is horizontal, ``i`` is the real row indices and ``j`` corresponds to heatmap names and single annotation names.

+# If the heatmap list is horizontal, ``i`` is the row indices and ``j`` corresponds to heatmap names and single annotation names.

+# and if the heatlist is vertical, ``i`` corresponds to heatmap/annotation names and ``j`` is the column indices.

+#

+# == example

+# ht_list = Heatmap(matrix(rnorm(100), 10), name = "rnorm") +

+#   rowAnnotation(foo = 1:10, bar = anno_points(10:1)) + 

+#   Heatmap(matrix(runif(100), 10), name = "runif")

+# summary(ht_list[1:5, ])

+# summary(ht_list[1:5, 1])

+# summary(ht_list[1:5, "rnorm"])

+# summary(ht_list[1:5, c("rnorm", "foo")])

 #

+# ht_list = Heatmap(matrix(rnorm(100), 10), name = "rnorm") \%v\%

+#   columnAnnotation(foo = 1:10, bar = anno_points(10:1)) \%v\%

+#   Heatmap(matrix(runif(100), 10), name = "runif")

+# summary(ht_list[, 1:5])

+# summary(ht_list[1, 1:5])

+# summary(ht_list["rnorm", 1:5])

+# summary(ht_list[c("rnorm", "foo"), 1:5])

 "[.HeatmapList" = function(x, i, j) {

     direction = x@direction

@@ -581,18 +601,19 @@ setMethod(f = "show",

         }

     }

-    if(length(x@ht_list) == 1) {

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

-            if(direction == "horizontal") {

-                return(x@ht_list[[1]][i, j] + NULL)

+    if(direction == "horizontal") {

+        if(nargs() == 2) {

+            subset_heatmap_list_by_row(x, i, direction)

+        } else {

+            if(missing(i)) {

+                subset_heatmap_list_by_column(x, j, direction)

+            } else if(missing(j)) {

+                subset_heatmap_list_by_row(x, i, direction)

             } else {

-                return(x@ht_list[[1]][i, j] %v% NULL)

+                x = subset_heatmap_list_by_row(x, i, direction)

+                subset_heatmap_list_by_column(x, j, direction)

             }

         }

-    }

-

-    if(nargs() == 2) {

-        subset_heatmap_list_by_row(x, i, direction)

     } else {

         if(missing(i)) {

             subset_heatmap_list_by_column(x, j, direction)

@@ -617,24 +638,28 @@ subset_heatmap_list_by_row = function(ht_list, ind, direction) {

             }

         }

     } else {

+        # if it is vertical heatmap list, `ind` corresponds to heatmap names and annotation names

         if(is.numeric(ind)) {

             ht_list@ht_list = ht_list@ht_list[ind]

         } else {

-            ht_list = NULL

+            hl = list()

             # also check annotation names

+            if(!all(ind %in% names(ht_list))) {

+                stop_wrap("Cannot find all name indices in the heatmap list.")

+            }

             for(nm in names(ht_list@ht_list)) {

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

                     if(nm %in% ind) {

-                        ht_list[[nm]] = ht_list@ht_list[[nm]]

+                        hl[[nm]] = ht_list@ht_list[[nm]]

                     }

                 } else {

                     anno_nm = names(ht_list@ht_list[[nm]]@anno_list)

-                    if(anno_nm %in% ind) {

-                        ht_list[[nm]] = ht_list@ht_list[[nm]][, intersect(ind, anno_nm)]

+                    if(any(anno_nm %in% ind)) {

+                        hl[[nm]] = ht_list@ht_list[[nm]][, intersect(ind, anno_nm)]

                     }

                 }

             }

-            ht_list@ht_list = ht_list

+            ht_list@ht_list = hl

         }

     }

     return(ht_list)

@@ -642,24 +667,28 @@ subset_heatmap_list_by_row = function(ht_list, ind, direction) {

 subset_heatmap_list_by_column = function(ht_list, ind, direction) {

     if(direction == "horizontal") {

+        # if it is horizontal heatmap list, `ind` corresponds to heatmap names and annotation names

         if(is.numeric(ind)) {

             ht_list@ht_list = ht_list@ht_list[ind]

         } else {

-            ht_list = NULL

+            hl = list()

             # also check annotation names

+            if(!all(ind %in% names(ht_list))) {

+                stop_wrap("Cannot find all name indices in the heatmap list.")

+            }

             for(nm in names(ht_list@ht_list)) {

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

                     if(nm %in% ind) {

-                        ht_list[[nm]] = ht_list@ht_list[[nm]]

+                        hl[[nm]] = ht_list@ht_list[[nm]]

                     }

                 } else {

                     anno_nm = names(ht_list@ht_list[[nm]]@anno_list)

-                    if(anno_nm %in% ind) {

-                        ht_list[[nm]] = ht_list@ht_list[[nm]][, intersect(ind, anno_nm)]

+                    if(any(anno_nm %in% ind)) {

+                        hl[[nm]] = ht_list@ht_list[[nm]][, intersect(ind, anno_nm)]

                     }

                 }

             }

-            ht_list@ht_list = ht_list

+            ht_list@ht_list = hl

         }

     } else {

         for(i in seq_along(ht_list@ht_list)) {

@@ -700,3 +729,37 @@ names.HeatmapList = function(x) {

 length.HeatmapList = function(x) {

     length(x@ht_list)

 }

+

+

+# == title

+# Summary of a Heatmap List

+#

+# == param

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

+# -... Other arguments.

+#

+summary.HeatmapList = function(object, ...) {

+    n_ht = length(object@ht_list)

+

+    direction = object@direction

+

+    qqcat("A @{direction} heamtap list with @{n_ht} heatmap/annotations.\n")

+

+    ht_name = names(object@ht_list)

+    for(i in seq_len(n_ht)) {

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

+            qqcat("  @{ht_name[i]}: a matrix with @{nrow(object@ht_list[[i]]@matrix)} rows and @{ncol(object@ht_list[[i]]@matrix)} columns\n")

+        } else {

+            qqcat("  @{ht_name[i]}: a list of @{length(object@ht_list[[i]]@anno_list)} annotations\n")

+            for(j in seq_along(object@ht_list[[i]]@anno_list)) {

+                qqcat("    @{object@ht_list[[i]]@anno_list[[j]]@name}:")

+                if(is_simple_annotation(object@ht_list[[i]]@anno_list[[j]])) {

+                    qqcat("   a simple annotation.\n")

+                } else {

+                    qqcat("   a complex annotation.\n")

+                }

+            }

+        }

+    }

+}

+

@@ -3,10 +3,11 @@

 # Adjust Heatmap List

 #

 # == param

-# -object A `HeatmapList-class` object

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

 #

 # == details

-# This function adjust heatmap components for all heatmaps to align them nicely.

+# This function adjusts settings in all other heatmaps according to the main heatmap.

+# It also adjust the size of heatmap annotations to make them aligned nicely.

 #

 # This function is only for internal use.

 #

@@ -461,13 +462,13 @@ setMethod(f = "adjust_heatmap_list",

 })

 # == title

-# Draw the list of heatmaps

+# Draw the List of Heatmaps

 #

 # == param

-# -object a `HeatmapList-class` object

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

 #

 # == details

-# A viewport is created which contains heatmaps.

+# It only draws the list of heatmaps without legends and titles.

 #

 # This function is only for internal use.

 #

@@ -607,11 +608,11 @@ setMethod(f = "draw_heatmap_list",

 })

 # == title

-# Draw heatmap list title

+# Draw Heatmap List Title

 #

 # == param

-# -object a `HeatmapList-class` object

-# -which dendrogram on the row or on the column of the heatmap

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

+# -which Is it a row title or a column title.

 #

 # == details

 # A viewport is created which contains heatmap list title.

@@ -1,9 +1,10 @@

 # == title

-# Get row order from a heatmap list

+# Get Row Order from a Heatmap List

 #

 # == param

-# -object a `HeatmapList-class` object

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

+# -name Name of a specific heatmap.

 #

 # == value

 # The format of the returned object depends on whether rows/columns of the heatmaps are split.

@@ -19,7 +20,7 @@

 # ht_list = Heatmap(mat, row_km = 2) + Heatmap(mat)

 # ht_list = draw(ht_list)

 # row_order(ht_list)

-# ht_list = Heatmap(mat, row_km = 2) %v% Heatmap(mat)

+# ht_list = Heatmap(mat, row_km = 2) \%v\% Heatmap(mat)

 # ht_list = draw(ht_list)

 # row_order(ht_list)

 setMethod(f = "row_order",

@@ -28,6 +29,10 @@ setMethod(f = "row_order",

 	object = make_layout(object)

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

+		return(row_order(object@ht_list[[ name[1] ]]))

+	}

+

 	n = length(object@ht_list)

 	ht_index = which(sapply(seq_along(object@ht_list), function(i) inherits(object@ht_list[[i]], "Heatmap")))

 	if(length(ht_index) == 0) {

@@ -53,10 +58,10 @@ setMethod(f = "row_order",

 })

 # == title

-# Get row order from a heatmap

+# Get Row Order from a Heatmap

 #

 # == param

-# -object a `Heatmap-class` object

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

 #

 # == value

 # The format of the returned object depends on whether rows/columns of the heatmaps are split.

@@ -88,10 +93,11 @@ setMethod(f = "row_order",

 })

 # == title

-# Get column order from a heatmap list

+# Get Column Order from a Heatmap List

 #

 # == param

-# -object a `HeatmapList-class` object

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

+# -name Name of a specific heatmap.

 #

 # == value

 # The format of the returned object depends on whether rows/columns of the heatmaps are split.

@@ -107,18 +113,22 @@ setMethod(f = "row_order",

 # ht_list = Heatmap(mat, column_km = 2) + Heatmap(mat, column_km = 2)

 # ht_list = draw(ht_list)

 # column_order(ht_list)

-# ht_list = Heatmap(mat) %v% Heatmap(mat)

+# ht_list = Heatmap(mat) \%v\% Heatmap(mat)

 # ht_list = draw(ht_list)

 # column_order(ht_list)

-# ht_list = Heatmap(mat, column_km = 2) %v% Heatmap(mat)

+# ht_list = Heatmap(mat, column_km = 2) \%v\% Heatmap(mat)

 # ht_list = draw(ht_list)

 # column_order(ht_list)

 setMethod(f = "column_order",

 	signature = "HeatmapList",

-	definition = function(object) {

+	definition = function(object, name = NULL) {

 	object = make_layout(object)

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

+		return(column_order(object@ht_list[[ name[1] ]]))

+	}

+

 	n = length(object@ht_list)

 	ht_index = which(sapply(seq_along(object@ht_list), function(i) inherits(object@ht_list[[i]], "Heatmap")))

 	if(length(ht_index) == 0) {

@@ -144,10 +154,10 @@ setMethod(f = "column_order",

 })

 # == title

-# Get column order from a heatmap list

+# Get Column Order from a Aeatmap List