Browse code

documentation checked

Zuguang Gu authored on 23/10/2018 19:59:12
Showing158 changed files

... ...
@@ -2,7 +2,7 @@ Package: ComplexHeatmap
2 2
 Type: Package
3 3
 Title: Make Complex Heatmaps
4 4
 Version: 1.99.0
5
-Date: 2018-6-9
5
+Date: 2018-10-23
6 6
 Author: Zuguang Gu
7 7
 Maintainer: Zuguang Gu <z.gu@dkfz.de>
8 8
 Depends: R (>= 3.1.2), methods, grid, graphics, stats, grDevices
... ...
@@ -17,5 +17,5 @@ Description: Complex heatmaps are efficient to visualize associations
17 17
     Here the ComplexHeatmap package provides a highly flexible way to arrange 
18 18
     multiple heatmaps and supports various annotation graphics.
19 19
 biocViews: Software, Visualization, Sequencing
20
-URL: https://github.com/jokergoo/ComplexHeatmap
20
+URL: https://github.com/jokergoo/ComplexHeatmap, https://jokergoo.github.io/ComplexHeatmap-reference/book/
21 21
 License: MIT + file LICENSE
... ...
@@ -18,8 +18,12 @@ S3method("grid.draw", "Legends")
18 18
 export("grid.draw.Legends")
19 19
 S3method("height", "AnnotationFunction")
20 20
 export("height.AnnotationFunction")
21
+S3method("height", "Heatmap")
22
+export("height.Heatmap")
21 23
 S3method("height", "HeatmapAnnotation")
22 24
 export("height.HeatmapAnnotation")
25
+S3method("height", "HeatmapList")
26
+export("height.HeatmapList")
23 27
 S3method("height", "Legends")
24 28
 export("height.Legends")
25 29
 S3method("height", "SingleAnnotation")
... ...
@@ -72,10 +76,16 @@ S3method("size<-", "SingleAnnotation")
72 76
 export("size<-.SingleAnnotation")
73 77
 S3method("summary", "Heatmap")
74 78
 export("summary.Heatmap")
79
+S3method("summary", "HeatmapList")
80
+export("summary.HeatmapList")
75 81
 S3method("width", "AnnotationFunction")
76 82
 export("width.AnnotationFunction")
83
+S3method("width", "Heatmap")
84
+export("width.Heatmap")
77 85
 S3method("width", "HeatmapAnnotation")
78 86
 export("width.HeatmapAnnotation")
87
+S3method("width", "HeatmapList")
88
+export("width.HeatmapList")
79 89
 S3method("width", "Legends")
80 90
 export("width.Legends")
81 91
 S3method("width", "SingleAnnotation")
... ...
@@ -125,7 +135,6 @@ export("anno_text")
125 135
 export("annotation_axis_grob")
126 136
 export("cluster_within_group")
127 137
 export("columnAnnotation")
128
-export("convertXY_in_vp")
129 138
 export("decorate_annotation")
130 139
 export("decorate_column_dend")
131 140
 export("decorate_column_names")
... ...
@@ -143,6 +152,7 @@ export("dend_xy")
143 152
 export("dendrogramGrob")
144 153
 export("densityHeatmap")
145 154
 export("dist2")
155
+export("getXY_in_parent_vp")
146 156
 export("grid.boxplot")
147 157
 export("grid.dendrogram")
148 158
 export("ht_global_opt")
