% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/linkedheatmap.R
\name{LinkedHeatmap}
\alias{LinkedHeatmap}
\title{Linked Heatmap}
\usage{
LinkedHeatmap(
  data,
  values_by,
  values_fill = NA,
  name = NULL,
  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,
  palreverse = FALSE,
  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 = 1,
  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,
  title_params = 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,
  link_width_by = NULL,
  link_width_scale = 5,
  link_color = "grey40",
  link_alpha = 0.6,
  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 in long format. Each row represents one
observation; columns specify row/column membership for both left and
right heatmaps as well as the values to encode as color.}

\item{values_by}{Default column name for heatmap cell values.  Used as
fallback when \code{left_values_by} / \code{right_values_by} are not
explicitly provided via \code{...}.}

\item{values_fill}{A value used to fill missing cells in the matrix
(passed to \code{HeatmapAtomic}).  Default is \code{NA} (cells with no
data are left empty).}

\item{name}{Default legend title for the colour scale.  Used as fallback
when \code{left_name} / \code{right_name} are not provided via
\code{...}.  The suffixes \code{" (left)"} / \code{" (right)"} are
appended automatically.}

\item{split_by}{The column(s) to split data by and plot separately.
When \code{combine = TRUE}, the combined plot's data (\code{p$data})
contains the rows of every split, tagged with the \code{split_by}
column. For ggraph-based plots (e.g. \code{\link{Network}},
\code{\link{ClustreePlot}}), the node layout of every split is
exposed with the split column, and the original link rows (also
tagged with the \code{split_by} column) are available as the
\code{"edges"} attribute of the data.}

\item{split_by_sep}{The separator for multiple split_by columns. See \code{split_by}}

\item{rows_by}{Default column for rows in both heatmaps.  Used as
fallback for \code{left_rows_by} / \code{right_rows_by}.}

\item{rows_by_sep}{Separator for concatenated \code{rows_by} columns.}

\item{rows_split_by}{Optional column name to split the rows of \strong{both}
heatmaps into groups (passed as \code{row_split}).  When provided, row
names in the link table are prefixed with the split level to
disambiguate rows across splits.}

\item{rows_split_by_sep}{Separator for concatenated
\code{rows_split_by} columns.}

\item{columns_by}{Default column for columns in both heatmaps.  Used as
fallback for \code{left_columns_by} / \code{right_columns_by}.}

\item{columns_by_sep}{Separator for concatenated \code{columns_by}
columns.}

\item{columns_split_by}{Default column to split columns into groups.
Used as fallback for \code{left_columns_split_by} /
\code{right_columns_split_by}.}

\item{columns_split_by_sep}{Separator for concatenated
\code{columns_split_by} columns.}

\item{rows_data, columns_data}{Optional data frames providing additional
row / column metadata for annotations.  Passed through to
\code{HeatmapAtomic}.}

\item{keep_na, keep_empty}{Passed through to \code{HeatmapAtomic}.
See \code{\link{common_args}} for details.}

\item{rows_orderby, columns_orderby}{Column name to order rows / columns
by (disables clustering when set).}

\item{columns_name}{Display name for the column annotation.}

\item{columns_split_name}{Display name for the column split annotation.}

\item{rows_name}{Display name for the row annotation.}

\item{rows_split_name}{Display name for the row split annotation.}

\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"}.  Applied to both
heatmaps unless overridden per-side via \code{...}.}

\item{palcolor}{A custom colour vector that overrides \code{palette} for
the main heatmap colour scale.  Applied to both heatmaps unless
overridden per-side.}

\item{palreverse}{Logical; if \code{TRUE}, reverse the palette direction.}

\item{pie_size_name}{Legend title for the pie size when
\code{cell_type = "pie"}.}

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

\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_name}{Default name for the pie legend.  Used as fallback for
\code{left_pie_name} / \code{right_pie_name}.}

\item{pie_group_by}{Default column(s) for pie grouping.  Used as fallback
for \code{left_pie_group_by} / \code{right_pie_group_by}.}

\item{pie_group_by_sep}{Separator for concatenated \code{pie_group_by}
columns.}

\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.  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 \code{\link{HeatmapAtomic}} 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 (used as fallback when
the \code{label} function does not return a \code{color} field).}

\item{label_name}{Legend title for the label colour scale.}

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

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

