% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/heatmap.R
\name{Heatmap}
\alias{Heatmap}
\title{Heatmap}
\usage{
Heatmap(
  data,
  values_by = NULL,
  values_fill = NA,
  name = NULL,
  in_form = c("auto", "matrix", "wide-columns", "wide-rows", "long"),
  split_by = NULL,
  split_by_sep = "_",
  rows_by = NULL,
  rows_by_sep = "_",
  rows_split_by = NULL,
  rows_split_by_sep = "_",
  columns_by = NULL,
  columns_by_sep = "_",
  columns_split_by = NULL,
  columns_split_by_sep = "_",
  rows_data = NULL,
  columns_data = NULL,
  keep_na = FALSE,
  keep_empty = FALSE,
  rows_orderby = NULL,
  columns_orderby = NULL,
  columns_name = NULL,
  columns_split_name = NULL,
  rows_name = NULL,
  rows_split_name = NULL,
  palette = "RdBu",
  palcolor = NULL,
  pie_size_name = "size",
  pie_size = NULL,
  pie_values = "length",
  pie_name = NULL,
  pie_group_by = NULL,
  pie_group_by_sep = "_",
  pie_palette = "Spectral",
  pie_palcolor = NULL,
  bars_sample = 100,
  label = identity,
  label_size = 10,
  label_color = "black",
  label_name = "label",
  mark = identity,
  mark_color = "black",
  mark_size = 1,
  mark_name = "mark",
  violin_fill = NULL,
  boxplot_fill = NULL,
  dot_size = 8,
  dot_size_name = "size",
  legend_items = NULL,
  legend_discrete = FALSE,
  legend.position = "right",
  legend.direction = "vertical",
  lower_quantile = 0,
  upper_quantile = 0.99,
  lower_cutoff = NULL,
  upper_cutoff = NULL,
  add_bg = FALSE,
  bg_alpha = 0.5,
  add_reticle = FALSE,
  reticle_color = "grey",
  cluster_columns = NULL,
  cluster_rows = NULL,
  show_row_names = NULL,
  show_column_names = NULL,
  border = TRUE,
  title = NULL,
  column_title = character(0),
  row_title = character(0),
  na_col = "grey85",
  row_names_side = "right",
  column_names_side = "bottom",
  column_annotation = NULL,
  column_annotation_side = "top",
  column_annotation_palette = "Paired",
  column_annotation_palcolor = NULL,
  column_annotation_type = "auto",
  column_annotation_params = list(),
  column_annotation_agg = NULL,
  row_annotation = NULL,
  row_annotation_side = "left",
  row_annotation_palette = "Paired",
  row_annotation_palcolor = NULL,
  row_annotation_type = "auto",
  row_annotation_params = list(),
  row_annotation_agg = NULL,
  flip = FALSE,
  alpha = 1,
  seed = 8525,
  padding = 15,
  base_size = 1,
  aspect.ratio = NULL,
  draw_opts = list(),
  layer_fun_callback = NULL,
  cell_type = c("tile", "bars", "label", "mark", "label+mark", "mark+label", "dot",
    "violin", "boxplot", "pie"),
  cell_agg = NULL,
  combine = TRUE,
  nrow = NULL,
  ncol = NULL,
  byrow = TRUE,
  axes = NULL,
  axis_titles = axes,
  guides = NULL,
  design = NULL,
  ...
)
}
\arguments{
\item{data}{A data frame or matrix containing the data to be plotted.
Based on the \code{in_form}, the data can have the following formats:
\itemize{
\item \code{matrix}: A matrix with rows and columns directly representing the heatmap.
\item \code{long}: A data frame in long format with columns for values, rows, and columns.
\item \code{wide-rows}: A data frame in wide format with columns for heatmap rows and values,
and a single column for heatmap columns.
\item \code{wide-columns}: A data frame in wide format with columns for heatmap columns and values,
and a single column for heatmap rows.
\item \code{auto}: Automatically inferred from the data format.
When \code{data} is a matrix, \code{in_form} is set to \code{"matrix"}. When \code{columns_by} has more than one column,
\code{in_form} is set to \code{"wide-columns"}. When \code{rows_by} has more than one column,
\code{in_form} is set to \code{"wide-rows"}. Otherwise, it is set to \code{"long"}.
}}

\item{values_by}{A character of column name in \code{data} that contains the values to be plotted.
This is required when \code{in_form} is \code{"long"}. For other formats, the values are pivoted into a column named by \code{values_by}.}

\item{values_fill}{A value to fill in the missing values in the heatmap.
When there is missing value in the data, the cluster_rows and cluster_columns will fail.}

\item{name}{A character string to name the heatmap (will be used to rename \code{values_by}).}

\item{in_form}{The format of the data. Can be one of \code{"matrix"}, \code{"long"}, \code{"wide-rows"}, \code{"wide-columns"}, or \code{"auto"}.
Defaults to \code{"auto"}.}

\item{split_by}{A character of column name in \code{data} that contains the split information to split into multiple heatmaps.
This is used to create a list of heatmaps, one for each level of the split.
Defaults to \code{NULL}, meaning no split.}

\item{split_by_sep}{A character string to concat multiple columns in \code{split_by}.}

\item{rows_by}{A vector of column names in \code{data} that contains the row information.
This is used to create the rows of the heatmap.
When \code{in_form} is \code{"long"} or \code{"wide-columns"}, this is requied, and multiple columns can be specified,
which will be concatenated by \code{rows_by_sep} into a single column.}

\item{rows_by_sep}{A character string to concat multiple columns in \code{rows_by}.}

\item{rows_split_by}{A character of column name in \code{data} that contains the split information for rows.}

\item{rows_split_by_sep}{A character string to concat multiple columns in \code{rows_split_by}.}

\item{columns_by}{A vector of column names in \code{data} that contains the column information.
This is used to create the columns of the heatmap.
When \code{in_form} is \code{"long"} or \code{"wide-rows"}, this is required, and multiple columns can be specified,
which will be concatenated by \code{columns_by_sep} into a single column.}

\item{columns_by_sep}{A character string to concat multiple columns in \code{columns_by}.}

\item{columns_split_by}{A character of column name in \code{data} that contains the split information for columns.}

\item{columns_split_by_sep}{A character string to concat multiple columns in \code{columns_split_by}.}

\item{rows_data}{A data frame containing additional data for rows, which can be used to add annotations to the heatmap.
It will be joined to the main data by \code{rows_by} and \code{split_by} if \code{split_by} exists in \code{rows_data}.
This is useful for adding additional information to the rows of the heatmap.}

\item{columns_data}{A data frame containing additional data for columns, which can be used to add annotations to the heatmap.
It will be joined to the main data by \code{columns_by} and \code{split_by} if \code{split_by} exists in \code{columns_data}.
This is useful for adding additional information to the columns of the heatmap.}

\item{keep_na}{Whether we should keep NA groups in rows, columns and split_by variables. Default is FALSE.
FALSE to remove NA groups; TRUE to keep NA groups.
A vector of column names can also be provided to specify which columns to keep NA groups.
Note that the record will be removed if any of the grouping columns has NA and is not specified to keep NA.}

\item{keep_empty}{One of FALSE, TRUE and "level". It can also take a named list to specify
different behavior for different columns. Without a named list, the behavior applies to the
categorical/character columns used on the plot, for example, the \code{x}, \code{group_by}, \code{fill_by}, etc.
\itemize{
\item{\code{FALSE} (default): Drop empty factor levels from the data before plotting.}
\item{\code{TRUE}: Keep empty factor levels and show them as a separate category in the plot.}
\item{\code{"level"}: Keep empty factor levels, but do not show them in the plot.
But they will be assigned colors from the palette to maintain consistency across multiple plots.
Alias: \code{levels}}
}}

\item{rows_orderby}{A expression (in character) to specify how to order rows. It will be evaluated in the context of the data frame used for rows (after grouping by rows_split_by and rows_by). The expression should return a vector of the same length as the number of rows in the data frame. The default is NULL, which means no specific ordering.
Can't be used with cluster_rows = TRUE.
This is applied before renaming rows_by to rows_name.}

\item{columns_orderby}{A expression (in character) to specify how to order columns. It will be evaluated in the context of the data frame used for columns (after grouping by columns
split_by and columns_by). The expression should return a vector of the same length as the number of rows in the data frame. The default is NULL, which means no specific ordering.
Can't be used with cluster_columns = TRUE.
This is applied before renaming columns_by to columns_name.}

\item{columns_name}{A character string to rename the column created by \code{columns_by}, which will be reflected in the name of the annotation or legend.}

\item{columns_split_name}{A character string to rename the column created by \code{columns_split_by}, which will be reflected in the name of the annotation or legend.}

\item{rows_name}{A character string to rename the column created by \code{rows_by}, which will be reflected in the name of the annotation or legend.}

\item{rows_split_name}{A character string to rename the column created by \code{rows_split_by}, which will be reflected in the name of the annotation or legend.}

\item{palette}{A character string specifying the palette of the heatmap cells.}

\item{palcolor}{A character vector of colors to override the palette of the heatmap cells.}

\item{pie_size_name}{A character string specifying the name of the legend for the pie size.}

\item{pie_size}{A numeric value or a function specifying the size of the pie chart.
If it is a function, the function should take \code{count} as the argument and return the size.}

\item{pie_values}{A function or character that can be converted to a function by \code{\link[=match.arg]{match.arg()}}
to calculate the values for the pie chart. Default is "length".
The function should take a vector of values as the argument and return a single value, for each
group in \code{pie_group_by}.}

\item{pie_name}{A character string to rename the column created by \code{pie_group_by}, which will be reflected in the name of the annotation or legend.}

\item{pie_group_by}{A character of column name in \code{data} that contains the group information for pie charts.
This is used to create pie charts in the heatmap when \code{cell_type} is \code{"pie"}.}

\item{pie_group_by_sep}{A character string to concat multiple columns in \code{pie_group_by}.}

\item{pie_palette}{A character string specifying the palette of the pie chart.}

\item{pie_palcolor}{A character vector of colors to override the palette of the pie chart.}

\item{bars_sample}{An integer specifying the number of samples to draw the bars.}

\item{label}{A function to calculate the labels for the heatmap cells.
It can take either 1, 3, or 5 arguments. The first argument is the aggregated value for a single cell.
If it takes 3 arguments, the second and third arguments are the row and column indices of that cell.
If it takes 5 arguments, the second and third arguments are the row and column indices,
and the fourth and fifth arguments are the row and column names.
The function should return one of:
\itemize{
\item \code{NA} — no label is drawn for this cell.
\item A character scalar — used as the label text; \code{label_size} and \code{label_color} are used for size and color.
\item A named list with any of the following fields:
\itemize{
\item \code{label}: character scalar for the label text.
\item \code{size}: numeric pt size (overrides \code{label_size}).
\item \code{color}: character color string (overrides \code{label_color}).
\item \code{legend}: character string used as the legend entry for this cell's color/label combination.
\item \code{order}: integer controlling the position of this legend entry — smaller values appear first (top) in the legend.
Entries without an \code{order} are appended after all explicitly ordered entries.
For the indices, if you have the same dimension of data (same order of rows and columns) as the heatmap, you need to use \code{ComplexHeatmap::pindex()} to get the correct values.
}
}}

\item{label_size}{A numeric value specifying the default size (pt) of the labels when \code{cell_type = "label"}.
Used as fallback when the \code{label} function does not return a \code{size} field.}

\item{label_color}{A character string specifying the default color of the labels when \code{cell_type = "label"}.
Used as fallback when the \code{label} function does not return a \code{color} field. Default is \code{"black"}.}

\item{label_name}{A character string specifying the title of the label legend. Default is \code{"label"}.
The legend is shown automatically when the \code{label} function returns a list with a \code{legend} field for at least
one cell — no extra configuration needed. Set \code{legend.position = "none"} to suppress all legends.}

\item{mark}{A function to calculate the marks drawn on top of heatmap cells when \code{cell_type = "mark"}.
Same dispatch rules as \code{label} (1, 3, or 5 arguments).
The function should return one of:
\itemize{
\item \code{NA} — no mark is drawn for this cell.
\item A character scalar — the mark type string; \code{mark_color} and \code{mark_size} are used for appearance.
\item A named list with any of the following fields:
\itemize{
\item \code{mark} (or first unnamed element): character scalar, the mark type string.
\item \code{size}: numeric stroke width (lwd), overrides \code{mark_size}.
\item \code{color}: character color string, overrides \code{mark_color}.
\item \code{legend}: character string used as the legend entry key.
\item \code{order}: integer controlling legend entry position (smaller = higher).
\strong{Supported mark types:}
}
\item Primitives: \code{-} (h-line), \code{|} (v-line), \code{+} (cross), \code{/} (l-diag), \verb{\\} (r-diag),
\code{x} (both diags), \code{o} (circle with gap), \verb{()} (circle touching edge), \verb{<>} (diamond).
\item With rectangular border: \verb{[]}, \verb{[-]}, \verb{[|]}, \verb{[+]}, \verb{[/]}, \verb{[\]}, \verb{[x]}, \verb{[o]}, \verb{[()]}, \verb{[<>]}.
\item With full circle: \verb{(-)}, \verb{(|)}, \verb{(+)}, \verb{(/)}, \verb{(\\)}, \code{(x)}, \code{(o)}, \verb{(<>)}.
\item With diamond: \verb{<->}, \verb{<|>}, \verb{<+>}, \verb{</>}, \verb{<\\>}, \verb{<x>}, \verb{<o>}.
\item Octagon (standalone or wrapper): \code{{}}, \verb{\{-\}}, \verb{\{|\}}, \verb{\{+\}}, \verb{\{/\}}, \verb{\{\\\\\}}, \code{{x}}, \code{{o}}, \verb{\{()\}}, \verb{\{<>\}}.
\item Combinations: e.g. \verb{[(|)]}, \verb{[(-)]}, \verb{[(+)]}, \verb{[(/)]}, \verb{[(\\)]}, \verb{[(x)]}, \verb{[(o)]}, \verb{[(<>)]}.
}

[]: R:\%5C
[x]: R:x
[o]: R:o
[()]: R:()
[<>]: R:\%3C\%3E
[(|)]: R:(\%7C)
[(-)]: R:(-)
[(+)]: R:(+)
[(/)]: R:(/)
[(\)]: R:(\%5C\%5C)
[(x)]: R:(x)
[(o)]: R:(o)
[(<>)]: R:(\%3C\%3E)}

\item{mark_color}{A character string specifying the default color of the marks when \code{cell_type = "mark"}.
Used as fallback when the \code{mark} function does not return a \code{color} field. Default is \code{"black"}.}

\item{mark_size}{A numeric value specifying the default stroke width (lwd) of the marks when \code{cell_type = "mark"}.
Used as fallback when the \code{mark} function does not return a \code{size} field. Default is \code{1}.}

\item{mark_name}{A character string specifying the title of the mark legend. Default is \code{"mark"}.
The legend is shown automatically when the \code{mark} function returns a list with a \code{legend} field.}

\item{violin_fill}{A character vector of colors to override the fill color of the violin plot.
If NULL, the fill color will be the same as the annotion.}

\item{boxplot_fill}{A character vector of colors to override the fill color of the boxplot.
If NULL, the fill color will be the same as the annotion.}

\item{dot_size}{A numeric value specifying the size of the dot or a function to calculate the size
from the values in the cell or a function to calculate the size from the values in the cell.}

\item{dot_size_name}{A character string specifying the name of the legend for the dot size.
If NULL, the dot size legend will not be shown.}

\item{legend_items}{A numeric vector with names to specifiy the items in the main legend.
The names will be working as the labels of the legend items.}

\item{legend_discrete}{A logical value indicating whether the main legend is discrete.}

\item{legend.position}{A character string specifying the position of the legend.
if \code{waiver()}, for single groups, the legend will be "none", otherwise "right".}

\item{legend.direction}{A character string specifying the direction of the legend.}

\item{lower_quantile, upper_quantile, lower_cutoff, upper_cutoff}{Vector of minimum and maximum cutoff values or quantile values for each feature.
It's applied to aggregated values when aggregated values are used (e.g. plot_type tile, label, etc).
It's applied to raw values when raw values are used (e.g. plot_type bars, etc).}

\item{add_bg}{A logical value indicating whether to add a background to the heatmap.
Does not work with \code{cell_type = "bars"} or \code{cell_type = "tile"}.}

\item{bg_alpha}{A numeric value between 0 and 1 specifying the transparency of the background.}

\item{add_reticle}{A logical value indicating whether to add a reticle to the heatmap.}

\item{reticle_color}{A character string specifying the color of the reticle.}

\item{cluster_columns}{A logical value indicating whether to cluster the columns.
If TRUE and columns_split_by is provided, the clustering will only be applied to the columns within the same split.}

\item{cluster_rows}{A logical value indicating whether to cluster the rows.
If TRUE and rows_split_by is provided, the clustering will only be applied to the rows within the same split.}

\item{show_row_names}{A logical value indicating whether to show the row names.
If TRUE, the legend of the row group annotation will be hidden.}

\item{show_column_names}{A logical value indicating whether to show the column names.
If TRUE, the legend of the column group annotation will be hidden.}

\item{border}{A logical value indicating whether to draw the border of the heatmap.
If TRUE, the borders of the slices will be also drawn.}

\item{title}{The global (column) title of the heatmap}

\item{column_title}{A character string/vector of the column name(s) to use as the title of the column group annotation.}

\item{row_title}{A character string/vector of the column name(s) to use as the title of the row group annotation.}

\item{na_col}{A character string specifying the color for missing values.
The default is "grey85".}

\item{row_names_side}{A character string specifying the side of the row names.
The default is "right".}

\item{column_names_side}{A character string specifying the side of the column names.
The default is "bottom".}

\item{column_annotation}{A character string/vector of the column name(s) to use as the column annotation.
Or a list with the keys as the names of the annotation and the values as the column names.}

\item{column_annotation_side}{A character string specifying the side of the column annotation.
Could be a list with the keys as the names of the annotation and the values as the sides.}

\item{column_annotation_palette}{A character string specifying the palette of the column annotation.
The default is "Paired".
Could be a list with the keys as the names of the annotation and the values as the palettes.}

\item{column_annotation_palcolor}{A character vector of colors to override the palette of the column annotation.
Could be a list with the keys as the names of the annotation and the values as the palcolors.}

\item{column_annotation_type}{A character string specifying the type of the column annotation.
The default is "auto". Other options are "simple", "pie", "ring", "bar", "violin", "boxplot", "density".
Could be a list with the keys as the names of the annotation and the values as the types.
If the type is "auto", the type will be determined by the type and number of the column data.}

\item{column_annotation_params}{A list of parameters passed to the annotation function.
Could be a list with the keys as the names of the annotation and the values as the parameters.
For the name/split annotations, use aliases: \code{.col}/\code{.cols}/\code{.column}/\code{.columns} for \code{columns_by}, \code{.col.split}/\code{.cols.split}/\code{.column.split}/\code{.columns.split}
for \code{columns_split_by}. Setting a key to \code{FALSE} disables that annotation.
\verb{$<key>$show_legend} controls the legend for that annotation.
See \code{\link[=anno_pie]{anno_pie()}}, \code{\link[=anno_ring]{anno_ring()}}, \code{\link[=anno_bar]{anno_bar()}}, \code{\link[=anno_violin]{anno_violin()}}, \code{\link[=anno_boxplot]{anno_boxplot()}}, \code{\link[=anno_density]{anno_density()}}, \code{\link[=anno_simple]{anno_simple()}}, \code{\link[=anno_points]{anno_points()}} and \code{\link[=anno_lines]{anno_lines()}} for the parameters of each annotation function.}

\item{column_annotation_agg}{A function to aggregate the values in the column annotation.}

\item{row_annotation}{A character string/vector of the column name(s) to use as the row annotation.
Or a list with the keys as the names of the annotation and the values as the column names.}

\item{row_annotation_side}{A character string specifying the side of the row annotation.
Could be a list with the keys as the names of the annotation and the values as the sides.}

\item{row_annotation_palette}{A character string specifying the palette of the row annotation.
The default is "Paired".
Could be a list with the keys as the names of the annotation and the values as the palettes.}

\item{row_annotation_palcolor}{A character vector of colors to override the palette of the row annotation.
Could be a list with the keys as the names of the annotation and the values as the palcolors.}

\item{row_annotation_type}{A character string specifying the type of the row annotation.
The default is "auto". Other options are "simple", "pie", "ring", "bar", "violin", "boxplot", "density".
Could be a list with the keys as the names of the annotation and the values as the types.
If the type is "auto", the type will be determined by the type and number of the row data.}

\item{row_annotation_params}{A list of parameters passed to the annotation function.
Could be a list with the keys as the names of the annotation and the values as the parameters.
For the name/split annotations, use aliases: \code{.row}/\code{.rows} for \code{rows_by}, \code{.rows.split}/\code{.row.split} for \code{rows_split_by}.
Setting a key to \code{FALSE} disables that annotation. \verb{$<key>$show_legend} controls the legend.
Same structure as \code{column_annotation_params}.}

\item{row_annotation_agg}{A function to aggregate the values in the row annotation.}

\item{flip}{A logical value indicating whether to flip the heatmap.
The idea is that, you can simply set \code{flip = TRUE} to flip the heatmap.
You don't need to swap the arguments related to rows and columns, except those you specify via \code{...}
that are passed to \code{ComplexHeatmap::Heatmap()} directly.}

\item{alpha}{A numeric value between 0 and 1 specifying the transparency of the heatmap cells.}

\item{seed}{The random seed to use. Default is 8525.}

\item{padding}{A numeric vector of length 4 specifying the padding of the heatmap in the order of top, right, bottom, left.
Like padding in css. Note that it is different than the \code{padding} argument in \code{ComplexHeatmap::draw()}, which is the padding
in the order of bottom, left, top, right.
It also support 1, 2, 3 values like css padding.
When 1 element is provided, it will be used for all sides.
When 2 elements are provided, the first one will be used for top and bottom, and the second one will be used for left and right.
When 3 elements are provided, the first one will be used for top, the second one will be used for left and right, and the third one will be used for bottom.
When 4 elements are provided, they will be used for top, right, bottom, and left respectively.
If no unit is provided, the default unit will be "mm".}

\item{base_size}{A positive numeric scalar used as a scaling factor for the overall heatmap size.
Default is \code{1} (no scaling). Values greater than 1 enlarge the heatmap; values less than 1 shrink it.
Internally, all calculated cell dimensions are multiplied by this factor.}

\item{aspect.ratio}{A positive numeric scalar giving the height-to-width ratio of a single heatmap
cell. When \code{NULL} (default), sensible per-\code{cell_type} defaults are used:
\itemize{
\item \code{tile}, \code{label}, \code{dot}: square cells (ratio = 1).
\item \code{bars}: wider-than-tall cells (ratio = 0.5) so individual bars are legible.
\item \code{violin}, \code{boxplot}, \code{pie}: square cells with a larger base size (0.5 in) so embedded
sub-plots have enough room.
Provide an explicit value to override these defaults (e.g. \code{aspect.ratio = 2} for
portrait cells, \code{aspect.ratio = 0.5} for landscape cells).
Note that for \code{cell_type = "pie"} the cells are always drawn square by ComplexHeatmap
regardless of this setting; use it primarily to budget the figure size.
Note that the aspect ratio is not guaranteed to be perfectly preserved; it will also be restricted by the size and height/width ratio of the entire plot itself.
}}

\item{draw_opts}{A named list of additional arguments passed to \code{\link[ComplexHeatmap:draw-dispatch]{ComplexHeatmap::draw()}}. Arguments already managed
internally (\code{annotation_legend_list}, \code{padding}, \code{show_annotation_legend}, \code{annotation_legend_side},
\code{column_title}) take precedence over any values supplied here.
See \url{https://jokergoo.github.io/ComplexHeatmap/reference/draw-HeatmapList-method.html} for available options.}

\item{layer_fun_callback}{A function to add additional layers to the heatmap.
The function should have the following arguments: \code{j}, \code{i}, \code{x}, \code{y}, \code{w}, \code{h}, \code{fill}, \code{sr} and \code{sc}.
Please also refer to the \code{layer_fun} argument in \code{ComplexHeatmap::Heatmap}.}

\item{cell_type}{A character string specifying the type of the heatmap cells.
The default is "tile" Other options are "bars", "label", "mark", "label+mark" (or equivalently "mark+label"),
"dot", "violin", "boxplot" and "pie".
Use "label+mark" to render both marks (drawn first, as background) and text labels (drawn on top)
in each cell simultaneously, combining all \verb{label_*} and \verb{mark_*} parameters.
Note that for pie chart, the values under columns specified by \code{rows} will not be used directly. Instead, the values
will just be counted in different \code{pie_group_by} groups. \code{NA} values will not be counted.}

\item{cell_agg}{A function to aggregate the values in the cell, for the cell type "tile" and "label".
The default is \code{mean}.}

\item{combine}{Whether to combine the plots into one when facet is FALSE. Default is TRUE.}

\item{nrow}{A numeric value specifying the number of rows in the facet.}

\item{ncol}{A numeric value specifying the number of columns in the facet.}

\item{byrow}{A logical value indicating whether to fill the plots by row.}

\item{axes}{A string specifying how axes should be treated. Passed to \code{\link[patchwork:wrap_plots]{patchwork::wrap_plots()}}.
Only relevant when \code{split_by} is used and \code{combine} is TRUE.
Options are:
\itemize{
\item 'keep' will retain all axes in individual plots.
\item 'collect' will remove duplicated axes when placed in the same run of rows or columns of the layout.
\item 'collect_x' and 'collect_y' will remove duplicated x-axes in the columns or duplicated y-axes in the rows respectively.
}}

\item{axis_titles}{A string specifying how axis titltes should be treated. Passed to \code{\link[patchwork:wrap_plots]{patchwork::wrap_plots()}}.
Only relevant when \code{split_by} is used and \code{combine} is TRUE.
Options are:
\itemize{
\item 'keep' will retain all axis titles in individual plots.
\item 'collect' will remove duplicated titles in one direction and merge titles in the opposite direction.
\item 'collect_x' and 'collect_y' control this for x-axis titles and y-axis titles respectively.
}}

\item{guides}{A string specifying how guides should be treated in the layout. Passed to \code{\link[patchwork:wrap_plots]{patchwork::wrap_plots()}}.
Only relevant when \code{split_by} is used and \code{combine} is TRUE.
Options are:
\itemize{
\item 'collect' will collect guides below to the given nesting level, removing duplicates.
\item 'keep' will stop collection at this level and let guides be placed alongside their plot.
\item 'auto' will allow guides to be collected if a upper level tries, but place them alongside the plot if not.
}}

\item{design}{Specification of the location of areas in the layout, passed to \code{\link[patchwork:wrap_plots]{patchwork::wrap_plots()}}.
Only relevant when \code{split_by} is used and \code{combine} is TRUE. When specified, \code{nrow}, \code{ncol}, and \code{byrow} are ignored.
See \code{\link[patchwork:wrap_plots]{patchwork::wrap_plots()}} for more details.}

\item{...}{Other arguments passed to \code{\link[ComplexHeatmap:Heatmap]{ComplexHeatmap::Heatmap()}}
When \code{row_names_max_width} is passed, a unit is expected. But you can also pass a numeric values,
with a default unit "inches", or a string like "5inches" to specify the number and unit directly.
Unmatched arguments will be warned and ignored.}
}
\description{
Heatmap is a popular way to visualize data in matrix format. It is widely used in biology to visualize gene expression data in microarray and RNA-seq data. The heatmap is a matrix where rows represent the samples and columns represent the features. The color of each cell represents the value of the feature in the sample. The color can be continuous or discrete. The heatmap can be split by the columns or rows to show the subgroups in the data. The heatmap can also be annotated by the columns or rows to show the additional information of the samples or features.
}
\examples{
\donttest{
set.seed(8525)

matrix_data <- matrix(rnorm(60), nrow = 6, ncol = 10)
rownames(matrix_data) <- paste0("R", 1:6)
colnames(matrix_data) <- paste0("C", 1:10)
if (requireNamespace("cluster", quietly = TRUE)) {
    Heatmap(matrix_data)
}
if (requireNamespace("cluster", quietly = TRUE)) {
    # use a different color palette
    # change the main legend title
    # show row names (legend will be hidden)
    # show column names
    # change the row name annotation name and side
    # change the column name annotation name
    Heatmap(matrix_data, palette = "viridis", values_by = "z-score",
       show_row_names = TRUE, show_column_names = TRUE,
       rows_name = "Features", row_names_side = "left",
       columns_name = "Samples")
}
if (requireNamespace("cluster", quietly = TRUE)) {
    # flip the heatmap
    Heatmap(matrix_data, palette = "viridis", values_by = "z-score",
       show_row_names = TRUE, show_column_names = TRUE,
       rows_name = "Features", row_names_side = "left",
       columns_name = "Samples", flip = TRUE)
}
if (requireNamespace("cluster", quietly = TRUE)) {
    # add annotations to the heatmap
    rows_data <- data.frame(
       rows = paste0("R", 1:6),
       group = sample(c("X", "Y", "Z"), 6, replace = TRUE)
    )
    Heatmap(matrix_data, rows_data = rows_data,
        row_annotation = list(Group = "group"),
        row_annotation_type = list(Group = "simple"),
        row_annotation_palette = list(Group = "Spectral")
    )
}
if (requireNamespace("cluster", quietly = TRUE)) {
    Heatmap(matrix_data, rows_data = rows_data,
        rows_split_by = "group"
    )
}
if (requireNamespace("cluster", quietly = TRUE)) {
    # add labels to the heatmap
    Heatmap(matrix_data, rows_data = rows_data,
        rows_split_by = "group", cell_type = "label",
        base_size = 0.8,
        label = function(x) ifelse(
            x > 0, scales::number(x, accuracy = 0.01), NA
        )
    )
}
if (requireNamespace("cluster", quietly = TRUE)) {
    # add labels based on an external data
    pvalues <- matrix(runif(60, 0, 0.5), nrow = 6, ncol = 10)
    Heatmap(matrix_data, rows_data = rows_data,
        rows_split_by = "group", cell_type = "label",
        base_size = 0.8,
        label = function(x, i, j) {
            pv <- ComplexHeatmap::pindex(pvalues, i, j)
            ifelse(pv < 0.01, "***",
            ifelse(pv < 0.05, "**",
            ifelse(pv < 0.1, "*", NA)))
        }
    )
}
if (requireNamespace("cluster", quietly = TRUE)) {
    # Set label color, size, legend and order
    pvalues <- matrix(runif(60, 0, 0.5), nrow = 6, ncol = 10)
    Heatmap(matrix_data, rows_data = rows_data,
        rows_split_by = "group", cell_type = "label",
        base_size = 0.6,
        label_name = "Significance",
        label = function(x, i, j) {
            pv <- ComplexHeatmap::pindex(pvalues, i, j)
            if (pv < 0.01)
               list("***", color = "red", size = 12, legend = "p < 0.01", order = 1)
            else if (pv < 0.05)
               list("**", color = "orange", size = 10, legend = "p < 0.05", order = 3)
            else if (pv < 0.1)
               list("*", color = "yellow", size = 8, legend = "p < 0.1", order = 2)
            else NA
        }
    )
}
if (requireNamespace("cluster", quietly = TRUE)) {
    # add marks
    Heatmap(matrix_data, rows_data = rows_data,
        rows_split_by = "group", cell_type = "mark",
        mark = function(x, i, j) {
            pv <- ComplexHeatmap::pindex(pvalues, i, j)
            if(pv < 0.01) list("[x]", legend = "p < 0.01")
            else if (pv < 0.02) list("[o]", legend = "p < 0.02")
            else if (pv < 0.03) list("[-]", legend = "p < 0.03")
            else if (pv < 0.05) list("[()]", legend = "p < 0.05")
            else if (pv < 0.06) list("+", legend = "p < 0.06")
            else if (pv < 0.07) list("x", legend = "p < 0.07")
            else if (pv < 0.08) list("[/]", legend = "p < 0.08")
            else if (pv < 0.09) list("[\\\\]", legend = "p < 0.09")
            else NA
        }
    )
}
if (requireNamespace("cluster", quietly = TRUE)) {
    # add labels and marks
    Heatmap(matrix_data, rows_data = rows_data,
        rows_split_by = "group", cell_type = "mark+label",
        label = scales::label_number(accuracy = 0.01),
        mark = function(x, i, j) {
            pv <- ComplexHeatmap::pindex(pvalues, i, j)
            if(pv < 0.01) list("{}", legend = "p < 0.01")
            else if(pv < 0.05) list("[]", legend = "p < 0.05")
            else NA
        },
        mark_size = 1.5, mark_color = "red"
    )
}
if (requireNamespace("cluster", quietly = TRUE)) {
    # quickly simulate a GO board
    go <- matrix(sample(c(0, 1, NA), 81, replace = TRUE), ncol = 9)

    Heatmap(
        go,
        # Do not cluster rows and columns and hide the name annotations
        # Use .row/.col aliases (or the actual rows_name/columns_name) in annotation_params
        cluster_rows = FALSE, cluster_columns = FALSE,
        row_annotation_params = list(.row = FALSE),
        column_annotation_params = list(.col = FALSE),
        show_row_names = FALSE, show_column_names = FALSE,
        # Set the legend items
        values_by = "Players", legend_discrete = TRUE,
        legend_items = c("Player 1" = 0, "Player 2" = 1),
        # Set the pawns
        cell_type = "dot", dot_size = function(x) ifelse(is.na(x), 0, 10),
        dot_size_name = NULL,  # hide the dot size legend
        palcolor = c("white", "black"),
        # Set the board
        add_reticle = TRUE,
        # Set the size of the board
        width = ggplot2::unit(105, "mm"), height = ggplot2::unit(105, "mm"))
}
if (requireNamespace("cluster", quietly = TRUE)) {
    # Make the row/column name annotation thicker using the .row/.col aliases
    Heatmap(matrix_data,
        column_annotation_params = list(.col = list(height = 5)),
        row_annotation_params = list(.row = list(width = 5)))
}

# Use long form data
N <- 500
data <- data.frame(
    value = rnorm(N),
    c = sample(letters[1:8], N, replace = TRUE),
    r = sample(LETTERS[1:5], N, replace = TRUE),
    p = sample(c("x", "y"), N, replace = TRUE),
    q = sample(c("X", "Y", "Z"), N, replace = TRUE),
    a = as.character(sample(1:5, N, replace = TRUE)),
    p1 = runif(N),
    p2 = runif(N)
)

if (requireNamespace("cluster", quietly = TRUE)) {
    Heatmap(data, rows_by = "r", columns_by = "c", values_by = "value",
        rows_split_by = "p", columns_split_by = "q", show_column_names = TRUE)
}
if (requireNamespace("cluster", quietly = TRUE)) {
    # split into multiple heatmaps
    Heatmap(data,
        values_by = "value", columns_by = "c", rows_by = "r", split_by = "p",
        upper_cutoff = 2, lower_cutoff = -2, legend.position = c("none", "right"),
        design = "AAAAAA#BBBBBBB"
    )
}
if (requireNamespace("cluster", quietly = TRUE)) {
    # cell_type = "bars" (default is "tile")
    Heatmap(data, values_by = "value", rows_by = "r", columns_by = "c",
        cell_type = "bars")
}
if (requireNamespace("cluster", quietly = TRUE)) {
    p <- Heatmap(data, values_by = "value", rows_by = "r", columns_by = "c",
        cell_type = "dot", dot_size = length, dot_size_name = "data points",
        add_bg = TRUE, add_reticle = TRUE)
    p
}
if (requireNamespace("cluster", quietly = TRUE)) {
    dot_size_data <- p@data
    # Make it big so we can see if we get the right indexing
    # for dot_size function
    dot_size_data["A", "a"] <- max(dot_size_data) * 2

    Heatmap(data, values_by = "value", rows_by = "r", columns_by = "c",
        cell_type = "dot", dot_size_name = "data points",
        dot_size = function(x, i, j) ComplexHeatmap::pindex(dot_size_data, i, j),
        show_row_names = TRUE, show_column_names = TRUE,
        add_bg = TRUE, add_reticle = TRUE)
}
if (requireNamespace("cluster", quietly = TRUE)) {
    Heatmap(data, values_by = "value", rows_by = "r", columns_by = "c",
        cell_type = "pie", pie_group_by = "q", pie_size = sqrt,
        add_bg = TRUE, add_reticle = TRUE)
}
if (requireNamespace("cluster", quietly = TRUE)) {
    Heatmap(data, values_by = "value", rows_by = "r", columns_by = "c",
        cell_type = "violin", add_bg = TRUE, add_reticle = TRUE)
}
if (requireNamespace("cluster", quietly = TRUE)) {
    Heatmap(data, values_by = "value", rows_by = "r", columns_by = "c",
        cell_type = "boxplot", add_bg = TRUE, add_reticle = TRUE)
}
if (requireNamespace("cluster", quietly = TRUE)) {
    Heatmap(data,
        values_by = "value", rows_by = "r", columns_by = "c",
        column_annotation = list(r1 = "p", r2 = "q", r3 = "p1"),
        column_annotation_type = list(r1 = "ring", r2 = "bar", r3 = "violin"),
        column_annotation_params = list(
            r1 = list(height = grid::unit(10, "mm"), show_legend = FALSE),
            r3 = list(height = grid::unit(18, "mm"))
        ),
        row_annotation = c("q", "p2", "a"),
        row_annotation_side = "right",
        row_annotation_type = list(q = "pie", p2 = "density", a = "simple"),
        row_annotation_params = list(q = list(width = grid::unit(12, "mm"))),
        show_row_names = TRUE, show_column_names = TRUE
    )
}
if (requireNamespace("cluster", quietly = TRUE)) {
    Heatmap(data,
        values_by = "value", rows_by = "r", columns_by = "c",
        split_by = "p", palette = list(x = "Reds", y = "Blues")
    )
}
if (requireNamespace("cluster", quietly = TRUE)) {
    # implies in_form = "wide-rows"
    Heatmap(data, rows_by = c("p1", "p2"), columns_by = "c")
}
if (requireNamespace("cluster", quietly = TRUE)) {
    # implies wide-columns
    Heatmap(data, rows_by = "r", columns_by = c("p1", "p2"))
}
}
}
\seealso{
\code{\link{anno_simple}}, \code{\link{anno_points}}, \code{\link{anno_lines}}, \code{\link{anno_pie}}, \code{\link{anno_violin}}, \code{\link{anno_boxplot}}, \code{\link{anno_density}}
}
