% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/heatmap.R
\name{HeatmapAtomic}
\alias{HeatmapAtomic}
\title{Atomic heatmap (internal)}
\usage{
HeatmapAtomic(
  data,
  values_by,
  values_fill = NA,
  rows_by = NULL,
  rows_split_by = NULL,
  columns_by = NULL,
  columns_split_by = NULL,
  palette = "RdBu",
  palcolor = NULL,
  palreverse = FALSE,
  pie_size_name = "size",
  pie_size = NULL,
  pie_values = "length",
  pie_group_by = NULL,
  pie_palette = "Spectral",
  pie_palcolor = NULL,
  bars_sample = 1,
  label = scales::label_number_auto(),
  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,
  keep_na = FALSE,
  keep_empty = FALSE,
  add_reticle = FALSE,
  reticle_color = "grey",
  cluster_columns = TRUE,
  cluster_rows = TRUE,
  show_row_names = NULL,
  show_column_names = NULL,
  border = TRUE,
  title = NULL,
  column_title = NULL,
  row_title = NULL,
  na_col = "grey85",
  row_names_side = "right",
  column_names_side = "bottom",
  row_annotation = NULL,
  row_annotation_side = NULL,
  row_annotation_palette = NULL,
  row_annotation_palcolor = NULL,
  row_annotation_type = NULL,
  row_annotation_params = NULL,
  row_annotation_agg = NULL,
  column_annotation = NULL,
  column_annotation_side = NULL,
  column_annotation_palette = NULL,
  column_annotation_palcolor = NULL,
  column_annotation_type = NULL,
  column_annotation_params = NULL,
  column_annotation_agg = NULL,
  flip = FALSE,
  alpha = 1,
  seed = 8525,
  padding = 15,
  base_size = 1,
  aspect.ratio = NULL,
  draw_opts = list(),
  return_ht = FALSE,
  layer_fun_callback = NULL,
  cell_type = "tile",
  cell_agg = NULL,
  ...
)
}
\arguments{
\item{data}{A data frame in long format. Each row represents one
observation; columns specify row/column membership and the value to
encode as colour.}

\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 used to fill missing cells in the matrix.
Default \code{NA}.  Missing values prevent clustering when not filled.}

\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_split_by}{A character of column name in \code{data} that contains the split information for rows.}

\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_split_by}{A character of column name in \code{data} that contains the split information for columns.}

\item{palette}{A character string naming a palette (see
\code{\link{show_palettes}}) or a character vector of colours for the
main heatmap colour scale.  Default \code{"RdBu"}.}

\item{palcolor}{A custom colour vector overriding \code{palette}.}

\item{palreverse}{A logical value indicating whether to reverse the palette. Default is FALSE.}

\item{pie_size_name}{Legend title for the pie size.}

\item{pie_size}{A numeric value or function returning the pie radius.
When a function, it receives the count of groups in the pie.}

\item{pie_values}{A function or string (convertible via
\code{\link[base]{match.arg}}) to compute the value represented by
each pie slice.  Default \code{"length"} counts observations per
group.}

\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_palette, pie_palcolor}{Palette and custom colours for pie slice
fill colours.}

\item{bars_sample}{Fraction of each cell's observations (0 < x <= 1;
\code{1} uses all data) or a whole count > 1 sampled per cell when
\code{cell_type = "bars"}.  Column widths are proportional to the
number of bars drawn per column, so a numeric count gives equal
column widths and a fraction gives widths proportional to the
column data sizes.  Proportional widths are skipped when
\code{columns_split_by} is given, and column clustering is
disabled in proportional mode.  Default 1 (all data).}

\item{label}{A function to compute text labels when
\code{cell_type = "label"} (or \code{"label+mark"}).  Receives the
aggregated value for a cell and optionally row/column indices and
names.  See below for the full dispatch contract.}

\item{label_size}{Default point size for label text (used as fallback
when the \code{label} function does not return a \code{size} field).}

\item{label_color}{Default colour for label text (fallback).}

\item{label_name}{Legend title for the label colour scale.  The legend
is shown automatically when the \code{label} function returns a
\code{legend} field for at least one cell.}

\item{mark}{A function to compute mark symbols when
\code{cell_type = "mark"} (or \code{"label+mark"}).  Same dispatch
contract as \code{label}.}

\item{mark_color}{Default mark colour (fallback).}

\item{mark_size}{Default mark stroke width (\code{lwd}) in pt (fallback).}