\item{mark_size}{Default mark stroke width 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 where to place the
combined legend: \code{"right"} (default), \code{"left"}, \code{"top"},
\code{"bottom"}, or \code{"none"}.}

\item{legend.direction}{Legend stacking direction:
\code{"vertical"} (default) or \code{"horizontal"}.}

\item{lower_quantile, upper_quantile}{Quantiles used for clipping the
colour scale when \code{lower_cutoff} / \code{upper_cutoff} are
\code{NULL}.  Defaults are 0 and 0.99 respectively.}

\item{lower_cutoff, upper_cutoff}{Explicit cutoffs for the colour scale.
Values outside the range are clamped (winsorized).  Override
\code{lower_quantile} / \code{upper_quantile} when set.}

\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{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 columns in both heatmaps.
\code{NULL} lets \code{HeatmapAtomic} decide.}

\item{cluster_rows}{Default clustering setting for rows.  Used as
fallback for \code{left_cluster_rows} / \code{right_cluster_rows}.}

\item{show_row_names, show_column_names}{Logical; show row/column names.
May also be a character vector of display modes; see
\code{\link{Heatmap}}.}

\item{border}{Logical; draw a border around each heatmap.  Default
\code{TRUE}.}

\item{title}{A character string for the overall plot title.  A function
can be used to generate a dynamic title from the default.
Note that, \code{left_title} and \code{right_title} are used to set the title for each heatmap,
and \code{title} is used to set the overall title for the combined plot.}

\item{title_params}{A list of parameters passed to \code{grid::grid.text()} to control the title appearance.
Default is \code{list(gp = gpar(fontsize = 14, fontface = "bold"))}.}

\item{column_title, row_title}{Character title displayed above the columns
/ beside the rows of each heatmap.  May also be a character vector of
display modes; see \code{\link{Heatmap}}.}

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

\item{row_names_side}{Default side for row names.  Used as fallback for
\code{left_row_names_side} / \code{right_row_names_side}.  Default
\code{"right"}.}

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

\item{row_annotation}{A structured list specifying row annotations.
See \code{\link{HeatmapAtomic}} for the full specification.}

\item{row_annotation_side}{\strong{Deprecated}: use
\code{row_annotation} with the \code{side} sub-key instead.  Used as
fallback for \code{left_row_annotation_side} /
\code{right_row_annotation_side}.  Default \code{"left"}.}

\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.
See \code{\link{HeatmapAtomic}} for the full specification.}

\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{link_width_by}{Optional column name in \code{data} whose values
determine the stroke width of each link line (e.g. interaction
strength).  Values are min-max scaled to \eqn{[0, 1]} and multiplied by
\code{link_width_scale}.
You can also pass a numeric value to use a constant width for all links.}

\item{link_width_scale}{Numeric scaling factor applied to the normalised
link intensity values to produce final line widths (\code{lwd}).
Default 5.}

\item{link_color}{Colour of the link spline curves.  Default
\code{"grey30"}.}

\item{link_alpha}{Alpha transparency of link curves in \eqn{[0, 1]}.
Default 0.8.}

\item{flip}{Logical; must be \code{FALSE} for linked heatmaps (flipping
is not supported).  Default \code{FALSE}.}

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

\item{seed}{Random seed for reproducibility.  Default 8525.}

\item{padding}{Padding around the heatmap in CSS order (top, right,
bottom, left).  Supports 1–4 values.  Default 15 (mm).}

\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 defaults are chosen per
\code{cell_type} (e.g. 1 for tiles, 0.5 for bars, 2 for violins).}

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

\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"}.  Different cell types
use different \code{cell_fun} / \code{layer_fun} implementations.}

