\name{Heatmap}
 \alias{Heatmap}
 \title{

 Constructor method for Heatmap class

 }
 \description{

 Constructor method for Heatmap class

 }
 \usage{

 Heatmap(matrix, col, name,
     na_col = "grey",
     color_space = "LAB",
     rect_gp = gpar(col = NA),

     border = NA,

     cell_fun = NULL,

     layer_fun = NULL,
     

     row_title = character(0),
     row_title_side = c("left", "right"),

     row_title_gp = gpar(fontsize = 14),
     row_title_rot = switch(row_title_side[1], "left" = 90, "right" = 270),

     column_title = character(0),
     column_title_side = c("top", "bottom"),
     column_title_gp = gpar(fontsize = 14),
     column_title_rot = 0,

     cluster_rows = TRUE,

     cluster_row_slices = TRUE,

     clustering_distance_rows = "euclidean",
     clustering_method_rows = "complete",
     row_dend_side = c("left", "right"),
     row_dend_width = unit(10, "mm"),
     show_row_dend = TRUE,

     row_dend_reorder = is.logical(cluster_rows) || is.function(cluster_rows),

     row_dend_gp = gpar(),
     cluster_columns = TRUE,

     cluster_column_slices = TRUE,

     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(),

     column_dend_reorder = is.logical(cluster_columns) || is.function(cluster_columns),

     row_order = NULL,
     column_order = NULL,

     
     row_labels = rownames(matrix),

     row_names_side = c("right", "left"),
     show_row_names = TRUE,

     row_names_max_width = unit(6, "cm"),

     row_names_gp = gpar(fontsize = 12),

     row_names_rot = 0,

     row_names_centered = FALSE,

     column_labels = colnames(matrix),

     column_names_side = c("bottom", "top"),

     show_column_names = TRUE,

     column_names_max_height = unit(6, "cm"),

     column_names_gp = gpar(fontsize = 12),

     column_names_rot = 90,

     column_names_centered = FALSE,

     
     top_annotation = NULL,
     bottom_annotation = NULL,
     left_annotation = NULL,
     right_annotation = NULL,
     

     km = 1,
     split = NULL,

     row_km = km,

     row_km_repeats = 1,

     row_split = split,
     column_km = 1,

     column_km_repeats = 1,

     column_split = NULL,

     gap = unit(1, "mm"),
     row_gap = unit(1, "mm"),
     column_gap = unit(1, "mm"),

     show_parent_dend_line = ht_opt$show_parent_dend_line,

     heatmap_width = unit(1, "npc"),
     width = NULL,
     heatmap_height = unit(1, "npc"),
     height = NULL,

     show_heatmap_legend = TRUE,

     heatmap_legend_param = list(title = name),

     use_raster = (nrow(matrix) > 2000 && ncol(matrix) > 1) || (ncol(matrix) > 2000 && nrow(matrix) > 1),

     raster_device = c("png", "jpeg", "tiff", "CairoPNG", "CairoJPEG", "CairoTIFF"),

     raster_quality = 2,

     raster_device_param = list(),

     raster_resize = FALSE,

     
     post_fun = NULL)

 }

 \arguments{
 

   \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} .}

   \item{cluster_row_slices}{If rows are split into slices, whether perform clustering on the slice means?}

   \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}.}

   \item{cluster_column_slices}{If columns are split into slices, whether perform clustering on the slice means?}

   \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?}

   \item{column_dend_height}{height of the column cluster, should be a \code{\link[grid]{unit}} object.}

   \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.}

   \item{row_names_centered}{Should row names put centered?}

   \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.}

   \item{column_names_centered}{Should column names put centered?}

   \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}.}

   \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.}

   \item{row_split}{Same as \code{split}.}
   \item{column_km}{K-means clustering on columns.}

   \item{column_km_repeats}{Number of k-means runs to get a consensus k-means clustering. Similar as \code{row_km_repeats}.}

   \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.}

   \item{show_parent_dend_line}{When heatmap is split, whether to add a dashed line to mark parent dendrogram and children dendrograms?}

   \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} .}

   \item{raster_resize}{Whether resize the matrix to let the dimension of the matrix the same as the dimension of the raster image?}

   \item{post_fun}{A function which will be executed after the heatmap list is drawn.}

 }
 \details{

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

 Following methods can be applied to the \code{\link{Heatmap-class}} object:

 \itemize{
   \item \code{\link{show,Heatmap-method}}: draw a single heatmap with default parameters
   \item \code{\link{draw,Heatmap-method}}: draw a single heatmap.

   \item \code{+} or \code{\link[=pct_v_pct]{\%v\%}} append heatmaps and annotations to a list of heatmaps.

 }
 

 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.

 }

 \seealso{
 \url{https://jokergoo.github.io/ComplexHeatmap-reference/book/a-single-heatmap.html}
 }

 \value{

 A \code{\link{Heatmap-class}} object.

 }
 \author{

 Zuguang Gu <z.gu@dkfz.de>

 }
 \examples{

 # There is no example
 NULL

 }