\item{mark_name}{Legend title for the mark colour scale.}

\item{violin_fill}{A character vector of colours to use as fill for
violin plots when \code{cell_type = "violin"}.  If \code{NULL}, the
annotation colour is used.}

\item{boxplot_fill}{A character vector of colours to use as fill for
boxplots when \code{cell_type = "boxplot"}.  If \code{NULL}, the
annotation colour is used.}

\item{dot_size}{Dot size when \code{cell_type = "dot"}.  Can be a
numeric value or a function.}

\item{dot_size_name}{Legend title for the dot size.}

\item{legend_items}{A named numeric vector specifying custom legend
entries for the main colour scale.  Names become the displayed labels.}

\item{legend_discrete}{Logical; if \code{TRUE}, treat the main colour
scale as 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}{Quantile or explicit cutoffs for clipping the colour scale.  Applied
to aggregated values for \code{tile} / \code{label} cell types; applied
to raw values for \code{bars} / \code{violin} / \code{boxplot} types.}

\item{add_bg}{Logical; if \code{TRUE}, add a background fill behind
non-tile cell types.  Not used for \code{cell_type = "tile"} or
\code{"bars"}.}

\item{bg_alpha}{Numeric in \eqn{[0, 1]} for background transparency.}

\item{keep_na}{A logical value or a character to replace the NA values in the data.
It can also take a named list to specify different behavior for different columns.
If TRUE or NA, NA values will be replaced with NA.
If FALSE, NA values will be removed from the data before plotting.
If a character string is provided, NA values will be replaced with the provided string.
If a named vector/list is provided, the names should be the column names to apply the behavior to,
and the values should be one of TRUE, FALSE, or a character string.
Without a named vector/list, the behavior applies to categorical/character columns used on the plot,
for example, the \code{x}, \code{group_by}, \code{fill_by}, etc.}

\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{add_reticle}{Logical; if \code{TRUE}, draw a reticle (crosshair
pattern) over the heatmap.}

\item{reticle_color}{Colour for the reticle lines.}

\item{cluster_columns}{Logical; cluster the columns.  If \code{TRUE} and
\code{columns_split_by} is provided, clustering is applied within each
split group.}

\item{cluster_rows}{Logical; cluster the rows.  If \code{TRUE} and
\code{rows_split_by} is provided, clustering is applied within each
split group.}

\item{show_row_names}{Logical or character vector; show row names.  If
\code{TRUE}, the legend of the row group annotation is hidden.
\code{FALSE} only hides the in-place names.  Alternatively, a character
vector combining the display modes \code{"inplace"} (in-place names,
same as \code{TRUE}), \code{"legend"} (row group annotation with
legend), \code{"simple"} (row group annotation without legend),
\code{"anno"} (alias \code{"annotation"}; label annotation showing the
row names as text) and \code{"none"} (no names, annotation, or legend).
Modes are lower-priority defaults: explicit \code{row_annotation}
entries (e.g. \code{.row}) still win.}

\item{show_column_names}{Logical or character vector; show column names.
See \code{show_row_names} for the display modes.}

\item{border}{A logical value indicating whether to draw borders around
the heatmap.  If \code{TRUE}, slice borders are also drawn.  Default
\code{TRUE}.}

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

\item{column_title}{Character string/vector used as the column group
annotation title.  A character vector consisting entirely of the display
modes \code{"inplace"} (per-slice split titles), \code{"legend"} (split
annotation with legend, no title), \code{"simple"} (split annotation,
no legend/title), \code{"anno"} (alias \code{"annotation"}; label block
annotation) and \code{"none"} (no title, annotation, or legend)
controls how the split titles are displayed.  A literal title identical
to a mode keyword is interpreted as a mode.}

\item{row_title}{Character string/vector used as the row group
annotation title.  See \code{column_title} for the display modes.}

\item{na_col}{Colour for \code{NA} cells.  Default \code{"grey85"}.}

\item{row_names_side}{Side for row names.  Default \code{"right"}.}

\item{column_names_side}{Side for column names.  Default \code{"bottom"}.}

\item{row_annotation}{A structured list specifying row annotations.
Same format as \code{column_annotation}.  Sides default to
\code{"left"}.  Aliases: \code{.row}/\code{.rows} for
\code{rows_by}, \code{.row.split}/\code{.rows.split} for
\code{rows_split_by}.}

