% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/plot-heatmap.R
\name{plot_heatmap}
\alias{plot_heatmap}
\title{Plot Network as Heatmap}
\usage{
plot_heatmap(
  x,
  cluster_list = NULL,
  cluster_spacing = 0,
  show_legend = TRUE,
  legend_position = "right",
  legend_title = "Weight",
  colors = "viridis",
  limits = NULL,
  midpoint = NULL,
  na_color = "grey90",
  show_values = FALSE,
  value_size = 2.5,
  value_color = "black",
  value_fontface = "plain",
  value_fontfamily = "sans",
  value_halo = NULL,
  value_digits = 2,
  show_diagonal = TRUE,
  diagonal_color = NULL,
  cluster_labels = TRUE,
  cluster_borders = TRUE,
  border_color = "black",
  border_width = 0.5,
  row_labels = NULL,
  col_labels = NULL,
  show_axis_labels = TRUE,
  axis_text_size = 8,
  axis_text_angle = 45,
  title = NULL,
  subtitle = NULL,
  xlab = NULL,
  ylab = NULL,
  threshold = 0,
  aspect_ratio = 1,
  ...
)
}
\arguments{
\item{x}{Network input: matrix, CographNetwork, tna, igraph, group_tna,
or any object cograph accepts.}

\item{cluster_list}{Optional list of character vectors defining node clusters.
Creates a block-structured heatmap with clusters along diagonal.}

\item{cluster_spacing}{Gap size between clusters (in cell units). Default 0.}

\item{show_legend}{Logical: display color legend? Default TRUE.}

\item{legend_position}{Position: "right" (default), "left", "top", "bottom", "none".}

\item{legend_title}{Title for legend. Default "Weight".}

\item{colors}{Color palette: vector of colors for gradient, or a palette name
("viridis", "heat", "blues", "reds", "diverging"). Default "viridis".}

\item{limits}{Numeric vector c(min, max) for color scale. NULL for auto.}

\item{midpoint}{Midpoint for diverging scales. NULL for auto (0 if data spans neg/pos).}

\item{na_color}{Color for NA values. Default "grey90".}

\item{show_values}{Logical: display values in cells? Default FALSE.}

\item{value_size}{Text size for cell values. Default 2.5.}

\item{value_color}{Color for cell value text. Default "black".}

\item{value_fontface}{Font face for values: "plain", "bold", "italic",
"bold.italic". Default "plain".}

\item{value_fontfamily}{Font family for values: "sans", "serif", "mono".
Default "sans".}

\item{value_halo}{Halo color behind value labels for readability on dark
cells. Set to a color (e.g., "white") to enable, or NULL (default) to
disable.}

\item{value_digits}{Decimal places for values. Default 2.}

\item{show_diagonal}{Logical: show diagonal values? Default TRUE.}

\item{diagonal_color}{Optional color for diagonal cells. NULL uses scale.}

\item{cluster_labels}{Logical: show cluster/layer labels? Default TRUE.}

\item{cluster_borders}{Logical: draw borders around clusters? Default TRUE.}

\item{border_color}{Color for cluster borders. Default "black".}

\item{border_width}{Width of cluster borders. Default 0.5.}

\item{row_labels}{Row labels. NULL for auto (rownames or indices).}

\item{col_labels}{Column labels. NULL for auto (colnames or indices).}

\item{show_axis_labels}{Logical: show axis tick labels? Default TRUE.}

\item{axis_text_size}{Size of axis labels. Default 8.}

\item{axis_text_angle}{Angle for x-axis labels. Default 45.}

\item{title}{Plot title. Default NULL.}

\item{subtitle}{Plot subtitle. Default NULL.}

\item{xlab}{X-axis label. Default NULL.}

\item{ylab}{Y-axis label. Default NULL.}

\item{threshold}{Minimum absolute value to display. Values with
\code{abs(value) < threshold} are set to zero. Default 0.}

\item{aspect_ratio}{Aspect ratio. Default 1 (square cells).}

\item{...}{Additional arguments (currently unused).}
}
\value{
A ggplot2 object.
}
\description{
Visualizes a network adjacency/weight matrix as a heatmap. Supports single
networks, multi-cluster networks (block diagonal), and multi-layer networks
(group_tna).
}
\details{
For multi-cluster networks, provide \code{cluster_list} as a named list where
each element is a vector of node names belonging to that cluster. The heatmap
will be reordered to show clusters as blocks along the diagonal.

For group_tna objects (multiple separate networks), each network becomes a
diagonal block. Off-diagonal blocks are empty (no inter-layer edges) unless
the networks share nodes.
}
\examples{
\dontrun{
# Single network
m <- matrix(runif(25), 5, 5)
rownames(m) <- colnames(m) <- LETTERS[1:5]
plot_heatmap(m)

# With clusters
clusters <- list(Group1 = c("A", "B"), Group2 = c("C", "D", "E"))
plot_heatmap(m, cluster_list = clusters)

# Custom colors and legend
plot_heatmap(m, colors = "heat", limits = c(0, 1), show_values = TRUE)
}

\dontrun{
# Multi-layer (group_tna) — requires tna package and sequence data
if (requireNamespace("tna", quietly = TRUE)) {
  mod <- tna::tna(tna::group_regulation)
  plot_heatmap(mod)
}
}

}
