man/Heatmap.rd
d1da987e
 \name{Heatmap}
 \alias{Heatmap}
 \title{
6f1307c6
 Constructor method for Heatmap class
d1da987e
 }
 \description{
6f1307c6
 Constructor method for Heatmap class
d1da987e
 }
 \usage{
12e85497
 Heatmap(matrix, col, name,
     na_col = "grey",
     color_space = "LAB",
     rect_gp = gpar(col = NA),
ad35494a
     border = NA,
9487d939
     cell_fun = NULL,
ad35494a
     layer_fun = NULL,
     
12e85497
     row_title = character(0),
     row_title_side = c("left", "right"),
b08d7ba4
     row_title_gp = gpar(fontsize = 14),
     row_title_rot = switch(row_title_side[1], "left" = 90, "right" = 270),
12e85497
     column_title = character(0),
     column_title_side = c("top", "bottom"),
     column_title_gp = gpar(fontsize = 14),
     column_title_rot = 0,
ad35494a
     
12e85497
     cluster_rows = TRUE,
5e6b381e
     cluster_row_slices = TRUE,
12e85497
     clustering_distance_rows = "euclidean",
     clustering_method_rows = "complete",
     row_dend_side = c("left", "right"),
     row_dend_width = unit(10, "mm"),
     show_row_dend = TRUE,
fcefb322
     row_dend_reorder = is.logical(cluster_rows) || is.function(cluster_rows),
12e85497
     row_dend_gp = gpar(),
     cluster_columns = TRUE,
5e6b381e
     cluster_column_slices = TRUE,
12e85497
     clustering_distance_columns = "euclidean",
     clustering_method_columns = "complete",
     column_dend_side = c("top", "bottom"),
     column_dend_height = unit(10, "mm"),
     show_column_dend = TRUE,
     column_dend_gp = gpar(),
fcefb322
     column_dend_reorder = is.logical(cluster_columns) || is.function(cluster_columns),
ad35494a
     
12e85497
     row_order = NULL,
     column_order = NULL,
ad35494a
     
     row_labels = rownames(matrix),
12e85497
     row_names_side = c("right", "left"),
     show_row_names = TRUE,
ad35494a
     row_names_max_width = unit(6, "cm"),
12e85497
     row_names_gp = gpar(fontsize = 12),
ad35494a
     row_names_rot = 0,
9c4d56c4
     row_names_centered = FALSE,
ad35494a
     column_labels = colnames(matrix),
d1da987e
     column_names_side = c("bottom", "top"),
12e85497
     show_column_names = TRUE,
ad35494a
     column_names_max_height = unit(6, "cm"),
d1da987e
     column_names_gp = gpar(fontsize = 12),
ad35494a
     column_names_rot = 90,
9c4d56c4
     column_names_centered = FALSE,
ad35494a
     
     top_annotation = NULL,
     bottom_annotation = NULL,
     left_annotation = NULL,
     right_annotation = NULL,
     
12e85497
     km = 1,
     split = NULL,
ad35494a
     row_km = km,
9c4d56c4
     row_km_repeats = 1,
ad35494a
     row_split = split,
     column_km = 1,
9c4d56c4
     column_km_repeats = 1,
ad35494a
     column_split = NULL,
1a56796e
     gap = unit(1, "mm"),
     row_gap = unit(1, "mm"),
     column_gap = unit(1, "mm"),
fcefb322
     show_parent_dend_line = ht_opt$show_parent_dend_line,
ad35494a
     
1a56796e
     heatmap_width = unit(1, "npc"),
     width = NULL,
     heatmap_height = unit(1, "npc"),
     height = NULL,
ad35494a
     
12e85497
     show_heatmap_legend = TRUE,
0623db7b
     heatmap_legend_param = list(title = name),
ad35494a
     
65fecf1c
     use_raster = (nrow(matrix) > 2000 && ncol(matrix) > 1) || (ncol(matrix) > 2000 && nrow(matrix) > 1),
3034fb6f
     raster_device = c("png", "jpeg", "tiff", "CairoPNG", "CairoJPEG", "CairoTIFF"),
6a4c2b4c
     raster_quality = 2,
ad35494a
     raster_device_param = list(),
5e6b381e
     raster_resize = FALSE,
ad35494a
     
     post_fun = NULL)
ba8a5070
 }