\item{row_annotation_side}{\strong{Deprecated}: use
\code{row_annotation} with the \code{side} sub-key instead.}

\item{row_annotation_palette}{\strong{Deprecated}: use
\code{row_annotation} with the \code{palette} sub-key instead.}

\item{row_annotation_palcolor}{\strong{Deprecated}: use
\code{row_annotation} with the \code{palcolor} sub-key instead.}

\item{row_annotation_type}{\strong{Deprecated}: use
\code{row_annotation} with the \code{type} sub-key instead.}

\item{row_annotation_params}{\strong{Deprecated}: use
\code{row_annotation} with the \code{params} sub-key instead.}

\item{row_annotation_agg}{\strong{Deprecated}: use
\code{row_annotation} with the \code{agg} sub-key instead.}

\item{column_annotation}{A structured list specifying column annotations.
Each entry is a named list with sub-keys:
\describe{
\item{\code{col}}{Column name in \code{data} supplying the annotation
values.  If omitted, the entry name is used as the column name.}
\item{\code{side}}{\code{"top"} or \code{"bottom"}.}
\item{\code{palette}}{Palette name (see \code{\link{show_palettes}}).}
\item{\code{palcolor}}{Custom colour vector overriding \code{palette}.}
\item{\code{type}}{Annotation type: \code{"auto"}, \code{"simple"},
\code{"pie"}, \code{"ring"}, \code{"bar"}, \code{"violin"},
\code{"boxplot"}, \code{"density"}, \code{"label"},
\code{"rownames"}, \code{"points"}, \code{"lines"}.
For split annotations, \code{"rownames"} (row splits) /
\code{"colnames"} (column splits) is like \code{"label"} but labels
each split block with the concatenated row/column names;
\code{"names"} and \code{"dimnames"} are aliases.
\code{params$sep} (default \code{" "}) controls the separator and
\code{params$wrap_by} the number of names per line.
For name annotations (the built-in \code{rows_by}/\code{columns_by}
annotation), \code{"rownames"}/\code{"colnames"} renders the
row/column names as text labels (this is what
\code{show_row_names = "anno"} uses).}
\item{\code{params}}{A list of additional parameters passed to the
annotation constructor.  \code{FALSE} disables the annotation.
\code{$show_legend} controls legend visibility.  See
\code{\link[ComplexHeatmap]{HeatmapAnnotation}}.}
\item{\code{agg}}{A function to aggregate values for the annotation.}
\item{\code{name}}{Display name for the annotation, shown next to the
annotation bar and used as the legend title.  \code{FALSE} hides the
displayed name.  Defaults to the annotation key (column name).}
}
\strong{Shortcuts:}
\itemize{
\item \code{column_annotation = list(Score = "score")} is short for
\code{list(Score = list(col = "score"))}.
\item \code{column_annotation = TRUE} enables annotations with
defaults.  \code{FALSE} disables all column annotations.
}
\strong{Special keys:}
\itemize{
\item \code{.default} — default values inherited by all entries.
\code{params} is merged recursively; other keys are inherited
only when the entry does not already specify them.
\item \code{.col} / \code{.cols} / \code{.column} / \code{.columns} —
alias for \code{columns_by} (the built-in name annotation).
\item \code{.col.split} / \code{.cols.split} / \code{.column.split} /
\code{.columns.split} — alias for \code{columns_split_by}
(the built-in split annotation).
\item \code{.row} / \code{.rows} — alias for \code{rows_by}.
\item \code{.row.split} / \code{.rows.split} — alias for
\code{rows_split_by}.
}}

\item{column_annotation_side}{\strong{Deprecated}: use
\code{column_annotation} with the \code{side} sub-key instead.}

\item{column_annotation_palette}{\strong{Deprecated}: use
\code{column_annotation} with the \code{palette} sub-key instead.}

\item{column_annotation_palcolor}{\strong{Deprecated}: use
\code{column_annotation} with the \code{palcolor} sub-key instead.}

\item{column_annotation_type}{\strong{Deprecated}: use
\code{column_annotation} with the \code{type} sub-key instead.}

\item{column_annotation_params}{\strong{Deprecated}: use
\code{column_annotation} with the \code{params} sub-key instead.}

\item{column_annotation_agg}{\strong{Deprecated}: use
\code{column_annotation} with the \code{agg} sub-key instead.}

\item{flip}{Logical; if \code{TRUE}, swap rows and columns
transparently.  The caller does not need to swap row- and
column-related arguments manually.}