\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{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{...}{Additional arguments passed to \code{\link{LinkedHeatmapAtomic}}.
All parameters listed above (and those inherited from
\code{LinkedHeatmapAtomic}) can be specified with \code{left_} or
\code{right_} prefixes for per-side control (e.g.
\code{left_palette = "Blues"}, \code{right_palette = "Reds"}).
Unprefixed arguments apply to both sides.  Also forwarded to
\code{\link[ComplexHeatmap]{Heatmap}} after prefix stripping.}
}
\value{
A \code{patchwork} object (class \code{wrap_plots}) with
\code{height} and \code{width} attributes (in inches).  When
\code{combine = FALSE}, a named list of such objects, one per
\code{split_by} level.
}
\description{
Draw two heatmaps side-by-side with spline link lines connecting matching
rows across the two heatmaps.  This is the public, exported interface for
creating linked-heatmap visualisations.

A typical use case is visualising ligand–receptor interactions: the
left heatmap shows ligand expression (rows = ligands, columns = cell
sources), the right heatmap shows receptor expression (rows = receptors,
columns = cell targets), and link curves connect each ligand to its
cognate receptor(s).
}
\section{Left / right specification}{

Parameters that differ between the two heatmaps are prefixed with
\code{left_} or \code{right_}.  Shared parameters (e.g. \code{palette},
\code{cell_type}, \code{cluster_columns}) apply to both sides but can be
overridden per-side via the \code{...} argument.  Every parameter listed
below can also be passed with a \code{left_} or \code{right_} prefix in
\code{...} for full per-side control.

The \code{...} argument is also forwarded to
\code{\link[ComplexHeatmap]{Heatmap}} after prefix-stripping, allowing
direct access to \code{ComplexHeatmap} parameters (e.g.
\code{left_row_names_gp}, \code{right_column_names_rot}).
}

\section{Split-by support}{

When \code{split_by} is provided, the data is partitioned into subsets
and an independent linked-heatmap pair is produced for each level.  The
results are combined via \code{\link[patchwork]{wrap_plots}} according to
\code{nrow}, \code{ncol}, \code{byrow}, and \code{design}.
Per-split \code{palette}, \code{palcolor}, and \code{legend.position} can
be specified as named lists keyed by split level.
}

\section{Dimension calculation}{

Cell dimensions are pre-computed from \code{cell_type},
\code{aspect.ratio}, \code{base_size}, and the unique row/column counts
in the data (accounting for split groups).  These exact dimensions are
passed to \code{ComplexHeatmap::Heatmap} so cells have guaranteed
physical sizes, ensuring that the two heatmaps' bodies align precisely
and that link line endpoints land on the correct rows.  The final
\code{height} / \code{width} attributes on the returned object include
legend space and are clamped to \eqn{[4, 64]} inches with aspect-ratio
correction.
}

\examples{
\donttest{
set.seed(8525)
# Define sparse ligand-receptor pairs
pairs_df <- data.frame(
    ligand = c("Ligand1", "Ligand2", "Ligand3", "Ligand4", "Ligand5",
               "Ligand1", "Ligand3", "Ligand5"),
    receptor = c("Receptor1", "Receptor2", "Receptor1", "Receptor3", "Receptor4",
                 "Receptor5", "Receptor2", "Receptor5"),
    stringsAsFactors = FALSE
)
sources <- paste0("Source", 1:4)
targets <- paste0("Target", 1:6)

# Expand pairs across all sources and targets
data <- merge(
    merge(pairs_df, data.frame(source = sources, stringsAsFactors = FALSE)),
    data.frame(target = targets, stringsAsFactors = FALSE)
)
data$split <- sample(c("A", "B"), nrow(data), replace = TRUE)
data$ligand_expr <- runif(nrow(data), 0, 10)
data$receptor_expr <- runif(nrow(data), 0, 10)
data$intensity <- runif(nrow(data), 0, 1)

if (requireNamespace("ComplexHeatmap", quietly = TRUE)) {
    LinkedHeatmap(
        data,
        show_column_names = TRUE,
        column_names_side = "bottom",
        show_row_names = FALSE,
        left_row_names_side = "right",
        left_rows_by = "ligand",
        left_columns_by = "source",
        left_values_by = "ligand_expr",
        left_name = "Ligand",
        left_row_annotation = list(
            .row = list(
                type = "label",
                params = list(labels_rot = 0),
                side = "right"
            )
        ),
        right_cluster_rows = FALSE,
        right_row_names_side = "left",
        right_row_annotation = list(
            .row = list(
                type = "label",
                params = list(labels_rot = 0),
                side = "left"
            )
        ),
        right_rows_by = "receptor",
        right_columns_by = "target",
        right_values_by = "receptor_expr",
        right_name = "Receptor",
        link_width_by = "intensity"
    )
}
}
}
\seealso{
\code{\link{Heatmap}}
}