d1da987e
 \arguments{
 
3c40a7c1
   \item{matrix}{A matrix. Either numeric or character. If it is a simple vector, it will be converted to a one-column matrix.}
   \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} .}
   \item{name}{Name of the heatmap. By default the heatmap name is used as the title of the heatmap legend.}
   \item{na_col}{Color for \code{NA} values.}
   \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.}
   \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}}.}
   \item{border}{Whether draw border. The value can be logical or a string of color.}
   \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.}
   \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} .}
   \item{row_title}{Title on the row.}
   \item{row_title_side}{Will the title be put on the left or right of the heatmap?}
   \item{row_title_gp}{Graphic parameters for row title.}
   \item{row_title_rot}{Rotation of row title. Only 0, 90, 270 are allowed to set.}
   \item{column_title}{Title on the column.}
   \item{column_title_side}{Will the title be put on the top or bottom of the heatmap?}
   \item{column_title_gp}{Graphic parameters for column title.}
   \item{column_title_rot}{Rotation of column titles. Only 0, 90, 270 are allowed to set.}
   \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} .}
5e6b381e
   \item{cluster_row_slices}{If rows are split into slices, whether perform clustering on the slice means?}
3c40a7c1
   \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.}
   \item{clustering_method_rows}{Method to perform hierarchical clustering, pass to \code{\link[stats]{hclust}}.}
   \item{row_dend_side}{Should the row dendrogram be put on the left or right of the heatmap?}
   \item{row_dend_width}{Width of the row dendrogram, should be a \code{\link[grid]{unit}} object.}
   \item{show_row_dend}{Whether show row dendrogram?}
   \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.}
   \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}}.}
   \item{cluster_columns}{Whether make cluster on columns? Same settings as \code{cluster_rows}.}
5e6b381e
   \item{cluster_column_slices}{If columns are split into slices, whether perform clustering on the slice means?}
3c40a7c1
   \item{clustering_distance_columns}{Same setting as \code{clustering_distance_rows}.}
   \item{clustering_method_columns}{Method to perform hierarchical clustering, pass to \code{\link[stats]{hclust}}.}
   \item{column_dend_side}{Should the column dendrogram be put on the top or bottom of the heatmap?}
12e85497
   \item{column_dend_height}{height of the column cluster, should be a \code{\link[grid]{unit}} object.}
3c40a7c1
   \item{show_column_dend}{Whether show column dendrogram?}
   \item{column_dend_gp}{Graphic parameters for dendrogram segments. Same settings as \code{row_dend_gp}.}
   \item{column_dend_reorder}{Apply reordering on column dendrograms. Same settings as \code{row_dend_reorder}.}
   \item{row_order}{Order of rows. Manually setting row order turns off clustering.}
   \item{column_order}{Order of column.}
   \item{row_labels}{Optional row labels which are put as row names in the heatmap.}
   \item{row_names_side}{Should the row names be put on the left or right of the heatmap?}
   \item{show_row_names}{Whether show row names.}
   \item{row_names_max_width}{Maximum width of row names viewport.}
   \item{row_names_gp}{Graphic parameters for row names.}
   \item{row_names_rot}{Rotation of row names.}
9c4d56c4
   \item{row_names_centered}{Should row names put centered?}
3c40a7c1
   \item{column_labels}{Optional column labels which are put as column names in the heatmap.}
   \item{column_names_side}{Should the column names be put on the top or bottom of the heatmap?}
   \item{column_names_max_height}{Maximum height of column names viewport.}
   \item{show_column_names}{Whether show column names.}
   \item{column_names_gp}{Graphic parameters for drawing text.}
   \item{column_names_rot}{Rotation of column names.}
9c4d56c4
   \item{column_names_centered}{Should column names put centered?}
3c40a7c1
   \item{top_annotation}{A \code{\link{HeatmapAnnotation}} object.}
   \item{bottom_annotation}{A \code{\link{HeatmapAnnotation}} object.}
   \item{left_annotation}{It should be specified by \code{\link{rowAnnotation}}.}
   \item{right_annotation}{it should be specified by \code{\link{rowAnnotation}}.}
   \item{km}{Apply k-means clustering on rows. If the value is larger than 1, the heatmap will be split by rows according to the k-means clustering. For each row slice, hierarchical clustering is still applied with parameters above.}
   \item{split}{A vector or a data frame by which the rows are split. But if \code{cluster_rows} is a clustering object, \code{split} can be a single number indicating to split the dendrogram by \code{\link[stats]{cutree}}.}
   \item{row_km}{Same as \code{km}.}