\item{alpha}{Alpha transparency for heatmap cells in \eqn{[0, 1]}.}

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

\item{padding}{Padding around the heatmap in CSS order (top, right,
bottom, left).  Supports 1–4 values.  Default 15 (mm).  Note that
this is different from \code{ComplexHeatmap::draw()}'s \code{padding}
argument which uses bottom-left-top-right order.}

\item{base_size}{A positive numeric scalar used as a scaling factor for
the overall heatmap size.  Default 1 (no scaling).  Values > 1 enlarge
all cell dimensions proportionally.}

\item{aspect.ratio}{Height-to-width ratio of a single heatmap cell.
When \code{NULL} (default), sensible per-\code{cell_type} defaults are
used: 1 for \code{tile}/\code{label}/\code{dot}, 0.5 for \code{bars},
and 2 for \code{violin}/\code{boxplot}/\code{pie}.  The ratio is
constrained by the overall plot dimensions.}

\item{draw_opts}{A named list of additional arguments passed to
\code{\link[ComplexHeatmap]{draw,HeatmapList-method}}.  Internally
managed arguments take precedence.}

\item{return_ht}{Logical; if \code{TRUE}, return the prepared
\code{ComplexHeatmap::Heatmap} object without drawing.  Used
internally by \code{\link{LinkedHeatmapAtomic}}.}

\item{layer_fun_callback}{A function to add custom graphical layers on
top of each heatmap cell.  Receives \code{j}, \code{i}, \code{x},
\code{y}, \code{w}, \code{h}, \code{fill}, \code{sr}, \code{sc}.
See \code{\link[ComplexHeatmap]{Heatmap}} for details.}

\item{cell_type}{The type of cell to render.  One of \code{"tile"}
(default), \code{"bars"}, \code{"label"}, \code{"mark"},
\code{"label+mark"} (or \code{"mark+label"}), \code{"dot"},
\code{"violin"}, \code{"boxplot"}, \code{"pie"}.  See the
\strong{Cell types} section for details.}

\item{cell_agg}{A function to aggregate values within each cell when
\code{cell_type = "tile"} or \code{"label"}.  Default is
\code{\link[base]{mean}}.}

\item{...}{Additional arguments passed to
\code{\link[ComplexHeatmap]{Heatmap}}.  When
\code{row_names_max_width} is passed, a \code{unit} is expected but
numeric values (default unit \code{"inches"}) or strings like
\code{"5inches"} are also accepted.  Unmatched arguments produce a
warning.}
}
\value{
An object of heatmap that is wrapped by \code{patchwork::wrap_plots()}
}
\description{
Core implementation for drawing a single heatmap using
\code{ComplexHeatmap::Heatmap}.  This function takes pre-processed data
(already in long format with resolved row/column identifiers) and handles
colour mapping, cell rendering, annotation construction, and the final
\code{draw()} call.  It is the workhorse behind the exported
\code{\link{Heatmap}} function and is also reused by
\code{\link{LinkedHeatmapAtomic}} (via \code{return_ht = TRUE}).
}
\note{
Removed parameters: \code{rows_palette}, \code{rows_palcolor},
\code{columns_palette}, \code{columns_palcolor},
\code{columns_split_palette}, \code{columns_split_palcolor},
\code{rows_split_palette}, \code{rows_split_palcolor} — use
\code{row_annotation}/\code{column_annotation} with
sub-key \code{palette}/\code{palcolor} and alias
\code{.row} / \code{.row.split} / \code{.col} / \code{.col.split}.
Also removed:
\code{row_name_annotation}, \code{row_name_legend},
\code{column_name_annotation}, \code{column_name_legend} — set
\code{row_annotation = list(.row = list(params = FALSE))} /
\code{column_annotation = list(.col = list(params = FALSE))}.
}
\section{Architecture}{

\enumerate{
\item \strong{Annotation resolution} — row and column annotation
parameters (side, type, palette, params, aggregation) are
resolved with alias support (\code{.row}, \code{.col},
\code{.rows.split}, etc.) so that built-in name/split annotations
and user-defined annotations can be configured uniformly.
\item \strong{Keep-NA / keep-empty handling} — \code{keep_na} and
\code{keep_empty} are processed per column to control whether
\code{NA} values and empty factor levels are preserved in the
data before constructing the heatmap matrix.
\item \strong{Flip} — when \code{flip = TRUE}, row and column
parameters are swapped transparently so the caller does not need
to manually swap every argument.
\item \strong{Cell dimension calculation} — cell width and height are
pre-computed from \code{cell_type}, \code{aspect.ratio},
\code{base_size}, and the unique row/column counts (accounting
for split groups).  These are passed as explicit
\code{"inches"} units to \code{ComplexHeatmap::Heatmap()} so
cells have guaranteed physical sizes.
\item \strong{Colour mapping} — the main colour scale is built from
\code{palette} / \code{palcolor} with optional quantile-based
or explicit cutoff clamping.
\item \strong{Cell function dispatch} — depending on
\code{cell_type}, the appropriate \code{cell_fun} or
\code{layer_fun} is installed (tile, bars, label, mark,
label+mark, dot, violin, boxplot, pie).
\item \strong{Annotation construction} — row and column annotations
are built via \code{ComplexHeatmap::HeatmapAnnotation()} using
the resolved type and parameters.
\item \strong{Drawing} — the heatmap is drawn via
\code{ComplexHeatmap::draw()} with controlled padding and legend
collection.  When \code{return_ht = TRUE}, the prepared
\code{Heatmap} object is returned without drawing.
\item \strong{Dimension attributes} — the returned object carries
\code{height} / \code{width} attributes (in inches) and
\code{cell_w} / \code{cell_h} attributes for downstream layout
calculations.
}
}