... ...
@@ -387,8 +387,8 @@ size.HeatmapAnnotation = function(x, ...) {
387 387
 # The returned unit x is always in ``mm``.
388 388
 #
389 389
 # == example
390
-# lgd = Legend(labels = 1:10, title = "foo", gp = gpar(fill = "red"))
391
-# width(lgd)
390
+# lgd = Legend(labels = 1:10, title = "foo", legend_gp = gpar(fill = "red"))
391
+# ComplexHeatmap:::width(lgd)
392 392
 #
393 393
 width.Legends = function(x, ...) {
394 394
 	s = attr(x@grob, "width")
... ...
@@ -407,8 +407,8 @@ width.Legends = function(x, ...) {
407 407
 # The returned unit x is always in ``mm``.
408 408
 #
409 409
 # == example
410
-# lgd = Legend(labels = 1:10, title = "foo", gp = gpar(fill = "red"))
411
-# height(lgd)
410
+# lgd = Legend(labels = 1:10, title = "foo", legend_gp = gpar(fill = "red"))
411
+# ComplexHeatmap:::height(lgd)
412 412
 #
413 413
 height.Legends = function(x, ...) {
414 414
 	s = attr(x@grob, "height")
... ...
@@ -424,7 +424,7 @@ height.Legends = function(x, ...) {
424 424
 # -... Other arguments.
425 425
 #
426 426
 width.HeatmapList = function(x, ...) {
427
-    if(object@layout$initialized) {
427
+    if(x@layout$initialized) {
428 428
         x@ht_list_param$width
429 429
     } else {
430 430
         stop_wrap("width() can only be applied to the heatmap list object returned by draw().")
... ...
@@ -440,7 +440,7 @@ width.HeatmapList = function(x, ...) {
440 440
 # -... Other arguments.
441 441
 #
442 442
 height.HeatmapList = function(x, ...) {
443
-    if(object@layout$initialized) {
443
+    if(x@layout$initialized) {
444 444
         x@ht_list_param$height
445 445
     } else {
446 446
         stop_wrap("height() can only be applied to the heatmap list object returned by draw().")
... ...
@@ -5,7 +5,7 @@
5 5
 # == detail 
6 6
 # This class is a super class for `Heatmap-class`, `HeatmapList-class` and
7 7
 # `HeatmapAnnotation-class` classes. It is only designed for ``+`` generic
8
-# method and the `\%v\%v` method so that above three classes can be appended to each other.
8
+# method and the ``\%v\%v`` method so that above three classes can be appended to each other.
9 9
 #
10 10
 AdditiveUnit = setClass("AdditiveUnit")
11 11
 
... ...
@@ -3,23 +3,20 @@
3 3
 # class for single heatmap
4 4
 #
5 5
 
6
-
7
-# the layout of the heatmap is 7 x 9
8
-
9 6
 # == title
10
-# Class for a single heatmap
7
+# Class for a Single Heatmap
11 8
 #
12 9
 # == details
13 10
 # The `Heatmap-class` is not responsible for heatmap legend and annotation legends. The `draw,Heatmap-method` method
14
-# will construct a `HeatmapList-class` object which only contains one single heatmap
15
-# and call `draw,HeatmapList-method` to make a complete heatmap.
11
+# constructs a `HeatmapList-class` object which only contains one single heatmap
12
+# and call `draw,HeatmapList-method` to make the complete heatmap.
16 13
 #
17 14
 # == methods
18 15
 # The `Heatmap-class` provides following methods:
19 16
 #
20 17
 # - `Heatmap`: constructor method.
21 18
 # - `draw,Heatmap-method`: draw a single heatmap.
22
-# - `add_heatmap,Heatmap-method` append heatmaps and row annotations to a list of heatmaps.
19
+# - `add_heatmap,Heatmap-method` append heatmaps and annotations to a list of heatmaps.
23 20
 # - `row_order,HeatmapList-method`: get order of rows
24 21
 # - `column_order,HeatmapList-method`: get order of columns
25 22
 # - `row_dend,HeatmapList-method`: get row dendrograms
... ...
@@ -79,115 +76,114 @@ Heatmap = setClass("Heatmap",
79 76
 # Constructor method for Heatmap class
80 77
 #
81 78
 # == param
82
-# -matrix a matrix. Either numeric or character. If it is a simple vector, it will be
79
+# -matrix A matrix. Either numeric or character. If it is a simple vector, it will be
83 80
 #         converted to a one-column matrix.
84
-# -col a vector of colors if the color mapping is discrete or a color mapping 
85
-#      function if the matrix is continuous numbers (should be generated by `circlize::colorRamp2`. If the matrix is continuous,
86
-#      the value can also be a vector of colors so that colors will be interpolated. Pass to `ColorMapping`.
87
-# -name name of the heatmap. The name is used as the title of the heatmap legend.
88
-# -na_col color for ``NA`` values.
89
-# -rect_gp graphic parameters for drawing rectangles (for heatmap body).
90
-# -color_space the color space in which colors are interpolated. Only used if ``matrix`` is numeric and 
81
+# -col A vector of colors if the color mapping is discrete or a color mapping 
82
+#      function if the matrix is continuous numbers (should be generated by `circlize::colorRamp2`). If the matrix is continuous,
83
+#      the value can also be a vector of colors so that colors can be interpolated. Pass to `ColorMapping`. For more details
84
+#      and examples, please refer to https://jokergoo.github.io/ComplexHeatmap-reference/book/a-single-heatmap.html#colors .
85
+# -name Name of the heatmap. By default the heatmap name is used as the title of the heatmap legend.
86
+# -na_col Color for ``NA`` values.
87
+# -rect_gp Graphic parameters for drawing rectangles (for heatmap body). The value should be specified by `grid::gpar` and ``fill`` parameter is ignored.
88
+# -color_space The color space in which colors are interpolated. Only used if ``matrix`` is numeric and 
91 89
 #            ``col`` is a vector of colors. Pass to `circlize::colorRamp2`.
92
-# -border whether draw border or the color of border.
93
-# -cell_fun self-defined function to add graphics on each cell. Seven parameters will be passed into 
94
-#           this function: ``i``, ``j``, ``x``, ``y``, ``width``, ``height``, ``fill`` which are row index,
95
-#           column index in ``matrix``, coordinate of the middle points in the heatmap body viewport,
90
+# -border Whether draw border. The value can be logical or a string of color.
91
+# -cell_fun Self-defined function to add graphics on each cell. Seven parameters will be passed into 
92
+#           this function: ``j``, ``i``, ``x``, ``y``, ``width``, ``height``, ``fill`` which are column index,
93
+#           row index in ``matrix``, coordinate of the cell,
96 94
 #           the width and height of the cell and the filled color. ``x``, ``y``, ``width`` and ``height`` are all `grid::unit` objects.
97
-# -layer_fun similar as ``cell_fun``, but is vectorized. 
98
-# -row_title title on row.
99
-# -row_title_side will the title be put on the left or right of the heatmap?
100
-# -row_title_gp graphic parameters for drawing text.
101
-# -row_title_rot rotation of row titles. Only 0, 90, 270 are allowed to set.
102
-# -column_title title on column.
103
-# -column_title_side will the title be put on the top or bottom of the heatmap?
104
-# -column_title_gp graphic parameters for drawing text.
105
-# -column_title_rot rotation of column titles. Only 0, 90, 270 are allowed to set.
106
-# -cluster_rows If the value is a logical, it means whether make cluster on rows. The value can also
107
-#               be a `stats::hclust` or a `stats::dendrogram` that already contains clustering information.
108
-#               This means you can use any type of clustering methods and render the `stats::dendrogram`
109
-#               object with self-defined graphic settings.
110
-# -clustering_distance_rows it can be a pre-defined character which is in 
95
+# -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 .
96
+# -row_title Title on the row.
97
+# -row_title_side Will the title be put on the left or right of the heatmap?
98
+# -row_title_gp Graphic parameters for row title.
99
+# -row_title_rot Rotation of row title. Only 0, 90, 270 are allowed to set.
100
+# -column_title Title on the column.
101
+# -column_title_side Will the title be put on the top or bottom of the heatmap?
102
+# -column_title_gp Graphic parameters for column title.
103
+# -column_title_rot Rotation of column titles. Only 0, 90, 270 are allowed to set.
104
+# -cluster_rows If the value is a logical, it controls whether to make cluster on rows. The value can also
105
+#               be a `stats::hclust` or a `stats::dendrogram` which already contains clustering.
106
+#               Check https://jokergoo.github.io/ComplexHeatmap-reference/book/a-single-heatmap.html#clustering .
107
+# -clustering_distance_rows It can be a pre-defined character which is in 
111 108
 #                ("euclidean", "maximum", "manhattan", "canberra", "binary", 
112 109
 #                "minkowski", "pearson", "spearman", "kendall"). It can also be a function.
113 110
 #                If the function has one argument, the input argument should be a matrix and 
114 111
 #                the returned value should be a `stats::dist` object. If the function has two arguments,
115 112
 #                the input arguments are two vectors and the function calculates distance between these
116 113
 #                two vectors.
117
-# -clustering_method_rows method to make cluster, pass to `stats::hclust`.
118
-# -row_dend_side should the row cluster be put on the left or right of the heatmap?
119
-# -row_dend_width width of the row cluster, should be a `grid::unit` object.
120
-# -show_row_dend whether show row clusters. 
121
-# -row_dend_gp graphics parameters for drawing lines. If users already provide a `stats::dendrogram`
114
+# -clustering_method_rows Method to perform hierarchical clustering, pass to `stats::hclust`.
115
+# -row_dend_side Should the row dendrogram be put on the left or right of the heatmap?
116
+# -row_dend_width Width of the row dendrogram, should be a `grid::unit` object.
117
+# -show_row_dend Whether show row dendrogram?
118
+# -row_dend_gp Graphic parameters for the dendrogram segments. If users already provide a `stats::dendrogram`
122 119
 #                object with edges rendered, this argument will be ignored.
123
-# -row_dend_reorder apply reordering on rows. The value can be a logical value or a vector which contains weight 
124
-#               which is used to reorder rows
125
-# -cluster_columns whether make cluster on columns. Same settings as ``cluster_rows``.
126
-# -clustering_distance_columns same setting as ``clustering_distance_rows``.
127
-# -clustering_method_columns method to make cluster, pass to `stats::hclust`.
128
-# -column_dend_side should the column cluster be put on the top or bottom of the heatmap?
120
+# -row_dend_reorder Apply reordering on row dendrograms. The value can be a logical value or a vector which contains weight 
121
+#               which is used to reorder rows. The reordering is applied by `stats::reorder.dendrogram`.
122
+# -cluster_columns Whether make cluster on columns? Same settings as ``cluster_rows``.
123
+# -clustering_distance_columns Same setting as ``clustering_distance_rows``.
124
+# -clustering_method_columns Method to perform hierarchical clustering, pass to `stats::hclust`.
125
+# -column_dend_side Should the column dendrogram be put on the top or bottom of the heatmap?
129 126
 # -column_dend_height height of the column cluster, should be a `grid::unit` object.
130
-# -show_column_dend whether show column clusters.
131
-# -column_dend_gp graphic parameters for drawling lines. Same settings as ``row_dend_gp``.
132
-# -column_dend_reorder apply reordering on columns. The value can be a logical value or a vector which contains weight 
133
-#               which is used to reorder columns
134
-# -row_order order of rows. It makes it easy to adjust row order for a list of heatmaps if this heatmap 
135
-#      is selected as the main heatmap. Manually setting row order should turn off clustering
136
-# -column_order order of column. It makes it easy to adjust column order for both matrix and column annotations.
137
-# -row_labels row labels
138
-# -row_names_side should the row names be put on the left or right of the heatmap?
139
-# -show_row_names whether show row names.
140
-# -row_names_max_width maximum width of row names viewport. Because some times row names can be very long, it is not reasonable
141
-#                      to show them all.
142
-# -row_names_gp graphic parameters for drawing text.
143
-# -row_names_rot rotation of row labels
144
-# -column_labels column labels
145
-# -column_names_side should the column names be put on the top or bottom of the heatmap?
146
-# -column_names_max_height maximum height of column names viewport.
147
-# -show_column_names whether show column names.
148
-# -column_names_gp graphic parameters for drawing text.
149
-# -column_names_rot rotation of column labels
150
-# -top_annotation a `HeatmapAnnotation` object which contains a list of annotations.
151
-# -bottom_annotation a `HeatmapAnnotation` object.
152
-# -left_annotation should specified in `rowAnnotation`
153
-# -right_annotation should shpecified in `rowAnnotation`
154
-# -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.
155
-#     For each row-clusters, hierarchical clustering is still applied with parameters above.
156
-# -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
157
-#        indicating rows are to be split according to the split on the tree.
158
-# -row_km row km
159
-# -row_split row split
160
-# -column_km column km
161
-# -column_split column split
162
-# -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
163
-#   to top to bottom in the heatmap
164
-# -row_gap row gap
165
-# -column_gap column gap
166
-# -width width of the heatmap body
167
-# -height height of the heatmap body
168
-# -heatmap_width width of the whole heatmap (including heatmap components)
169
-# -heatmap_height height of the whole heatmap (including heatmap components)
170
-# -show_heatmap_legend whether show heatmap legend?
171
-# -heatmap_legend_param a list contains parameters for the heatmap legend. See `color_mapping_legend,ColorMapping-method` for all available parameters.
172
-# -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``
127
+# -show_column_dend Whether show column dendrogram?
128
+# -column_dend_gp Graphic parameters for dendrogram segments. Same settings as ``row_dend_gp``.
129
+# -column_dend_reorder Apply reordering on column dendrograms. Same settings as ``row_dend_reorder``.
130
+# -row_order Order of rows. Manually setting row order turns off clustering.
131
+# -column_order Order of column.
132
+# -row_labels Optional row labels which are put as row names in the heatmap.
133
+# -row_names_side Should the row names be put on the left or right of the heatmap?
134
+# -show_row_names Whether show row names.
135
+# -row_names_max_width Maximum width of row names viewport.
136
+# -row_names_gp Graphic parameters for row names.
137
+# -row_names_rot Rotation of row names.
138
+# -column_labels Optional column labels which are put as column names in the heatmap.
139
+# -column_names_side Should the column names be put on the top or bottom of the heatmap?
140
+# -column_names_max_height Maximum height of column names viewport.
141
+# -show_column_names Whether show column names.
142
+# -column_names_gp Graphic parameters for drawing text.
143
+# -column_names_rot Rotation of column names.
144
+# -top_annotation A `HeatmapAnnotation` object.
145
+# -bottom_annotation A `HeatmapAnnotation` object.
146
+# -left_annotation It should be specified by `rowAnnotation`.
147
+# -right_annotation it should be specified by `rowAnnotation`.
148
+# -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.
149
+#     For each row slice, hierarchical clustering is still applied with parameters above.
150
+# -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
151
+#        indicating to split the dendrogram by `stats::cutree`.
152
+# -row_km Same as ``km``.
153
+# -row_split Same as ``split``.
154
+# -column_km K-means clustering on columns.
155
+# -column_split Split on columns. For heatmap splitting, please refer to https://jokergoo.github.io/ComplexHeatmap-reference/book/a-single-heatmap.html#heatmap-split .
156
+# -gap Gap between row slices if the heatmap is split by rows. The value should be a `grid::unit` object.
157
+# -row_gap Same as ``gap``.
158
+# -column_gap Gap between column slices.
159
+# -width Width of the heatmap body.
160
+# -height Height of the heatmap body.
161
+# -heatmap_width Width of the whole heatmap (including heatmap components)
162
+# -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 .
163
+# -show_heatmap_legend Whether show heatmap legend?
164
+# -heatmap_legend_param A list contains parameters for the heatmap legends. See `color_mapping_legend,ColorMapping-method` for all available parameters.
165
+# -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``
173 166
 #       is set, ``use_raster`` is enforced to be ``FALSE``.
174
-# -raster_device graphic device which is used to generate the raster image
175
-# -raster_quality a value set to larger than 1 will improve the quality of the raster image.
176
-# -raster_device_param a list of further parameters for the selected graphic device
177
-# -post_fun a function which will be executed after the plot is drawn.
167
+# -raster_device Graphic device which is used to generate the raster image.
168
+# -raster_quality A value set to larger than 1 will improve the quality of the raster image.
169
+# -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 .
170
+# -post_fun A function which will be executed after the heatmap list is drawn.
178 171
 #
179 172
 # == details
180
-# The initialization function only applies parameter checking and fill values to the slots with proper values.
173
+# The initialization function only applies parameter checking and fill values to the slots with some validation.
181 174
 # 
182
-# Following methods can be applied on the `Heatmap-class` object:
175
+# Following methods can be applied to the `Heatmap-class` object:
183 176
 #
184 177
 # - `show,Heatmap-method`: draw a single heatmap with default parameters
185 178
 # - `draw,Heatmap-method`: draw a single heatmap.
186
-# - ``+`` or `\%v\%` append heatmaps and row annotations to a list of heatmaps.
179
+# - ``+`` or `\%v\%` append heatmaps and annotations to a list of heatmaps.
187 180
 #
188 181
 # The constructor function pretends to be a high-level graphic function because the ``show`` method
189 182
 # of the `Heatmap-class` object actually plots the graphics.
190 183
 #
184
+# == seealso
185
+# https://jokergoo.github.io/ComplexHeatmap-reference/book/a-single-heatmap.html
186
+#
191 187
 # == value
192 188
 # A `Heatmap-class` object.
193 189
 #
... ...
@@ -3,15 +3,15 @@
3 3
 # Class for Heatmap Annotations
4 4
 #
5 5
 # == details
6
-# A complex heatmap contains a list of annotations which are represented as different graphics
6
+# A complex heatmap contains a list of annotations which are represented as graphics
7 7
 # placed on rows and columns. The `HeatmapAnnotation-class` contains a list of single annotations which are
8
-# represented as a list of `SingleAnnotation-class` objects with same number of rows or columns.
8
+# represented as a list of `SingleAnnotation-class` objects.
9 9
 #
10 10
 # == methods
11 11
 # The `HeatmapAnnotation-class` provides following methods:
12 12
 #
13
-# - `HeatmapAnnotation`: constructor method
14
-# - `draw,HeatmapAnnotation-method`: draw the annotations
13
+# - `HeatmapAnnotation`: constructor method.
14
+# - `draw,HeatmapAnnotation-method`: draw the annotations.
15 15
 #
16 16
 # == author
17 17
 # Zuguang Gu <z.gu@dkfz.de>
... ...
@@ -39,47 +39,53 @@ HeatmapAnnotation = setClass("HeatmapAnnotation",
39 39
 )
40 40
 
41 41
 # == title
42
-# Constructor method for HeatmapAnnotation class
42
+# Constructor Method for HeatmapAnnotation class
43 43
 #
44 44
 # == param
45 45
 # -... Name-value pairs where the names correspond to annotation names and values can be a vector, a matrix and an
46 46
 #      annotation function. Each pair is sent to `SingleAnnotation` to contruct a single annotation.
47 47
 # -df A data frame. Each column will be treated as a simple annotation. The data frame must have column names.
48 48
 # -name Name of the heatmap annotation, optional.
49
-# -col A list of colors which contain color mapping to columns in ``df`` and simple annotations define din ``...``. 
49
+# -col A list of colors which contain color mapping to ``df`` or simple annotations defined in ``...``. 
50 50
 #      See `SingleAnnotation` for how to set colors.
51 51
 # -na_col Color for ``NA`` values in simple annotations.
52 52
 # -annotation_legend_param A list which contains parameters for annotation legends. See `color_mapping_legend,ColorMapping-method` for all possible options.
53
-# -show_legend Whether show annotation legend. The value can be one single value or a vector which corresponds to the simple annotations.
54
-# -which Are the annotations row annotations or column annotations?
53
+# -show_legend Whether show annotation legends. The value can be one single value or a vector which corresponds to simple annotations.
54
+# -which Are these row annotations or column annotations?
55 55
 # -gp Graphic parameters for simple annotations (with ``fill`` parameter ignored).
56 56
 # -border border of single annotations.
57
-# -gap Gap between each two annotation. It can be a single value or a vector of `grid::unit` objects.
57
+# -gap Gap between annotations. It can be a single value or a vector of `grid::unit` objects.
58 58
 # -show_annotation_name Whether show annotation names? For column annotation, annotation names are drawn either on the left
59
-#   or the right, and for row annotations, names are draw either on top to at bottom. The value can be a vector.
59
+#   or the right, and for row annotations, names are draw either on top or at the bottom. The value can be a vector.
60 60
 # -annotation_name_gp Graphic parameters for anntation names. Graphic paramters can be vectors.
61 61
 # -annotation_name_offset Offset to the annotations, `grid::unit` object. The value can be a vector.
62 62
 # -annotation_name_side Side of the annotation names.
63
-# -annotation_name_rot Rotation of the annotation names, can only take values in ``c(00, 90, 180, 270)``. The value can be a vector.
63
+# -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.
64 64
 # -annotation_height Height of each annotation if annotations are column annotations.
65 65
 # -annotation_width Width of each annotation if annotations are row annotations.
66
-# -height Height of the complete column annotations.
67
-# -width Width of the complete heatmap annotations.
68
-# -anno_simple_size size of the simple annotation.
69
-# -simple_anno_size_adjust whether also adjust the size of simple annotations when adjust the whole heatmap annotation.
66
+# -height Height of the whole column annotations.
67
+# -width Width of the whole heatmap annotations.
68
+# -anno_simple_size Size of the simple annotation.
69
+# -simple_anno_size_adjust Whether also adjust the size of simple annotations when adjusting the whole heatmap annotation.
70 70
 #
71 71
 # == details
72
+# For arguments ``border``, ``annotation_name_offset``, ``annotation_name_side``, ``annotation_name_rot``,
73
+# ``show_annotation_name``, they can be set as named vectors to modify values for some of the annotations,
74
+# e.g. assuming you have an annotation with name ``foo``, you can specify ``border = c(foo = TRUE)`` in `HeatmapAnnotation`.
75
+# 
72 76
 # There are three ways to specify heatmap annotations:
73 77
 #
74
-# 1. If the annotation is simply a vector or a matrix, it can be specified as ``HeatmapAnnotation(foo = 1:10)``.
75
-# 2. If the annotations are already stored as a data frame, it can be specified as ``HeatmapAnnotation(df = df)``.
76
-# 3. For complex annotation, users can use the pre-defined annotation functions such as `anno_points`: ``HeatmapAnnotation(foo = anno_points(1:10))``.
78
+# 1. If the annotation is simply a vector or a matrix, it can be specified like ``HeatmapAnnotation(foo = 1:10)``.
79
+# 2. If the annotations are already stored as a data frame, it can be specified like ``HeatmapAnnotation(df = df)``.
80
+# 3. For complex annotations, users can use the pre-defined annotation functions such as `anno_points`: ``HeatmapAnnotation(foo = anno_points(1:10))``.
81
+#
82
+# For more details and examples, please check https://jokergoo.github.io/ComplexHeatmap-reference/book/heatmap-annotations.html.
77 83
 #
78 84
 # == value
79 85
 # A `HeatmapAnnotation-class` object.
80 86
 #
81 87
 # == seealso
82
-# There are two shortcut functions: `rowAnnotation` and `columnAnnotation`.
88
+# There are two helper functions: `rowAnnotation` and `columnAnnotation`.
83 89
 #
84 90
 # == author
85 91
 # Zuguang Gu <z.gu@dkfz.de>
... ...
@@ -427,7 +433,7 @@ HeatmapAnnotation = function(...,
427 433
 # Construct Row Annotations
428 434
 #
429 435
 # == param
430
-# -... Pass to `HeatmapAnnotation`
436
+# -... Pass to `HeatmapAnnotation`.
431 437
 #
432 438
 # == details
433 439
 # The function is identical to 
... ...
@@ -448,7 +454,7 @@ rowAnnotation = function(...) {
448 454
 # Construct Column Annotations
449 455
 #
450 456
 # == param
451
-# -... Pass to `HeatmapAnnotation`
457
+# -... Pass to `HeatmapAnnotation`.
452 458
 #
453 459
 # == details
454 460
 # The function is identical to
... ...
@@ -721,6 +727,10 @@ setMethod(f = "show",
721 727
 # -object The `HeatmapAnnotation-class` object.
722 728
 # -... other arguments.
723 729
 #
730
+# == value
731
+# If there is no ``nobs`` information for any of its `SingleAnnotation-class` object,
732
+# it returns ``NA``.
733
+#
724 734
 nobs.HeatmapAnnotation = function(object, ...) {
725 735
 	n_anno = length(object@anno_list)
726 736
 	len = sapply(seq_len(n_anno), function(i) {
... ...
@@ -740,12 +750,12 @@ nobs.HeatmapAnnotation = function(object, ...) {
740 750
 }
741 751
 
742 752
 # == title
743
-# Add row annotations or heatmaps as a heatmap list
753
+# Add Annotations or Heatmaps as a Heatmap List
744 754
 #
745 755
 # == param
746 756
 # -object A `HeatmapAnnotation-class` object.
747 757
 # -x A `Heatmap-class` object, a `HeatmapAnnotation-class` object or a `HeatmapList-class` object.
748
-# -direction Whether it is a horizontal add or a vertical add?
758
+# -direction Whether it is horizontal list or a vertical list?
749 759
 #
750 760
 # == details
751 761
 # Normally we directly use ``+`` for horizontal concatenation and `\%v\%` for vertical concatenation.
... ...
@@ -776,10 +786,10 @@ setMethod(f = "add_heatmap",
776 786
 #
777 787
 # == param
778 788
 # -... `HeatmapAnnotation-class` objects.
779
-# -gap gap between the annotations.
789
+# -gap Gap between the groups of annotations.
780 790
 #
781 791
 # == details
782
-# The heatmap annotations should be same number of observations.
792
+# The heatmap annotations should have same number of observations.
783 793
 # 
784 794
 # == example
785 795
 # ha1 = HeatmapAnnotation(foo = 1:10)
... ...
@@ -977,14 +987,15 @@ length.HeatmapAnnotation = function(x) {
977 987
 # == details
978 988
 # The function only adjust height for column annotations and width for row annotations.
979 989
 #
980
-# the basic rule is:
981
-# 1. if ``annotation_height`` is set, it needs to be a vector and ``height`` is disabled. If all
990
+# The basic rules are (take ``height`` and ``annotation_height`` for example:
991
+#
992
+# 1. If ``annotation_height`` is set and all
982 993
 #    ``annotation_height`` are absolute units, ``height`` is ignored.
983
-# 2. if ``annotation_height`` contains non-absolute units, ``height`` also need to be set and the
984
-#    non-absolute unit should be set in a simple form such as 1:10 or ``unit(1, "null")``.
994
+# 2. If ``annotation_height`` contains non-absolute units, ``height`` also need to be set and the
995
+#    non-absolute units should be set in a simple form such as 1:10 or ``unit(1, "null")``.
985 996
 # 3. ``anno_simple_size`` is only used when ``annotation_height`` is NULL.
986
-# 4. if only ``height`` is set, non-simple annotation is adjusted while keep simple anntation unchanged.
987
-# 5. if only ``height`` is set and all annotations are simple annotations, all anntations are adjusted.
997
+# 4. If only ``height`` is set, non-simple annotation is adjusted while keeps simple anntation unchanged.
998
+# 5. If only ``height`` is set and all annotations are simple annotations, all anntations are adjusted,
988 999
 #      and ``anno_simple_size`` is disabled.
989 1000
 # 6. If ``simple_anno_size_adjust`` is ``FALSE``, the size of the simple annotations will not change.
990 1001
 #
... ...
@@ -245,6 +245,9 @@ setMethod(f = "add_heatmap",
245 245
 # then makes the plot by re-calling the graphic functions which are already recorded
246 246
 # in the layout.
247 247
 #
248
+# == seealso
249
+# https://jokergoo.github.io/ComplexHeatmap-reference/book/a-list-of-heatmaps.html
250
+#
248 251
 # == value
249 252
 # This function returns a `HeatmapList-class` object for which the layout has been created.
250 253
 #
... ...
@@ -569,8 +572,25 @@ setMethod(f = "show",
569 572
 # -j column indices
570 573
 #
571 574
 # == details
572
-# If the heatmap list is horizontal, ``i`` is the real row indices and ``j`` corresponds to heatmap names and single annotation names.
575
+# If the heatmap list is horizontal, ``i`` is the row indices and ``j`` corresponds to heatmap names and single annotation names.
576
+# and if the heatlist is vertical, ``i`` corresponds to heatmap/annotation names and ``j`` is the column indices.
577
+#
578
+# == example
579
+# ht_list = Heatmap(matrix(rnorm(100), 10), name = "rnorm") +
580
+#   rowAnnotation(foo = 1:10, bar = anno_points(10:1)) + 
581
+#   Heatmap(matrix(runif(100), 10), name = "runif")
582
+# summary(ht_list[1:5, ])
583
+# summary(ht_list[1:5, 1])
584
+# summary(ht_list[1:5, "rnorm"])
585
+# summary(ht_list[1:5, c("rnorm", "foo")])
573 586
 #
587
+# ht_list = Heatmap(matrix(rnorm(100), 10), name = "rnorm") \%v\%
588
+#   columnAnnotation(foo = 1:10, bar = anno_points(10:1)) \%v\%
589
+#   Heatmap(matrix(runif(100), 10), name = "runif")
590
+# summary(ht_list[, 1:5])
591
+# summary(ht_list[1, 1:5])
592
+# summary(ht_list["rnorm", 1:5])
593
+# summary(ht_list[c("rnorm", "foo"), 1:5])
574 594
 "[.HeatmapList" = function(x, i, j) {
575 595
 
576 596
     direction = x@direction
... ...
@@ -581,18 +601,19 @@ setMethod(f = "show",
581 601
         }
582 602
     }
583 603
 
584
-    if(length(x@ht_list) == 1) {
585
-        if(inherits(x@ht_list[[1]], "Heatmap")) {
586
-            if(direction == "horizontal") {
587
-                return(x@ht_list[[1]][i, j] + NULL)
604
+    if(direction == "horizontal") {
605
+        if(nargs() == 2) {
606
+            subset_heatmap_list_by_row(x, i, direction)
607
+        } else {
608
+            if(missing(i)) {
609
+                subset_heatmap_list_by_column(x, j, direction)
610
+            } else if(missing(j)) {
611
+                subset_heatmap_list_by_row(x, i, direction)
588 612
             } else {
589
-                return(x@ht_list[[1]][i, j] %v% NULL)
613
+                x = subset_heatmap_list_by_row(x, i, direction)
614
+                subset_heatmap_list_by_column(x, j, direction)
590 615
             }
591 616
         }
592
-    }
593
-
594
-    if(nargs() == 2) {
595
-        subset_heatmap_list_by_row(x, i, direction)
596 617
     } else {
597 618
         if(missing(i)) {
598 619
             subset_heatmap_list_by_column(x, j, direction)
... ...
@@ -617,24 +638,28 @@ subset_heatmap_list_by_row = function(ht_list, ind, direction) {
617 638
             }
618 639
         }
619 640
     } else {
641
+        # if it is vertical heatmap list, `ind` corresponds to heatmap names and annotation names
620 642
         if(is.numeric(ind)) {
621 643
             ht_list@ht_list = ht_list@ht_list[ind]
622 644
         } else {
623
-            ht_list = NULL
645
+            hl = list()
624 646
             # also check annotation names
647
+            if(!all(ind %in% names(ht_list))) {
648
+                stop_wrap("Cannot find all name indices in the heatmap list.")
649
+            }
625 650
             for(nm in names(ht_list@ht_list)) {
626 651
                 if(inherits(ht_list@ht_list[[nm]], "Heatmap")) {
627 652
                     if(nm %in% ind) {
628
-                        ht_list[[nm]] = ht_list@ht_list[[nm]]
653
+                        hl[[nm]] = ht_list@ht_list[[nm]]
629 654
                     }
630 655
                 } else {
631 656
                     anno_nm = names(ht_list@ht_list[[nm]]@anno_list)
632
-                    if(anno_nm %in% ind) {
633
-                        ht_list[[nm]] = ht_list@ht_list[[nm]][, intersect(ind, anno_nm)]
657
+                    if(any(anno_nm %in% ind)) {
658
+                        hl[[nm]] = ht_list@ht_list[[nm]][, intersect(ind, anno_nm)]
634 659
                     }
635 660
                 }
636 661
             }
637
-            ht_list@ht_list = ht_list
662
+            ht_list@ht_list = hl
638 663
         }
639 664
     }
640 665
     return(ht_list)
... ...
@@ -642,24 +667,28 @@ subset_heatmap_list_by_row = function(ht_list, ind, direction) {
642 667
 
643 668
 subset_heatmap_list_by_column = function(ht_list, ind, direction) {
644 669
     if(direction == "horizontal") {
670
+        # if it is horizontal heatmap list, `ind` corresponds to heatmap names and annotation names
645 671
         if(is.numeric(ind)) {
646 672
             ht_list@ht_list = ht_list@ht_list[ind]
647 673
         } else {
648
-            ht_list = NULL
674
+            hl = list()
649 675
             # also check annotation names
676
+            if(!all(ind %in% names(ht_list))) {
677
+                stop_wrap("Cannot find all name indices in the heatmap list.")
678
+            }
650 679
             for(nm in names(ht_list@ht_list)) {
651 680
                 if(inherits(ht_list@ht_list[[nm]], "Heatmap")) {
652 681
                     if(nm %in% ind) {
653
-                        ht_list[[nm]] = ht_list@ht_list[[nm]]
682
+                        hl[[nm]] = ht_list@ht_list[[nm]]
654 683
                     }
655 684
                 } else {
656 685
                     anno_nm = names(ht_list@ht_list[[nm]]@anno_list)
657
-                    if(anno_nm %in% ind) {
658
-                        ht_list[[nm]] = ht_list@ht_list[[nm]][, intersect(ind, anno_nm)]
686
+                    if(any(anno_nm %in% ind)) {
687
+                        hl[[nm]] = ht_list@ht_list[[nm]][, intersect(ind, anno_nm)]
659 688
                     }
660 689
                 }
661 690
             }
662
-            ht_list@ht_list = ht_list
691
+            ht_list@ht_list = hl
663 692
         }
664 693
     } else {
665 694
         for(i in seq_along(ht_list@ht_list)) {
... ...
@@ -700,3 +729,37 @@ names.HeatmapList = function(x) {
700 729
 length.HeatmapList = function(x) {
701 730
     length(x@ht_list)
702 731
 }
732
+
733
+
734
+# == title
735
+# Summary of a Heatmap List
736
+#
737
+# == param
738
+# -object A `HeatmapList-class` object.
739
+# -... Other arguments.
740
+#
741
+summary.HeatmapList = function(object, ...) {
742
+    n_ht = length(object@ht_list)
743
+
744
+    direction = object@direction
745
+
746
+    qqcat("A @{direction} heamtap list with @{n_ht} heatmap/annotations.\n")
747
+
748
+    ht_name = names(object@ht_list)
749
+    for(i in seq_len(n_ht)) {
750
+        if(inherits(object@ht_list[[i]], "Heatmap")) {
751
+            qqcat("  @{ht_name[i]}: a matrix with @{nrow(object@ht_list[[i]]@matrix)} rows and @{ncol(object@ht_list[[i]]@matrix)} columns\n")
752
+        } else {
753
+            qqcat("  @{ht_name[i]}: a list of @{length(object@ht_list[[i]]@anno_list)} annotations\n")
754
+            for(j in seq_along(object@ht_list[[i]]@anno_list)) {
755
+                qqcat("    @{object@ht_list[[i]]@anno_list[[j]]@name}:")
756
+                if(is_simple_annotation(object@ht_list[[i]]@anno_list[[j]])) {
757
+                    qqcat("   a simple annotation.\n")
758
+                } else {
759
+                    qqcat("   a complex annotation.\n")
760
+                }
761
+            }
762
+        }
763
+    }
764
+}
765
+
... ...
@@ -3,10 +3,11 @@
3 3
 # Adjust Heatmap List
4 4
 #
5 5
 # == param
6
-# -object A `HeatmapList-class` object
6
+# -object A `HeatmapList-class` object.
7 7
 #
8 8
 # == details
9
-# This function adjust heatmap components for all heatmaps to align them nicely.
9
+# This function adjusts settings in all other heatmaps according to the main heatmap.
10
+# It also adjust the size of heatmap annotations to make them aligned nicely.
10 11
 #
11 12
 # This function is only for internal use.
12 13
 #
... ...
@@ -461,13 +462,13 @@ setMethod(f = "adjust_heatmap_list",
461 462
 })
462 463
 
463 464
 # == title
464
-# Draw the list of heatmaps
465
+# Draw the List of Heatmaps
465 466
 #
466 467
 # == param
467
-# -object a `HeatmapList-class` object
468
+# -object A `HeatmapList-class` object.
468 469
 #
469 470
 # == details
470
-# A viewport is created which contains heatmaps.
471
+# It only draws the list of heatmaps without legends and titles.
471 472
 #
472 473
 # This function is only for internal use.
473 474
 #
... ...
@@ -607,11 +608,11 @@ setMethod(f = "draw_heatmap_list",
607 608
 })
608 609
 
609 610
 # == title
610
-# Draw heatmap list title
611
+# Draw Heatmap List Title
611 612
 #
612 613
 # == param
613
-# -object a `HeatmapList-class` object
614
-# -which dendrogram on the row or on the column of the heatmap
614
+# -object A `HeatmapList-class` object.
615
+# -which Is it a row title or a column title.
615 616
 #
616 617
 # == details
617 618
 # A viewport is created which contains heatmap list title.
... ...
@@ -1,9 +1,10 @@
1 1
 
2 2
 # == title
3
-# Get row order from a heatmap list
3
+# Get Row Order from a Heatmap List
4 4
 #
5 5
 # == param
6
-# -object a `HeatmapList-class` object
6
+# -object A `HeatmapList-class` object.
7
+# -name Name of a specific heatmap.
7 8
 #
8 9
 # == value
9 10
 # The format of the returned object depends on whether rows/columns of the heatmaps are split.
... ...
@@ -19,7 +20,7 @@
19 20
 # ht_list = Heatmap(mat, row_km = 2) + Heatmap(mat)
20 21
 # ht_list = draw(ht_list)
21 22
 # row_order(ht_list)
22
-# ht_list = Heatmap(mat, row_km = 2) %v% Heatmap(mat)
23
+# ht_list = Heatmap(mat, row_km = 2) \%v\% Heatmap(mat)
23 24
 # ht_list = draw(ht_list)
24 25
 # row_order(ht_list)
25 26
 setMethod(f = "row_order",
... ...
@@ -28,6 +29,10 @@ setMethod(f = "row_order",
28 29
 
29 30
 	object = make_layout(object)
30 31
 
32
+	if(!is.null(name)) {
33
+		return(row_order(object@ht_list[[ name[1] ]]))
34
+	}
35
+
31 36
 	n = length(object@ht_list)
32 37
 	ht_index = which(sapply(seq_along(object@ht_list), function(i) inherits(object@ht_list[[i]], "Heatmap")))
33 38
 	if(length(ht_index) == 0) {
... ...
@@ -53,10 +58,10 @@ setMethod(f = "row_order",
53 58
 })
54 59
 
55 60
 # == title
56
-# Get row order from a heatmap
61
+# Get Row Order from a Heatmap
57 62
 #
58 63
 # == param
59
-# -object a `Heatmap-class` object
64
+# -object A `Heatmap-class` object.
60 65
 #
61 66
 # == value
62 67
 # The format of the returned object depends on whether rows/columns of the heatmaps are split.
... ...
@@ -88,10 +93,11 @@ setMethod(f = "row_order",
88 93
 })
89 94
 
90 95
 # == title
91
-# Get column order from a heatmap list
96
+# Get Column Order from a Heatmap List
92 97
 #
93 98
 # == param
94
-# -object a `HeatmapList-class` object
99
+# -object A `HeatmapList-class` object.
100
+# -name Name of a specific heatmap.
95 101
 #
96 102
 # == value
97 103
 # The format of the returned object depends on whether rows/columns of the heatmaps are split.
... ...
@@ -107,18 +113,22 @@ setMethod(f = "row_order",
107 113
 # ht_list = Heatmap(mat, column_km = 2) + Heatmap(mat, column_km = 2)
108 114
 # ht_list = draw(ht_list)
109 115
 # column_order(ht_list)
110
-# ht_list = Heatmap(mat) %v% Heatmap(mat)
116
+# ht_list = Heatmap(mat) \%v\% Heatmap(mat)
111 117
 # ht_list = draw(ht_list)
112 118
 # column_order(ht_list)
113
-# ht_list = Heatmap(mat, column_km = 2) %v% Heatmap(mat)
119
+# ht_list = Heatmap(mat, column_km = 2) \%v\% Heatmap(mat)
114 120
 # ht_list = draw(ht_list)
115 121
 # column_order(ht_list)
116 122
 setMethod(f = "column_order",
117 123
 	signature = "HeatmapList",
118
-	definition = function(object) {
124
+	definition = function(object, name = NULL) {
119 125
 
120 126
 	object = make_layout(object)
121 127
 
128
+	if(!is.null(name)) {
129
+		return(column_order(object@ht_list[[ name[1] ]]))
130
+	}
131
+
122 132
 	n = length(object@ht_list)
123 133
 	ht_index = which(sapply(seq_along(object@ht_list), function(i) inherits(object@ht_list[[i]], "Heatmap")))
124 134
 	if(length(ht_index) == 0) {
... ...
@@ -144,10 +154,10 @@ setMethod(f = "column_order",
144 154
 })
145 155
 
146 156
 # == title
147
-# Get column order from a heatmap list
157
+# Get Column Order from a Aeatmap List
148 158
 #
149 159
 # == param
150
-# -object a `Heatmap-class` object
160
+# -object A `Heatmap-class` object.
151 161
 #
152 162
 # == value
153 163
 # The format of the returned object depends on whether rows/columns of the heatmaps are split.
... ...
@@ -179,10 +189,11 @@ setMethod(f = "column_order",
179 189
 })
180 190
 
181 191
 # == title
182
-# Get row dendrograms from a heatmap list
192
+# Get Row Dendrograms from a Heatmap List
183 193
 #
184 194
 # == param
185
-# -object a `HeatmapList-class` object
195
+# -object A `HeatmapList-class` object.
196
+# -name Name of a specific heatmap.
186 197
 # 
187 198
 # == value
188 199
 # The format of the returned object depends on whether rows/columns of the heatmaps are split.
... ...
@@ -198,15 +209,19 @@ setMethod(f = "column_order",
198 209
 # ht_list = Heatmap(mat, row_km = 2) + Heatmap(mat)
199 210
 # ht_list = draw(ht_list)
200 211
 # row_dend(ht_list)
201
-# ht_list = Heatmap(mat, row_km = 2) %v% Heatmap(mat)
212
+# ht_list = Heatmap(mat, row_km = 2) \%v\% Heatmap(mat)
202 213
 # ht_list = draw(ht_list)
203 214
 # row_dend(ht_list)
204 215
 setMethod(f = "row_dend",
205 216
 	signature = "HeatmapList",
206
-	definition = function(object) {
217
+	definition = function(object, name = NULL) {
207 218
 
208 219
 	object = make_layout(object)
209 220
 
221
+	if(!is.null(name)) {
222
+		return(row_dend(object@ht_list[[ name[1] ]]))
223
+	}
224
+
210 225
 	n = length(object@ht_list)
211 226
 	ht_index = which(sapply(seq_along(object@ht_list), function(i) inherits(object@ht_list[[i]], "Heatmap")))
212 227
 	if(length(ht_index) == 0) {
... ...
@@ -233,10 +248,10 @@ setMethod(f = "row_dend",
233 248
 
234 249
 
235 250
 # == title
236
-# Get row dendrograms from a heatmap
251
+# Get Row Dendrograms from a Heatmap
237 252
 #
238 253
 # == param
239
-# -object a `Heatmap-class` object
254
+# -object A `Heatmap-class` object.
240 255
 # 
241 256
 # == value
242 257
 # The format of the returned object depends on whether rows/columns of the heatmaps are split.
... ...
@@ -268,10 +283,11 @@ setMethod(f = "row_dend",
268 283
 })
269 284
 
270 285
 # == title
271
-# Get column dendrograms from a heatmap list
286
+# Get Column Dendrograms from a hHeatmap List
272 287
 #
273 288
 # == param
274
-# -object a `HeatmapList-class` object
289
+# -object A `HeatmapList-class` object.
290
+# -name Name of a specific heatmap.
275 291
 # 
276 292
 # == value
277 293
 # The format of the returned object depends on whether rows/columns of the heatmaps are split.
... ...
@@ -287,18 +303,22 @@ setMethod(f = "row_dend",
287 303
 # ht_list = Heatmap(mat, column_km = 2) + Heatmap(mat, column_km = 2)
288 304
 # ht_list = draw(ht_list)
289 305
 # column_dend(ht_list)
290
-# ht_list = Heatmap(mat) %v% Heatmap(mat)
306
+# ht_list = Heatmap(mat) \%v\% Heatmap(mat)
291 307
 # ht_list = draw(ht_list)
292 308
 # column_dend(ht_list)
293
-# ht_list = Heatmap(mat, column_km = 2) %v% Heatmap(mat)
309
+# ht_list = Heatmap(mat, column_km = 2) \%v\% Heatmap(mat)
294 310
 # ht_list = draw(ht_list)
295 311
 # column_dend(ht_list)
296 312
 setMethod(f = "column_dend",
297 313
 	signature = "HeatmapList",
298
-	definition = function(object) {
314
+	definition = function(object, name = NULL) {
299 315
 
300 316
 	object = make_layout(object)
301 317
 
318
+	if(!is.null(name)) {
319
+		return(column_dend(object@ht_list[[ name[1] ]]))
320
+	}
321
+
302 322
 	n = length(object@ht_list)
303 323
 	ht_index = which(sapply(seq_along(object@ht_list), function(i) inherits(object@ht_list[[i]], "Heatmap")))
304 324
 	if(length(ht_index) == 0) {
... ...
@@ -325,10 +345,10 @@ setMethod(f = "column_dend",
325 345
 
326 346
 
327 347
 # == title
328
-# Get column dendrograms from a heatmap
348
+# Get Column Dendrograms from a Heatmap
329 349
 #
330 350
 # == param
331
-# -object a `Heatmap-class` object
351
+# -object A `Heatmap-class` object.
332 352
 # 
333 353
 # == value
334 354
 # The format of the returned object depends on whether rows/columns of the heatmaps are split.
... ...
@@ -1,68 +1,65 @@
1 1
 
2 2
 # == title
3
-# Make layout for the complete plot
3
+# Make Layout for the Heatmap List
4 4
 #
5 5
 # == param
6
-# -object a `HeatmapList-class` object.
7
-# -row_title title on the row.
8
-# -row_title_side will the title be put on the left or right of the heatmap.
9
-# -row_title_gp graphic parameters for drawing text.
10
-# -column_title title on the column.
11
-# -column_title_side will the title be put on the top or bottom of the heatmap.
12
-# -column_title_gp graphic parameters for drawing text.
13
-# -heatmap_legend_side side of the heatmap legend.
14
-# -merge_legends whether put heatmap legends and annotation legends in a same column
15
-# -show_heatmap_legend whether show heatmap legend.
16
-# -heatmap_legend_list a list of self-defined legend, should be wrapped into `grid::grob` objects.
17
-# -annotation_legend_side side of annotation legend.
18
-# -show_annotation_legend whether show annotation legend.
19
-# -annotation_legend_list a list of self-defined legend, should be wrapped into `grid::grob` objects.
20
-# -ht_gap gap between heatmaps, should be a `grid::unit` object.
21
-# -main_heatmap name or index for the main heatmap
22
-# -padding padding of the plot
23
-# -auto_adjust whether autoadjust
24
-# -row_dend_side if auto adjust, where to put the row dendrograms for the main heatmap
25
-# -row_sub_title_side row sub title
26
-# -column_dend_side column dend
27
-# -column_sub_title_side column sub title
28
-# -row_gap gap between row clusters if rows are split
29
-# -cluster_rows same setting as in `Heatmap`, if it is specified, ``cluster_rows`` in main heatmap is ignored.
30
-# -clustering_distance_rows same setting as in `Heatmap`, if it is specified, ``clustering_distance_rows`` in main heatmap is ignored.
31
-# -clustering_method_rows same setting as in `Heatmap`, if it is specified, ``clustering_method_rows`` in main heatmap is ignored.
32
-# -row_dend_width same setting as in `Heatmap`, if it is specified, ``row_dend_width`` in main heatmap is ignored.
33
-# -show_row_dend same setting as in `Heatmap`, if it is specified, ``show_row_dend`` in main heatmap is ignored.
34
-# -row_dend_reorder same setting as in `Heatmap`, if it is specified, ``row_dend_reorder`` in main heatmap is ignored.
35
-# -row_dend_gp same setting as in `Heatmap`, if it is specified, ``row_dend_gp`` in main heatmap is ignored.
36
-# -row_order same setting as in `Heatmap`, if it is specified, ``row_order`` in main heatmap is ignored.
37
-# -row_km row km
38
-# -row_split row split
39
-# -height height of the heatmap body
40
-# -heatmap_height height of the complete heatmap
41
-# -column_gap column gap
42
-# -cluster_columns cluster columns
43
-# -clustering_distance_columns clustering distance columns
44
-# -clustering_method_columns clustering method columns
45
-# -column_dend_width column dend width
46
-# -show_column_dend show column dendrogram
47
-# -column_dend_reorder column dend reorder
48
-# -column_dend_gp column dendrogram gp
49
-# -column_order column order
50
-# -column_km column km
51
-# -column_split column split
52
-# -width width of the heatmap body
53
-# -heatmap_width width of the complete heatmap
6
+# -object A `HeatmapList-class` object.
7
+# -row_title Title on the row.
8
+# -row_title_side Will the title be put on the left or right of the heatmap list?
9
+# -row_title_gp Graphic parameters for the row title.
10
+# -column_title Title on the column.
11
+# -column_title_side Will the title be put on the top or bottom of the heatmap?
12
+# -column_title_gp Graphic parameters for the column title.
13
+# -heatmap_legend_side Side of the heatmap legends.
14
+# -merge_legends Whether to put heatmap legends and annotation legends together. By default they are put in different viewports.
15
+# -show_heatmap_legend Whether show heatmap legends.
16
+# -heatmap_legend_list A list of self-defined legends, should be wrapped into a list of `grid::grob` objects. Normally they are constructed by `Legend`. 
17
+# -annotation_legend_side Side of annotation legends.
18
+# -show_annotation_legend Whether show annotation legends.
19
+# -annotation_legend_list A list of self-defined legends, should be wrapped into a list of `grid::grob` objects. Normally they are constructed by `Legend`.
20
+# -ht_gap Gap between heatmaps, should be a `grid::unit` object. It can be a vector of length 1 or the number of heamtaps/annotations.
21
+# -main_heatmap Name or index for the main heatmap.
22
+# -padding Padding of the whole plot. The four values correspond to the bottom, left, top and right paddings.
23
+# -auto_adjust whether apply automatic adjustment? The auto-adjustment includes turning off dendrograms, titles and row/columns for non-main heatmaps.
24
+# -row_dend_side If auto-adjustment is on, to put the row dendrograms of the main heatmap to the most left side of the heatmap list or the most right side?
25
+# -row_sub_title_side There can be sub titles generated by the splitting of heatmaps. Similar setting as ``row_dend_side``.
26
+# -column_dend_side Similar setting as ``row_dend_side``.
27
+# -column_sub_title_side Similar setting as ``row_sub_title_side``.
28
+# -row_gap Overwrite the corresponding setting in the main heatmap.
29
+# -cluster_rows Overwrite the corresponding setting in the main heatmap.
30
+# -clustering_distance_rows Overwrite the corresponding setting in the main heatmap.
31
+# -clustering_method_rows Overwrite the corresponding setting in the main heatmap.same setting as in `Heatmap`, if it is specified, ``clustering_method_rows`` in main heatmap is ignored.
32
+# -row_dend_width Overwrite the corresponding setting in the main heatmap.
33
+# -show_row_dend same Overwrite the corresponding setting in the main heatmap.
34
+# -row_dend_reorder Overwrite the corresponding setting in the main heatmap.
35
+# -row_dend_gp Overwrite the corresponding setting in the main heatmap.
36
+# -row_order Overwrite the corresponding setting in the main heatmap.
37
+# -row_km Overwrite the corresponding setting in the main heatmap.
38
+# -row_split Overwrite the corresponding setting in the main heatmap.
39
+# -height Overwrite the corresponding setting in the main heatmap.
40
+# -heatmap_height Overwrite the corresponding setting in the main heatmap.
41
+# -column_gap Overwrite the corresponding setting in the main heatmap.
42
+# -cluster_columns Overwrite the corresponding setting in the main heatmap.
43
+# -clustering_distance_columns Overwrite the corresponding setting in the main heatmap.
44
+# -clustering_method_columns Overwrite the corresponding setting in the main heatmap.
45
+# -column_dend_width column Overwrite the corresponding setting in the main heatmap.
46
+# -show_column_dend Overwrite the corresponding setting in the main heatmap.
47
+# -column_dend_reorder Overwrite the corresponding setting in the main heatmap.
48
+# -column_dend_gp Overwrite the corresponding setting in the main heatmap.
49
+# -column_order Overwrite the corresponding setting in the main heatmap.
50
+# -column_km Overwrite the corresponding setting in the main heatmap.
51
+# -column_split Overwrite the corresponding setting in the main heatmap.
52
+# -width Overwrite the corresponding setting in the main heatmap.
53
+# -heatmap_width Overwrite the corresponding setting in the main heatmap.
54 54
 #
55 55
 # == detail
56 56
 # It sets the size of each component of the heatmap list and adjusts graphic
57 57
 # parameters for each heatmap if necessary.
58 58
 #
59
-# The layout for the heatmap list and layout for each heatmap are calculated
60
-# when drawing the heatmap list.
61
-#
62 59
 # This function is only for internal use.
63 60
 #
64 61
 # == value
65
-# A `HeatmapList-class` object in which settings for each heatmap are adjusted.
62
+# A `HeatmapList-class` object in which settings for all heatmap are adjusted.
66 63
 #
67 64
 # == author
68 65
 # Zuguang Gu <z.gu@dkfz.de>
... ...
@@ -1031,17 +1028,17 @@ has_heatmap_list_component = function(object, component) {
1031 1028
 
1032 1029
 
1033 1030
 # == title
1034
-# Width of each heatmap list component
1031
+# Width of Heatmap List Components
1035 1032
 #
1036 1033
 # == param
1037
-# -object a `HeatmapList-class` object.
1038
-# -k which component in the heatmap list, see `HeatmapList-class`.
1034
+# -object A `HeatmapList-class` object.
1035
+# -k Which component in the heatmap list. Values are in ``ComplexHeatmap:::HEATMAP_LIST_LAYOUT_ROW_COMPONENT``.
1039 1036
 #
1040 1037
 # == detail
1041 1038
 # This function is only for internal use.
1042 1039
 #
1043 1040
 # == value
1044
-# A `grid::unit` object
1041
+# A `grid::unit` object.
1045 1042
 #
1046 1043
 # == author
1047 1044
 # Zuguang Gu <z.gu@dkfz.de>
... ...
@@ -1113,14 +1110,14 @@ setMethod(f = "component_width",
1113 1110
 })
1114 1111
 
1115 1112
 # == title
1116
-# Height of each heatmap list component
1113
+# Height of Heatmap List Components
1117 1114
 #
1118 1115
 # == param
1119
-# -object a `HeatmapList-class` object.
1120
-# -k which component in the heatmap list, see `HeatmapList-class`.
1116
+# -object A `HeatmapList-class` object.
1117
+# -k Which component in the heatmap list. Values are in ``ComplexHeatmap:::HEATMAP_LIST_LAYOUT_COLUMN_COMPONENT``.
1121 1118
 #
1122 1119
 # == value
1123
-# A `grid::unit` object
1120
+# A `grid::unit` object.
1124 1121
 #
1125 1122
 # == author
1126 1123
 # Zuguang Gu <z.gu@dkfz.de>
... ...
@@ -770,7 +770,7 @@ setMethod(f = "copy_all",
770 770
 #
771 771
 # == param
772 772
 # -object The `SingleAnnotation-class` object.
773
-# -... other arguments.
773
+# -... Other arguments.
774 774
 #
775 775
 # == details
776 776
 # It returns the ``n`` slot of the annotaton function. If it does not exist, it returns ``NA``.
... ...
@@ -1,23 +1,26 @@
1 1
 # == title
2
-# Decorate the heatmap body
2
+# Decorate Heatmap Bodies
3 3
 #
4 4
 # == param
5
-# -heatmap name of the heatmap which is set as ``name`` argument in `Heatmap` function.
6
-# -code code that adds graphics in the selected heatmap body.
7
-# -slice index of row slices in the heatmap.
8
-# -row_slice index of row slices in the heatmap.
9
-# -column_slice index of column slices in the heatmap.
10
-# -envir where to look for variables inside ``code``
5
+# -heatmap Name of the heatmap which is set as ``name`` argument in `Heatmap` function.
6
+# -code Code that adds graphics in the selected heatmap body.
7
+# -slice Index of the row slice in the heatmap.
8
+# -row_slice Index of the row slice in the heatmap.
9
+# -column_slice Index of the column slice in the heatmap.
10
+# -envir Where to look for variables inside ``code``.
11 11
 #
12 12
 # == details
13
-# There is a viewport for each row slice and each column slice in each heatmap.
13
+# There is a viewport for each slice in each heatmap.
14 14
 # This function contructs the name of the viewport,
15
-# goes to the viewport by `grid::seekViewport` and applies code
16
-# to that viewport.
15
+# goes to the viewport by `grid::seekViewport`, runs the code
16
+# to that viewport and finally goes back to the original viewport.
17 17
 #
18 18
 # == value
19 19
 # This function returns no value.
20 20
 #
21
+# == seealso
22
+# https://jokergoo.github.io/ComplexHeatmap-reference/book/heatmap-decoration.html
23
+#
21 24
 # == author
22 25
 # Zuguang Gu <z.gu@dkfz.de>
23 26
 #
... ...
@@ -46,32 +49,31 @@ decorate_heatmap_body = function(heatmap, code,
46 49
 }
47 50
 
48 51
 # == title
49
-# Decorate the heatmap dendrogram
52
+# Decorate Heatmap Dendrograms
50 53
 #
51 54
 # == param
52
-# -heatmap name of the heatmap
53
-# -code code that adds graphics in the selected heatmap body
54
-# -slice index of row slice or column slice in the heatmap
55
-# -which on rows or on columns?
56
-# -envir where to look for variables inside ``code``
55
+# -heatmap Name of the heatmap.
56
+# -code Code that adds graphics in the selected heatmap dendrogram.
57
+# -slice Index of the row slice or column slice in the heatmap.
58
+# -which Is the dendrogram on rows or on columns?
59
+# -envir Where to look for variables inside ``code``.
57 60
 #
58 61
 # == details
59
-# There is a viewport for each dendrogram in the heatmap.
60
-# This function contructs the name of the viewport,
61
-# goes to the viewport by `grid::seekViewport` and applies code
62
-# to that viewport.
63 62
 #
64 63
 # If you know the number of leaves in the dendrogram, it is
65 64
 # simple to calculate the position of every leave in the dendrogram.
66 65
 # E.g., for the column dendrogram, the i^th leave is located at:
67 66
 #
68
-#     # assume nc is the number of columns 
67
+#     # assume nc is the number of columns in the column slice
69 68
 #     unit((i-0.5)/nc, "npc")
70 69
 #
71 70
 #
72 71
 # == value
73 72
 # This function returns no value.
74 73
 #
74
+# == seealso
75
+# https://jokergoo.github.io/ComplexHeatmap-reference/book/heatmap-decoration.html
76
+#
75 77
 # == author
76 78
 # Zuguang Gu <z.gu@dkfz.de>
77 79
 #
... ...
@@ -100,11 +102,11 @@ decorate_dend = function(heatmap, code, slice = 1, which = c("column", "row"),
100 102
 }
101 103
 
102 104
 # == title
103
-# Decorate heatmap dendrogram on columns
105
+# Decorate Heatmap Column Dendrograms
104 106
 #
105 107
 # == param
106
-# -... pass to `decorate_dend`
107
-# -envir where to look for variables inside ``code``
108
+# -... Pass to `decorate_dend`.
109
+# -envir Where to look for variables inside ``code``.
108 110
 #
109 111
 # == details
110 112
 # This is a wrapper function which pre-defined ``which`` argument in `decorate_dend`.
... ...
@@ -115,20 +117,16 @@ decorate_dend = function(heatmap, code, slice = 1, which = c("column", "row"),
115 117
 # == author
116 118
 # Zuguang Gu <z.gu@dkfz.de>
117 119
 #
118
-# == example
119
-# # No example for this function
120
-# NULL
121
-#
122 120
 decorate_column_dend = function(..., envir = new.env(parent = parent.frame())) {
123 121
 	decorate_dend(..., which = "column", envir = envir)
124 122
 }
125 123
 
126 124
 # == title
127
-# Decorate heatmap dendrogram on rows
125
+# Decorate Heatmap Row Dendrograms
128 126
 #
129 127
 # == param
130
-# -... pass to `decorate_dend`
131
-# -envir where to look for variables inside ``code``
128
+# -... Pass to `decorate_dend`.
129
+# -envir Where to look for variables inside ``code``?
132 130
 #
133 131
 # == details
134 132
 # This is a helper function which pre-defined ``which`` argument in `decorate_dend`.
... ...
@@ -139,36 +137,27 @@ decorate_column_dend = function(..., envir = new.env(parent = parent.frame())) {
139 137
 # == author
140 138
 # Zuguang Gu <z.gu@dkfz.de>
141 139
 #
142
-# == example
143
-# # No example for this function
144
-# NULL
145
-#
146 140
 decorate_row_dend = function(..., envir = new.env(parent = parent.frame())) {
147 141
 	decorate_dend(..., which = "row", envir = envir)
148 142
 }
149 143
 
150 144
 
151 145
 # == title
152
-# Decorate the heatmap dimension names
146
+# Decorate Heatmap Dimension Names
153 147
 #
154 148
 # == param
155
-# -heatmap name of the heatmap
156
-# -code code that adds graphics in the selected heatmap body
157
-# -slice index of row slice or column slice in the heatmap
149
+# -heatmap Name of the heatmap.
150
+# -code Code that adds graphics in the selected viewport.
151
+# -slice Index of the row slice or column slice in the heatmap.
158 152
 # -which on rows or on columns?
159
-# -envir where to look for variables inside ``code``
153
+# -envir where to look for variables inside ``code``.
160 154
 #
161 155
 # == details
162
-# There is a viewport for row names and column names in the heatmap.
163
-# This function contructs the name of the viewport,
164
-# goes to the viewport by `grid::seekViewport` and applies code
165
-# to that viewport.
166
-#
167 156
 # If you know the dimensions of the matrix, it is
168 157
 # simple to calculate the position of every row name or column name in the heatmap.
169 158
 # E.g., for the column column, the i^th name is located at:
170 159
 #
171
-#     # assume nc is the number of columns 
160
+#     # assume nc is the number of columns in the column slice
172 161
 #     unit((i-0.5)/nc, "npc")
173 162
 #
174 163
 #
... ...
@@ -205,11 +194,11 @@ decorate_dimnames = function(heatmap, code, slice = 1, which = c("column", "row"
205 194
 }
206 195
 
207 196
 # == title
208
-# Decorate heatmap row names
197
+# Decorate Heatmap Row Names
209 198
 #
210 199
 # == param
211
-# -... pass to `decorate_dimnames`
212
-# -envir where to look for variables inside ``code``
200
+# -... Pass to `decorate_dimnames`.
201
+# -envir wWhere to look for variables inside ``code``.
213 202
 #
214 203
 # == details
215 204
 # This is a helper function which pre-defined ``which`` argument in `decorate_dimnames`.
... ...
@@ -220,20 +209,16 @@ decorate_dimnames = function(heatmap, code, slice = 1, which = c("column", "row"
220 209
 # == author
221 210
 # Zuguang Gu <z.gu@dkfz.de>
222 211
 #
223
-# == example
224
-# # No example for this function
225
-# NULL
226
-#
227 212
 decorate_row_names = function(..., envir = new.env(parent = parent.frame())) {
228 213
 	decorate_dimnames(..., which = "row", envir = envir)
229 214
 }
230 215
 
231 216
 # == title
232
-# Decorate heatmap column names
217
+# Decorate Heatmap Column Names
233 218
 #
234 219
 # == param
235
-# -... pass to `decorate_dimnames`
236
-# -envir where to look for variables inside ``code``
220
+# -... Pass to `decorate_dimnames`.
221
+# -envir Where to look for variables inside ``code``.
237 222
 #
238 223
 # == details
239 224
 # This is a helper function which pre-defined ``which`` argument in `decorate_dimnames`.
... ...
@@ -244,34 +229,33 @@ decorate_row_names = function(..., envir = new.env(parent = parent.frame())) {
244 229
 # == author
245 230
 # Zuguang Gu <z.gu@dkfz.de>
246 231
 #
247
-# == example
248
-# # No example for this function
249
-# NULL
250
-#
251 232
 decorate_column_names = function(..., envir = new.env(parent = parent.frame())) {
252 233
 	decorate_dimnames(..., which = "column", envir = envir)
253 234
 }
254 235
 
255 236
 
256 237
 # == title
257
-# Decorate the heatmap title
238
+# Decorate Heatmap Titles
258 239
 #
259 240
 # == param
260
-# -heatmap name of the heatmap
261
-# -code code that adds graphics in the selected heatmap body
262
-# -slice index of row slice or column slice in the heatmap
263
-# -which on rows or on columns?
264
-# -envir where to look for variables inside ``code``
241
+# -heatmap Name of the heatmap.
242
+# -code Code that adds graphics in the selected viewport.
243
+# -slice Index of the row slice or column slice in the heatmap.
244
+# -which Is it a row title or a column title?
245
+# -envir Where to look for variables inside ``code``.
265 246
 #
266 247
 # == details
267 248
 # There is a viewport for row titles and column title in the heatmap.
268 249
 # This function contructs the name of the viewport,
269
-# goes to the viewport by `grid::seekViewport` and applies code
270
-# to that viewport.
250
+# goes to the viewport by `grid::seekViewport` , runs code
251
+# to that viewport and finally goes back to the original viewport.
271 252
 #
272 253
 # == value
273 254
 # The function returns no value.
274 255
 #
256
+# == seealso
257
+# https://jokergoo.github.io/ComplexHeatmap-reference/book/heatmap-decoration.html
258
+#
275 259
 # == author
276 260
 # Zuguang Gu <z.gu@dkfz.de>
277 261
 #
... ...
@@ -298,11 +282,11 @@ decorate_title = function(heatmap, code, slice = 1, which = c("column", "row"),
298 282
 }
299 283
 
300 284
 # == title
301
-# Decorate heatmap row title
285
+# Decorate Heatmap Row Titles
302 286
 #
303 287
 # == param
304
-# -... pass to `decorate_title`
305
-# -envir where to look for variables inside ``code``
288
+# -... Pass to `decorate_title`.
289
+# -envir Where to look for variables inside ``code``.
306 290
 #
307 291
 # == details
308 292
 # This is a helper function which pre-defined ``which`` argument in `decorate_title`.
... ...
@@ -313,20 +297,16 @@ decorate_title = function(heatmap, code, slice = 1, which = c("column", "row"),
313 297
 # == author
314 298
 # Zuguang Gu <z.gu@dkfz.de>
315 299
 #
316
-# == example
317
-# # No example for this function
318
-# NULL
319
-#
320 300
 decorate_row_title = function(..., envir = new.env(parent = parent.frame())) {
321 301
 	decorate_title(..., which = "row", envir = envir)
322 302
 }
323 303
 
324 304
 # == title
325
-# Decorate heatmap column title
305
+# Decorate Heatmap Column Titles
326 306
 #
327 307
 # == param
328
-# -... pass to `decorate_title`
329
-# -envir where to look for variables inside ``code``
308
+# -... Pass to `decorate_title`.
309
+# -envir Where to look for variables inside ``code``.
330 310
 #
331 311
 # == details
332 312
 # This is a helper function which pre-defined ``which`` argument in `decorate_title`.
... ...
@@ -337,32 +317,31 @@ decorate_row_title = function(..., envir = new.env(parent = parent.frame())) {
337 317
 # == author
338 318
 # Zuguang Gu <z.gu@dkfz.de>
339 319
 #
340
-# == example
341
-# # No example for this function
342
-# NULL
343
-#
344 320
 decorate_column_title = function(..., envir = new.env(parent = parent.frame())) {
345 321
 	decorate_title(..., which = "column", envir = envir)
346 322
 }
347 323
 
348 324
 # == title
349
-# Decorate the heatmap annotation
325
+# Decorate Heatmap Annotation
350 326
 #
351 327
 # == param
352
-# -annotation name of the annotation
353
-# -code code that adds graphics in the selected heatmap body
354
-# -slice index of row slices in the heatmap
355
-# -envir where to look for variables inside ``code``
328
+# -annotation Name of the annotation.
329
+# -code Code that adds graphics in the selected heatmap annotation.
330
+# -slice Index of the row slices or the column slice in the heatmap.
331
+# -envir Where to look for variables inside ``code``.
356 332
 #
357 333
 # == details
358 334
 # There is a viewport for every column annotation and row annotation.
359 335
 # This function contructs the name of the viewport,
360
-# goes to the viewport by `grid::seekViewport` and applies code
361
-# to that viewport.
336
+# goes to the viewport by `grid::seekViewport`, runs code
337
+# to that viewport, and finally goes back to the original viewport.
362 338
 #
363 339
 # == value
364 340
 # The function returns no value.
365 341
 #
342
+# == seealso
343
+# https://jokergoo.github.io/ComplexHeatmap-reference/book/heatmap-decoration.html
344
+#
366 345
 # == author
367 346
 # Zuguang Gu <z.gu@dkfz.de>
368 347
 #
... ...
@@ -379,7 +358,7 @@ decorate_column_title = function(..., envir = new.env(parent = parent.frame()))
379 358
 # decorate_annotation("point", {
380 359
 #     grid.rect(gp = gpar(fill = "#FF000080"))
381 360
 # }, slice = 2)
382
-
361
+#
383 362
 decorate_annotation = function(annotation, code, slice = 1, envir = new.env(parent = parent.frame())) {
384 363
 
385 364
 	current_vp = current.viewport()$name
... ...
@@ -56,7 +56,7 @@
56 56
 # ha = HeatmapAnnotation(points = anno_points(runif(10)),
57 57
 #     anno = rep(c("A", "B"), each = 5), col = list(anno = c("A" = "red", "B" = "blue")))
58 58
 # densityHeatmap(matrix, top_annotation = ha)
59
-# densityHeatmap(matrix, top_annotation = ha) %v% Heatmap(matrix, height = unit(6, "cm"))
59
+# densityHeatmap(matrix, top_annotation = ha) \%v\% Heatmap(matrix, height = unit(6, "cm"))
60 60
 densityHeatmap = function(data, 
61 61
 	density_param = list(na.rm = TRUE),
62 62
 	
... ...
@@ -1074,6 +1074,7 @@ setMethod(f = "draw",
1074 1074
 # general method. It applies `grid::grid.draw` on the ``grob`` slot of the object.
1075 1075
 #
1076 1076
 # == example
1077
+# lgd = Legend(at = 1:4, title = "foo")
1077 1078
 # pushViewport(viewport(x = unit(0, "npc"), y = unit(0, "npc"), just = c("left", "bottom")))
1078 1079
 # grid.draw(lgd)
1079 1080
 # popViewport()
... ...
@@ -557,7 +557,7 @@ dend_xy = function(dend) {
557 557
 # compare to between-group dendrogram.
558 558
 #
559 559
 # == value
560
-# A `dendrogram` object. The order of columns can be retrieved by `stat::order.dendrogram`.
560
+# A `dendrogram` object. The order of columns can be retrieved by `stats::order.dendrogram`.
561 561
 #
562 562
 # == example
563 563
 # m = matrix(rnorm(120), nc = 12)
... ...
@@ -3,38 +3,40 @@
3 3
 # Make oncoPrint
4 4
 #
5 5
 # == param
6
-# -mat a character matrix which encodes mulitple alterations or a list of matrix for which every matrix contains binary
7
-#      value representing the alteration is present or absent. When it is a list, the names of the list represent alteration types.
6
+# -mat The value should be a character matrix which encodes mulitple alterations 
7
+#      or a list of matrices for which every matrix contains binary
8
+#      value representing whether the alteration is present or absent. 
9
+#      When the value is a list, the names of the list represent alteration types.
8 10
 #      You can use `unify_mat_list` to make all matrix having same row names and column names.
9
-# -get_type If different alterations are encoded in the matrix, this self-defined function
10
-#           determines how to extract them. Only work when ``mat`` is a matrix.
11
-# -alter_fun a single function or a list of functions which define how to add graphics for different alterations.
12
-#                 If it is a list, the names of the list should cover all alteration types.
11
+# -get_type If different alterations are encoded in the matrix as complex strings, this self-defined function
12
+#           determines how to extract them. It only works when ``mat`` is a matrix.
13
+# -alter_fun A single function or a list of functions which defines how to add graphics for different alterations.
13 14
 # -alter_fun_is_vectorized Whether ``alter_fun`` is implemented vectorized. Internally the function will guess.
14
-# -col a vector of color for which names correspond to alteration types.
15
-# -top_annotation Annotation put on top of the oncoPrint. By default it is barplot which shows the number of genes having the alteration in each sample.
16
-# -right_annotation Annotation put on the right of hte oncoPrint. By default it is barplto which shows the number of samples having the alteration in each gene.
17
-# -bottom_annotation
18
-# -show_pct whether show percent values on the left of the oncoprint
19
-# -pct_gp graphic paramters for percent row annotation
20
-# -pct_digits digits for percent values
21
-# -pct_side side of pct
15
+# -col A vector of color for which names correspond to alteration types.
16
+# -top_annotation Annotation put on top of the oncoPrint. By default it is barplot which shows the number of genes with a certain alteration in each sample.
17
+# -right_annotation Annotation put on the right of the oncoPrint. By default it is barplot which shows the number of samples with a certain alteration in each gene.
18
+# -bottom_annotation Annotation put at the bottom of the oncoPrint.
19
+# -show_pct whether show percent values on the left of the oncoprint?
20
+# -pct_gp Graphic paramters for percent values
21
+# -pct_digits Digits for the percent values.
22
+# -pct_side Side of the percent values to the oncoPrint. This argument is currently disabled.
22 23
 # -show_row_names Whether show row names?
23
-# -row_names_side side of the row names
24
-# -row_names_gp Graphic parameters of row names.
25
-# -row_order row order
26
-# -column_order column order
27
-# -remove_empty_columns if there is no alteration in that sample, whether remove it on the heatmap
28
-# -remove_empty_rows if there is no alteration in that sample, whether remove it on the heatmap
24
+# -row_names_side Side of the row names to the oncoPrint. This argument is currently disabled.
25
+# -row_names_gp Graphic parameters for the row names.
26
+# -row_order Order of rows. By default rows are sorted by the number of occurence of the alterations.
27
+# -column_order Order of columns. By default the columns are sorted to show the mutual exclusivity of alterations.
28
+# -remove_empty_columns If there is no alteration in some samples, whether remove them on the oncoPrint?
29
+# -remove_empty_rows If there is no alteration in some samples, whether remove them on the oncoPrint?
29 30
 # -show_column_names Whether show column names?
30
-# -heatmap_legend_param pass to `Heatmap`
31
-# -... pass to `Heatmap`, so can set ``bottom_annotation`` here.
31
+# -heatmap_legend_param pass to `Heatmap`.
32
+# -... Pass to `Heatmap`.
32 33
 #
33 34
 # == details
34 35
 # The 'memo sort' method is from https://gist.github.com/armish/564a65ab874a770e2c26 . Thanks to
35 36
 # B. Arman Aksoy for contributing the code.
36 37
 #
37
-# For more explanation, please go to the vignette.
38
+# https://jokergoo.github.io/ComplexHeatmap-reference/book/oncoprint.html gives details for configuring
39
+# a oncoPrint.
38 40
 #
39 41
 # == value
40 42
 # A `Heatmap-class` object which means you can add other heatmaps or annotations to it.
... ...
@@ -337,14 +339,14 @@ oncoPrint = function(mat,
337 339
 }
338 340
 
339 341
 # == title
340
-# Unify a list of matrix 
342
+# Unify a List of Matrix 
341 343
 #
342 344
 # == param
343
-# -mat_list a list of matrix, all of them should have dimension names
344
-# -default default values for the newly added rows and columns
345
+# -mat_list A list of matrix. All of them should have dimension names.
346
+# -default Default values for the newly added rows and columns.
345 347
 #
346 348
 # == details
347
-# All matrix will be unified to have same row names and column names
349
+# All matrix will be unified to have same row names and column names.
348 350
 #
349 351
 # == value
350 352
 # A list of matrix
... ...
@@ -369,18 +371,18 @@ unify_mat_list = function(mat_list, default = 0) {
369 371
 
370 372
 
371 373
 # == title
372
-# Barplot annotation for oncoPrint
374
+# Barplot Annotation for oncoPrint
373 375
 #
374 376
 # == param
375
-# -type A vector of the alteration types in your data. It can be a subset of all alteration types if you don't want to show them all.
376
-# -which Is ti a row annotation or a column annotation?
377
+# -type A vector of the alteration types in the data. It can be a subset of all alteration types if you don't want to show them all.
378
+# -which Is it a row annotation or a column annotation?
377 379
 # -width Wisth of the annotation.
378 380
 # -height Height of the annotation.
379 381
 # -border Whether draw the border?
380 382
 # -... Other parameters passed to `anno_barplot`.
381 383
 #
382 384
 # == detail
383
-# This annotation function should always use with `oncoPrint`.
385
+# This annotation function should always be used with `oncoPrint`.
384 386
 # 
385 387
 # == author
386 388
 # Zuguang Gu <z.gu@dkfz.de>
... ...
@@ -10,7 +10,7 @@ Class for Concatenating Heatmaps and Annotations
10 10
 \details{
11 11
 This class is a super class for \code{\link{Heatmap-class}}, \code{\link{HeatmapList-class}} and
12 12
 \code{\link{HeatmapAnnotation-class}} classes. It is only designed for \code{+} generic
13
-method so that above three classes can be appended to each other.
13
+method and the \code{\%v\%v} method so that above three classes can be appended to each other.
14 14
 }
15 15
 \examples{
16 16
 # There is no example
... ...
@@ -2,20 +2,19 @@
2 2
 \docType{class}
3 3
 \alias{AnnotationFunction-class}
4 4
 \title{
5
-The AnnotationFunction class
5
+The AnnotationFunction Class
6 6
 }
7 7
 \description{
8
-The AnnotationFunction class
8
+The AnnotationFunction Class
9 9
 }
10 10
 \details{
11
-The heatmap annotation is basically graphics aligned to the heatmap columns
12
-if it is column annotation or heatmap rows if it is row annotation, while
13
-there is no restrictions for the graphic types, e.g. it can be heatmap-like
11
+The heatmap annotation is basically graphics aligned to the heatmap columns or rows.
12
+There is no restriction for the graphic types, e.g. it can be heatmap-like
14 13
 annotation or points. Here the AnnotationFunction class is designed for
15 14
 creating complex and flexible annotation graphics. As the main part of the class, it uses
16 15
 a user-defined function to define the graphics. It also keeps information of
17 16
 the size of the plotting regions of the annotation. And most importantly, it
18
-allows subsetting of the annotation to draw a subset of the graphics, which
17
+allows subsetting to the annotation to draw a subset of the graphics, which
19 18
 is the base for the splitting of the annotations.
20 19
 
21 20
 See \code{\link{AnnotationFunction}} constructor for details.
... ...
@@ -27,99 +27,35 @@ AnnotationFunction(fun, fun_name = "", which = c("column", "row"),
27 27
 
28 28
 }
29 29
 \details{
30
-We use a normal R function defines how to draw the annotation graphics. As
31
-expected, the main part of the AnnotationFunction class is this function.
32
-The function defines how to draw at specific positions which correspond to
33
-rows or columns in the heatmap. The function should have three arguments:
34
-\code{index}, \code{k} and \code{n} (the names of the arguments can be arbitory)
35
-where \code{k} and \code{n} are optional. \code{index} corresponds to the indices of
36
-rows or columns of the heatmap. The value of \code{index} is not necessarily to
37
-be the whole row indices or column indices of the heatmap. It can be a
38
-subset of the indices if the annotation is split into slices according to
39
-the split of the heatmap. \code{index} is always reordered according to the
40
-reordering of heatmap rows or columns (e.g. by clustering). So, \code{index}
41
-actually contains a list of row or column indices for the current slice
42
-after row or column reordering.
43
-
44
-As mentioned, annotation can be split into slices. \code{k} corresponds to the
45
-current slice and \code{n} corresponds to the total number of slices. As you can image, 
46
-when \code{n > 1}, the annotation function will be executed for all \code{k}s. The
47
-information of \code{k} and \code{n} sometimes can be useful, for example, we want
48
-to add axis ot the right side of a column annotation, if this column annotation
49
-is split into several slices, the axis is only drawn when\code{k == n}.
50
-
51
-Since the function only allows \code{index}, \code{k} and \code{n}, the function
52
-sometimes uses several external variables which can not be defined inside
53
-the function, e.g. the data points for the annotation. These variables
54
-should be imported into the AnnotationFunction class so that the function
55
-can correctly find these variables (by \code{var_import} argument).
56
-
57
-One important feature for AnnotationFunction class is it can be subsetable.
58
-To allow subsetting of the object, users need to define the rules for the
59
-imported variables. The rules are simple function which
60
-accpets the variable and indices, and returns the subset of the variable.
61
-The subset rule functions implemented in this package are \code{\link{subset_gp}},
62
-\code{\link{subset_matrix_by_row}} and \code{\link{subset_vector}}. These three functions are enough
63
-for most of the cases.
64
-
65
-In following, we defined three AnnotationFunction objects:
66
-
67
-1. It needs external variable and support subsetting
68
-
69
-x = 1:10
70
-anno1 = AnnotationFunction(
71
-	fun = function(index) {
72
-		n = length(index)
73
-		pushViewport(viewport())
74
-		grid.points(1:n, x[index])
75
-		popViewport()
76
-	},
77
-	var_imported = list(x = x),
78
-	n = 10,
79
-	subset_rule = list(x = subset_vector),
80
-	subsetable = TRUE
81
-)
82
-
83
-2. The data variable is defined inside the function and no need to import other variables.
84
-
85
-anno2 = AnnotationFunction(
86
-	fun = function(index) {
87
-		x = 1:10
88
-		n = length(index)
89
-		pushViewport(viewport())
90
-		grid.points(1:n, x[index])
91
-		popViewport()
92
-	},
93
-	n = 10,
94
-	subsetable = TRUE
95
-)
96
-
97
-3. Only specify the function to the constructor. \code{anno3} is not subsettable.
98
-
99
-anno3 = AnnotationFunction(
100
-	fun = function(index) {
101
-		x = 1:10
102
-		n = length(index)
103
-		pushViewport(viewport())
104
-		grid.points(1:n, x[index])
105
-		popViewport()
106
-	}
107
-)
108
-
109
-As you can see from the examples, you need to push a viewport for graphics and finally pop the viewport.
110
-
111
-In the package, we have implemted quite a lot annotation function by \code{\link{AnnotationFunction}} constructor:
30
+In the package, we have implemted quite a lot annotation functions by \code{\link{AnnotationFunction}} constructor:
112 31
 \code{\link{anno_empty}}, \code{\link{anno_image}}, \code{\link{anno_points}}, \code{\link{anno_lines}}, \code{\link{anno_barplot}}, \code{\link{anno_boxplot}}, \code{\link{anno_histogram}},
113 32
 \code{\link{anno_density}}, \code{\link{anno_joyplot}}, \code{\link{anno_horizon}}, \code{\link{anno_text}} and \code{\link{anno_mark}}. These built-in annotation functions
114 33
 support as both row annotations and column annotations and they are are all subsettable.
115
-}
116
-\seealso{
34
+
117 35
 The build-in annotation functions are already enough for most of the analysis, nevertheless, if users
118 36
 want to know more about how to construct the AnnotationFunction class manually, they can refer to
119
-ComplexHeatmap Complete Reference ().
37
+\url{https://jokergoo.github.io/ComplexHeatmap-reference/book/heatmap-annotations.html#implement-new-annotation-functions.}
38
+}
39
+\value{
40
+A \code{\link{AnnotationFunction-class}} object which can be used in \code{\link{HeatmapAnnotation}}.
120 41
 }
121 42
 \examples{
122
-# There is no example
123
-NULL
124
-
43
+x = 1:10
44
+anno1 = AnnotationFunction(
45
+    fun = function(index, k, n) {
46
+        n = length(index)
47
+        pushViewport(viewport(xscale = c(0.5, n + 0.5), yscale = c(0, 10)))
48
+        grid.rect()
49
+        grid.points(1:n, x[index], default.units = "native")
50
+        if(k == 1) grid.yaxis()
51
+        popViewport()
52
+    },
53
+    var_import = list(x = x),
54
+    n = 10,
55
+    subsetable = TRUE,
56
+    height = unit(2, "cm")
57
+)
58
+m = rbind(1:10, 11:20)
59
+Heatmap(m, top_annotation = HeatmapAnnotation(foo = anno1))
60
+Heatmap(m, top_annotation = HeatmapAnnotation(foo = anno1), column_km = 2)
125 61
 }
... ...
@@ -12,11 +12,11 @@ This package aims to provide a simple and flexible way to arrange
12 12
 multiple heatmaps as well as flexible annotation graphics.
13 13
 
14 14
 The package is implemented in an object-oriented way. 
15
-Components of heatmap lists are abstracted into several classes.
15
+The heatmap lists are abstracted into several classes.
16 16
 
17 17
 \itemize{
18
-  \item \code{\link{Heatmap-class}}: a single heatmap containing heatmap body, row/column names, titles, dendrograms and column annotations.
19
-  \item \code{\link{HeatmapList-class}}: a list of heatmaps and row/column annotations.
18
+  \item \code{\link{Heatmap-class}}: a single heatmap containing heatmap body, row/column names, titles, dendrograms and annotations.
19
+  \item \code{\link{HeatmapList-class}}: a list of heatmaps and annotations.
20 20
   \item \code{\link{HeatmapAnnotation-class}}: a list of row/column annotations.
21 21
 }
22 22
 
... ...
@@ -28,10 +28,14 @@ There are also several internal classes:
28 28
   \item \code{\link{AnnotationFunction-class}}: construct an annotation function which allows subsetting.
29 29
 }
30 30
 
31
-For plotting one single heatmap, please go to the documentation page of \code{\link{Heatmap}}.
32
-For plotting multiple heatmaps, please go to \code{\link{HeatmapList-class}}, \code{+.AdditiveUnit} and \code{\%v\%.AdditiveUnit}.
31
+Following two high-level functions take use of functionality of complex heatmaps:
33 32
 
34
-You can refer to the ComplexHeatmap Complete Reference for all the information of this package ().
33
+\itemize{
34
+  \item \code{\link{oncoPrint}}: oncoPrint plot which visualize genomic alterations in a set of genes.
35
+  \item \code{\link{densityHeatmap}}: use heatmaps to visualize density distributions.
36
+}
37
+
38
+The complete reference of ComplexHeatmap package is available at \url{http://jokergoo.github.io/ComplexHeatmap-reference/book.}
35 39
 }
36 40
 \examples{
37 41
 # There is no example
... ...
@@ -13,8 +13,8 @@ Subset a Heatmap
13 13
 \arguments{
14 14
 
15 15
   \item{x}{A \code{\link{Heatmap-class}} object.}
16
-  \item{i}{Row indices}
17
-  \item{j}{Column indices}
16
+  \item{i}{Row indices.}
17
+  \item{j}{Column indices.}
18 18
 
19 19
 }
20 20
 \details{
... ...
@@ -18,10 +18,23 @@ Subset a HeatmapList object
18 18
 
19 19
 }
20 20
 \details{
21
-If the heatmap list is horizontal, \code{i} is the real row indices and \code{j} corresponds to heatmap names and single annotation names.
21
+If the heatmap list is horizontal, \code{i} is the row indices and \code{j} corresponds to heatmap names and single annotation names.
22
+and if the heatlist is vertical, \code{i} corresponds to heatmap/annotation names and \code{j} is the column indices.
22 23
 }
23 24
 \examples{
24
-# There is no example
25
-NULL
25
+ht_list = Heatmap(matrix(rnorm(100), 10), name = "rnorm") +
26
+  rowAnnotation(foo = 1:10, bar = anno_points(10:1)) + 
27
+  Heatmap(matrix(runif(100), 10), name = "runif")
28
+summary(ht_list[1:5, ])
29
+summary(ht_list[1:5, 1])
30
+summary(ht_list[1:5, "rnorm"])
31
+summary(ht_list[1:5, c("rnorm", "foo")])
26 32
 
33
+ht_list = Heatmap(matrix(rnorm(100), 10), name = "rnorm") \%v\%
34
+  columnAnnotation(foo = 1:10, bar = anno_points(10:1)) \%v\%
35
+  Heatmap(matrix(runif(100), 10), name = "runif")
36
+summary(ht_list[, 1:5])
37
+summary(ht_list[1, 1:5])
38
+summary(ht_list["rnorm", 1:5])
39
+summary(ht_list[c("rnorm", "foo"), 1:5])
27 40
 }
... ...
@@ -2,15 +2,15 @@
2 2
 \docType{class}
3 3
 \alias{Heatmap-class}
4 4
 \title{
5
-Class for a single heatmap
5
+Class for a Single Heatmap
6 6
 }
7 7
 \description{
8
-Class for a single heatmap
8
+Class for a Single Heatmap
9 9
 }
10 10
 \details{
11 11
 The \code{\link{Heatmap-class}} is not responsible for heatmap legend and annotation legends. The \code{\link{draw,Heatmap-method}} method
12
-will construct a \code{\link{HeatmapList-class}} object which only contains one single heatmap
13
-and call \code{\link{draw,HeatmapList-method}} to make a complete heatmap.
12
+constructs a \code{\link{HeatmapList-class}} object which only contains one single heatmap
13
+and call \code{\link{draw,HeatmapList-method}} to make the complete heatmap.
14 14
 }
15 15
 \section{Methods}{
16 16
 The \code{\link{Heatmap-class}} provides following methods:
... ...
@@ -18,7 +18,7 @@ The \code{\link{Heatmap-class}} provides following methods:
18 18
 \itemize{
19 19
   \item \code{\link{Heatmap}}: constructor method.
20 20
   \item \code{\link{draw,Heatmap-method}}: draw a single heatmap.
21
-  \item \code{\link{add_heatmap,Heatmap-method}} append heatmaps and row annotations to a list of heatmaps.
21
+  \item \code{\link{add_heatmap,Heatmap-method}} append heatmaps and annotations to a list of heatmaps.
22 22
   \item \code{\link{row_order,HeatmapList-method}}: get order of rows
23 23
   \item \code{\link{column_order,HeatmapList-method}}: get order of columns
24 24
   \item \code{\link{row_dend,HeatmapList-method}}: get row dendrograms
... ...
@@ -89,93 +89,96 @@ Heatmap(matrix, col, name,
89 89
 }
90 90
 \arguments{
91 91
 
92
-  \item{matrix}{a matrix. Either numeric or character. If it is a simple vector, it will be converted to a one-column matrix.}
93
-  \item{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 \code{\link[circlize]{colorRamp2}}. If the matrix is continuous, the value can also be a vector of colors so that colors will be interpolated. Pass to \code{\link{ColorMapping}}.}
94
-  \item{name}{name of the heatmap. The name is used as the title of the heatmap legend.}
95
-  \item{na_col}{color for \code{NA} values.}
96
-  \item{rect_gp}{graphic parameters for drawing rectangles (for heatmap body).}
97
-  \item{color_space}{the color space in which colors are interpolated. Only used if \code{matrix} is numeric and  \code{col} is a vector of colors. Pass to \code{\link[circlize]{colorRamp2}}.}
98
-  \item{border}{whether draw border or the color of border.}
99
-  \item{cell_fun}{self-defined function to add graphics on each cell. Seven parameters will be passed into  this function: \code{i}, \code{j}, \code{x}, \code{y}, \code{width}, \code{height}, \code{fill} which are row index, column index in \code{matrix}, coordinate of the middle points in the heatmap body viewport, the width and height of the cell and the filled color. \code{x}, \code{y}, \code{width} and \code{height} are all \code{\link[grid]{unit}} objects.}
100
-  \item{layer_fun}{similar as \code{cell_fun}, but is vectorized. }
101
-  \item{row_title}{title on row.}
102
-  \item{row_title_side}{will the title be put on the left or right of the heatmap?}
103
-  \item{row_title_gp}{graphic parameters for drawing text.}
104
-  \item{row_title_rot}{rotation of row titles. Only 0, 90, 270 are allowed to set.}
105
-  \item{column_title}{title on column.}
106
-  \item{column_title_side}{will the title be put on the top or bottom of the heatmap?}
107
-  \item{column_title_gp}{graphic parameters for drawing text.}
108
-  \item{column_title_rot}{rotation of column titles. Only 0, 90, 270 are allowed to set.}
109
-  \item{cluster_rows}{If the value is a logical, it means whether make cluster on rows. The value can also be a \code{\link[stats]{hclust}} or a \code{\link[stats]{dendrogram}} that already contains clustering information. This means you can use any type of clustering methods and render the \code{\link[stats]{dendrogram}} object with self-defined graphic settings.}
110
-  \item{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 \code{\link[stats]{dist}} object. If the function has two arguments, the input arguments are two vectors and the function calculates distance between these two vectors.}
111
-  \item{clustering_method_rows}{method to make cluster, pass to \code{\link[stats]{hclust}}.}
112
-  \item{row_dend_side}{should the row cluster be put on the left or right of the heatmap?}
113
-  \item{row_dend_width}{width of the row cluster, should be a \code{\link[grid]{unit}} object.}
114
-  \item{show_row_dend}{whether show row clusters. }
115
-  \item{row_dend_gp}{graphics parameters for drawing lines. If users already provide a \code{\link[stats]{dendrogram}} object with edges rendered, this argument will be ignored.}
116
-  \item{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}
117
-  \item{cluster_columns}{whether make cluster on columns. Same settings as \code{cluster_rows}.}
118
-  \item{clustering_distance_columns}{same setting as \code{clustering_distance_rows}.}
119
-  \item{clustering_method_columns}{method to make cluster, pass to \code{\link[stats]{hclust}}.}
120
-  \item{column_dend_side}{should the column cluster be put on the top or bottom of the heatmap?}
92
+  \item{matrix}{A matrix. Either numeric or character. If it is a simple vector, it will be converted to a one-column matrix.}
93
+  \item{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 \code{\link[circlize]{colorRamp2}}). If the matrix is continuous, the value can also be a vector of colors so that colors can be interpolated. Pass to \code{\link{ColorMapping}}. For more details and examples, please refer to \url{https://jokergoo.github.io/ComplexHeatmap-reference/book/a-single-heatmap.html#colors} .}
94
+  \item{name}{Name of the heatmap. By default the heatmap name is used as the title of the heatmap legend.}
95
+  \item{na_col}{Color for \code{NA} values.}
96
+  \item{rect_gp}{Graphic parameters for drawing rectangles (for heatmap body). The value should be specified by \code{\link[grid]{gpar}} and \code{fill} parameter is ignored.}
97
+  \item{color_space}{The color space in which colors are interpolated. Only used if \code{matrix} is numeric and  \code{col} is a vector of colors. Pass to \code{\link[circlize]{colorRamp2}}.}
98
+  \item{border}{Whether draw border. The value can be logical or a string of color.}
99
+  \item{cell_fun}{Self-defined function to add graphics on each cell. Seven parameters will be passed into  this function: \code{j}, \code{i}, \code{x}, \code{y}, \code{width}, \code{height}, \code{fill} which are column index, row index in \code{matrix}, coordinate of the cell, the width and height of the cell and the filled color. \code{x}, \code{y}, \code{width} and \code{height} are all \code{\link[grid]{unit}} objects.}
100
+  \item{layer_fun}{Similar as \code{cell_fun}, but is vectorized. Check \url{https://jokergoo.github.io/ComplexHeatmap-reference/book/a-single-heatmap.html#customize-the-heatmap-body} .}
101
+  \item{row_title}{Title on the row.}
102
+  \item{row_title_side}{Will the title be put on the left or right of the heatmap?}
103
+  \item{row_title_gp}{Graphic parameters for row title.}
104
+  \item{row_title_rot}{Rotation of row title. Only 0, 90, 270 are allowed to set.}
105
+  \item{column_title}{Title on the column.}
106
+  \item{column_title_side}{Will the title be put on the top or bottom of the heatmap?}
107
+  \item{column_title_gp}{Graphic parameters for column title.}
108
+  \item{column_title_rot}{Rotation of column titles. Only 0, 90, 270 are allowed to set.}
109
+  \item{cluster_rows}{If the value is a logical, it controls whether to make cluster on rows. The value can also be a \code{\link[stats]{hclust}} or a \code{\link[stats]{dendrogram}} which already contains clustering. Check \url{https://jokergoo.github.io/ComplexHeatmap-reference/book/a-single-heatmap.html#clustering} .}
110
+  \item{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 \code{\link[stats]{dist}} object. If the function has two arguments, the input arguments are two vectors and the function calculates distance between these two vectors.}
111
+  \item{clustering_method_rows}{Method to perform hierarchical clustering, pass to \code{\link[stats]{hclust}}.}
112
+  \item{row_dend_side}{Should the row dendrogram be put on the left or right of the heatmap?}
113
+  \item{row_dend_width}{Width of the row dendrogram, should be a \code{\link[grid]{unit}} object.}
114
+  \item{show_row_dend}{Whether show row dendrogram?}
115
+  \item{row_dend_gp}{Graphic parameters for the dendrogram segments. If users already provide a \code{\link[stats]{dendrogram}} object with edges rendered, this argument will be ignored.}
116
+  \item{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 \code{\link[stats]{reorder.dendrogram}}.}
117
+  \item{cluster_columns}{Whether make cluster on columns? Same settings as \code{cluster_rows}.}
118
+  \item{clustering_distance_columns}{Same setting as \code{clustering_distance_rows}.}
119
+  \item{clustering_method_columns}{Method to perform hierarchical clustering, pass to \code{\link[stats]{hclust}}.}
120
+  \item{column_dend_side}{Should the column dendrogram be put on the top or bottom of the heatmap?}
121 121
   \item{column_dend_height}{height of the column cluster, should be a \code{\link[grid]{unit}} object.}
122
-  \item{show_column_dend}{whether show column clusters.}
123
-  \item{column_dend_gp}{graphic parameters for drawling lines. Same settings as \code{row_dend_gp}.}
124
-  \item{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}
125
-  \item{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}
126
-  \item{column_order}{order of column. It makes it easy to adjust column order for both matrix and column annotations.}
127
-  \item{row_labels}{row labels}
128
-  \item{row_names_side}{should the row names be put on the left or right of the heatmap?}
129