edfce525
   \item{row_km_repeats}{Number of k-means runs to get a consensus k-means clustering. Note if \code{row_km_repeats} is set to more than one, the final number of groups might be smaller than \code{row_km}, but this might means the original \code{row_km} is not a good choice.}
3c40a7c1
   \item{row_split}{Same as \code{split}.}
   \item{column_km}{K-means clustering on columns.}
edfce525
   \item{column_km_repeats}{Number of k-means runs to get a consensus k-means clustering. Similar as \code{row_km_repeats}.}
3c40a7c1
   \item{column_split}{Split on columns. For heatmap splitting, please refer to \url{https://jokergoo.github.io/ComplexHeatmap-reference/book/a-single-heatmap.html#heatmap-split} .}
   \item{gap}{Gap between row slices if the heatmap is split by rows. The value should be a \code{\link[grid]{unit}} object.}
   \item{row_gap}{Same as \code{gap}.}
   \item{column_gap}{Gap between column slices.}
fcefb322
   \item{show_parent_dend_line}{When heatmap is split, whether to add a dashed line to mark parent dendrogram and children dendrograms?}
3c40a7c1
   \item{width}{Width of the heatmap body.}
   \item{height}{Height of the heatmap body.}
   \item{heatmap_width}{Width of the whole heatmap (including heatmap components)}
   \item{heatmap_height}{Height of the whole heatmap (including heatmap components). Check \url{https://jokergoo.github.io/ComplexHeatmap-reference/book/a-single-heatmap.html#size-of-the-heatmap} .}
   \item{show_heatmap_legend}{Whether show heatmap legend?}
   \item{heatmap_legend_param}{A list contains parameters for the heatmap legends. See \code{\link{color_mapping_legend,ColorMapping-method}} for all available parameters.}
   \item{use_raster}{Whether render the heatmap body as a raster image. It helps to reduce file size when the matrix is huge. Note if \code{cell_fun} is set, \code{use_raster} is enforced to be \code{FALSE}.}
   \item{raster_device}{Graphic device which is used to generate the raster image.}
   \item{raster_quality}{A value set to larger than 1 will improve the quality of the raster image.}
   \item{raster_device_param}{A list of further parameters for the selected graphic device. For raster image support, please check \url{https://jokergoo.github.io/ComplexHeatmap-reference/book/a-single-heatmap.html#heatmap-as-raster-image} .}
5e6b381e
   \item{raster_resize}{Whether resize the matrix to let the dimension of the matrix the same as the dimension of the raster image?}
3c40a7c1
   \item{post_fun}{A function which will be executed after the heatmap list is drawn.}
ba8a5070
 
d1da987e
 }
 \details{
3c40a7c1
 The initialization function only applies parameter checking and fill values to the slots with some validation.
7ab3fd24
 
3c40a7c1
 Following methods can be applied to the \code{\link{Heatmap-class}} object:
7ab3fd24
 
d1da987e
 \itemize{
   \item \code{\link{show,Heatmap-method}}: draw a single heatmap with default parameters
   \item \code{\link{draw,Heatmap-method}}: draw a single heatmap.
3c40a7c1
   \item \code{+} or \code{\link[=pct_v_pct]{\%v\%}} append heatmaps and annotations to a list of heatmaps.
d1da987e
 }
 
6f1307c6
 The constructor function pretends to be a high-level graphic function because the \code{show} method
 of the \code{\link{Heatmap-class}} object actually plots the graphics.
d1da987e
 }
3c40a7c1
 \seealso{
 \url{https://jokergoo.github.io/ComplexHeatmap-reference/book/a-single-heatmap.html}
 }
d1da987e
 \value{
6f1307c6
 A \code{\link{Heatmap-class}} object.
d1da987e
 }
 \author{
6f1307c6
 Zuguang Gu <z.gu@dkfz.de>
d1da987e
 }
 \examples{
ad35494a
 # There is no example
 NULL
69345c7d
 
f597719b
 }