\section{Label / mark dispatch contract}{

The \code{label} and \code{mark} functions can take 1, 3, or 5
arguments.  The first argument is always the aggregated value for a
single cell.  With 3 arguments, the second and third are the row and
column indices.  With 5 arguments, the fourth and fifth are the row
and column names.  The function should return one of:
\itemize{
\item \code{NA} — nothing is drawn for this cell.
\item A character scalar — used as the label text / mark type;
default size and colour are used.
\item A named list with fields \code{label}/\code{mark},
\code{size}, \code{color}, \code{legend}, and \code{order}
(all optional; smaller \code{order} appears first in the
legend).
}
For label cells with custom indices, use
\code{ComplexHeatmap::pindex()} to translate between data and heatmap
coordinates.
}

\section{Supported mark types}{

\itemize{
\item \strong{Primitives:} \code{-} (h-line), \code{|} (v-line),
\code{+} (cross), \code{/} (l-diag), \code{\\} (r-diag),
\code{x} (both diags), \code{o} (circle), \code{()}
(edge-touching circle), \code{<>} (diamond).
\item \strong{With rectangular border:} \code{[]}, \code{[-]},
\code{[|]}, \code{[+]}, \code{[/]}, \code{[\\]}, \code{[x]},
\code{[o]}, \code{[()]}, \code{[<>]}.
\item \strong{With full circle:} \code{(-)}, \code{(|)},
\code{(+)}, \code{(/)}, \code{(\\)}, \code{(x)}, \code{(o)},
\code{(<>)}.
\item \strong{With diamond:} \code{<->}, \code{<|>}, \code{<+>},
\code{</>}, \code{<\\>}, \code{<x>}, \code{<o>}.
\item \strong{Octagon:} \code{\{\}}, \code{\{-\}}, \code{\{|\}},
\code{\{+\}}, \code{\{/\}}, \code{\{\\\}}, \code{\{x\}},
\code{\{o\}}, \code{\{()\}}, \code{\{<>\}}.
\item \strong{Combinations:} e.g. \code{[(|)]}, \code{[(-)]},
\code{[(+)]}, \code{[(/)]}, \code{[(\\]}, \code{[(x)]},
\code{[(o)]}, \code{[(<>)]}.
}
}

\section{Annotations}{

Row and column annotations are configured via the
\code{row_annotation} / \code{column_annotation} structured list
arguments.  Built-in name annotations (for \code{rows_by} /
\code{columns_by}) and split annotations (for \code{rows_split_by} /
\code{columns_split_by}) are added automatically and can be configured
using the aliases \code{.row} / \code{.col} and \code{.row.split} /
\code{.col.split} as keys in the annotation list.  Setting an alias
entry's \code{params} to \code{FALSE} disables that annotation.
\code{.default} provides default values inherited by all entries
(with recursive merge for \code{params}).  Ordering within each side:
name annotations are closest to the body, split annotations farthest
away, user-defined annotations in between.
}

\keyword{internal}
