% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/gglink_heatmaps_2.R
\name{gglink_heatmaps_2}
\alias{gglink_heatmaps_2}
\title{Visualize multi-orientation environmental-species correlation heatmaps (adaptive sizing)}
\usage{
gglink_heatmaps_2(
  env,
  spec,
  env_select = NULL,
  spec_select = NULL,
  spec_layout = "circle_outline",
  spec_orientation = c("up", "down", "left", "right"),
  spec_relation = TRUE,
  relation_method = c("correlation", "mantel"),
  cor.method = c("pearson", "kendall", "spearman"),
  cor.use = c("everything", "all", "complete", "pairwise", "na"),
  mantel.method = c("mantel", "mantel.partial", "mantelhaen.test", "mantel.correlog"),
  mantel.method2 = c("pearson", "kendall", "spearman"),
  mantel.alternative = c("two.sided", "less", "greater"),
  drop_nonsig = FALSE,
  comparisons = TRUE,
  comparisons_groups = NULL,
  shape = 22,
  distance = 3,
  HeatmapLabelSize = 5,
  HeatmapSigSize = 5,
  HeatmapColorBar = NULL,
  HeatmapLabelOrient = 0,
  SigLineWidth = c(0.5, 2),
  SigLineColor = c("#fdbb84", "#d7301f"),
  HeatmapPointSize = 5,
  CorePointSize = 8.5,
  HeatmapPointFill = "#de77ae",
  CorePointFill = "#41b6c4",
  HeatmapTileColor = NA,
  HeatmapTileSize = 0,
  HeatmapScale = 1,
  SigLineAlpha = 0.5,
  fontsize = 5,
  orientation = c("top_right", "bottom_right", "top_left", "bottom_left"),
  r = 6,
  group_layout = c("circle", "row", "column", "square", "diamond", "triangle",
    "triangle_down", "snake"),
  anchor_dist = 6,
  scale_networks = TRUE,
  nrow = NULL,
  ncol = NULL
)
}
\arguments{
\item{env}{Data frame or matrix. Environmental variables, one column per
factor, one row per sample. Row order must match \code{spec}.}

\item{spec}{Data frame or matrix. Species abundance / trait data, one
column per species (or taxonomic unit), one row per sample. Row order
must match \code{env}.}

\item{env_select}{Named list (required). Each element gives the column
indices or names of \code{env} that form one environmental block; each
block becomes one heatmap quadrant. The list length must equal
\code{length(orientation)}. Block names (used for
\code{comparisons_groups}) come from \code{names(env_select)}, e.g.
\code{list(Env01 = 1:14, Env02 = 15:28, Env03 = 29:42, Env04 = 43:56)}.}

\item{spec_select}{Named list (required). Each element gives the column
indices or names of \code{spec} that form one species block. Each block
is rendered as one central network (or one collapsed point if
\code{spec_collapse = TRUE}). Block names come from
\code{names(spec_select)}, e.g. \code{list(Spec01 = 1:15, Spec02 = 16:30)}.}

\item{spec_layout}{Character or character vector (default
\code{"circle_outline"}). Shape of the per-block node layout. Length 1
applies to all blocks; a vector must have length equal to
\code{length(spec_select)} and is matched element-wise. Valid values:
\code{"circle_outline"}, \code{"diamond_outline"},
\code{"rectangle_outline"}, \code{"square_outline"}.
Ignored when \code{spec_collapse = TRUE}.}

\item{spec_orientation}{Character (default \code{"up"}). Base orientation
passed to the per-block layout function. One of \code{"up"},
\code{"down"}, \code{"left"}, \code{"right"}.}

\item{spec_relation}{Logical (default \code{TRUE}). Whether to compute
within-block species-species correlations to drive the per-block layout
(e.g. modularity of \code{"circle_outline"}). Set \code{FALSE} for a
geometry-only layout. Ignored when \code{spec_collapse = TRUE}.}

\item{relation_method}{Character (default \code{"correlation"}). One of
\code{"correlation"} or \code{"mantel"}.}

\item{cor.method}{Character (default \code{"pearson"}). Correlation
method used by \code{psych::corr.test} for env-env (the heatmap tiles)
and, when \code{relation_method = "correlation"}, for spec-env links.
One of \code{"pearson"}, \code{"kendall"}, \code{"spearman"}.}

\item{cor.use}{Character (default \code{"everything"}). Missing-value
handling for \code{psych::corr.test}. One of \code{"everything"},
\code{"all"}, \code{"complete"}, \code{"pairwise"}, \code{"na"}.}

\item{mantel.method}{Character. Reserved for future use -- currently
accepted for backwards compatibility but \strong{not} consumed by the
active code path (only \code{vegan::mantel} via \code{mantel.method2}
is used).}

\item{mantel.method2}{Character (default \code{"pearson"}). Correlation
coefficient passed to \code{vegan::mantel} as its \code{method}
argument. One of \code{"pearson"}, \code{"kendall"},
\code{"spearman"}.}

\item{mantel.alternative}{Character. Same status as \code{mantel.method}
-- accepted but not consumed.}

\item{drop_nonsig}{Logical (default \code{FALSE}). If \code{TRUE},
non-significant links (\code{Pvalue > sig_threshold}) are removed
from the plot but kept in the returned stats data frame.}

\item{comparisons}{Logical (default \code{TRUE}). Master switch for
spec-env analysis. \code{FALSE} skips all spec-env stats and links
(only the env-env heatmaps remain).}

\item{comparisons_groups}{List or NULL (default \code{NULL}). When
\code{comparisons = TRUE}, restricts which (env_block, spec_block)
pairs are computed and drawn. Each element is a length-2 character
vector \code{c(env_block_name, spec_block_name)}; names must match
\code{names(env_select)} / \code{names(spec_select)}. \code{NULL}
means "all pairs". Example:
\code{list(c("Env01","Spec01"), c("Env02","Spec02"))}.}

\item{shape}{Integer (default \code{22}). Reserved; the rendered point
shapes are currently hard-coded to \code{21} internally.}

\item{distance}{Numeric (default \code{3}). Offset added between the
central node group and the env heatmaps. Positive pushes heatmaps
outward; \code{0} places them flush against the central group;
\strong{negative values are allowed} and will pull heatmaps inward
(may visually overlap the central points). A \code{message()} is
emitted on negative values, and a \code{warning()} is emitted if the
value is so negative that an anchor coordinate becomes \eqn{\le 0}
(the heatmap will then flip to the opposite side).}

\item{HeatmapLabelSize}{Numeric (default \code{5}). Text size for
heatmap row/column labels (ID/Type).}

\item{HeatmapSigSize}{Numeric (default \code{5}). Text size for the
significance marks (\code{*}, \code{**}, \code{***}) inside heatmap
tiles.}

\item{HeatmapColorBar}{\code{NULL} or list (default \code{NULL}).
Per-quadrant colour palettes. Three accepted forms:
\itemize{
  \item \code{NULL}: use built-in defaults.
  \item Length-2 named list \code{list(low = ..., high = ...)}: applied
    to all quadrants (each value can be a vector that is recycled).
  \item List of length \code{length(orientation)}: each element is
    either \code{c(low, high)} or \code{list(low = ..., high = ...)}
    for that quadrant in order. Example:
    \code{list(c("#2166ac","#b2182b"), c("#1b7837","#762a83"),
               c("#4393c3","#d6604d"), c("#92c5de","#f4a582"))}.
}}

\item{HeatmapLabelOrient}{Numeric (default \code{0}). Rotation angle (in
degrees) for heatmap row/column labels. Use 45 or 90 to avoid label
overlap.}

\item{SigLineWidth}{Numeric vector of length 2 (default \code{c(0.5, 2)}).
Min and max line width for the significant spec-env link segments
(mapped through \code{link_width_by}). The minimum is also used as the
fixed width for non-significant background lines.}

\item{SigLineColor}{Character vector of length 2 (default
\code{c("#fdbb84", "#d7301f")}). Colour gradient endpoints (low, high)
for the significant spec-env link segments (mapped through
\code{link_color_by}).}

\item{HeatmapPointSize}{Numeric (default \code{5}). Point size for the
diagonal anchor points on each heatmap (where the link lines land).}

\item{CorePointSize}{Numeric (default \code{8.5}). Point size for the
central species nodes (or collapsed block points).}

\item{HeatmapPointFill}{Character vector (default \code{"#de77ae"}).
Fill colour(s) for the heatmap diagonal points.
\itemize{
  \item Length 1: same colour for all quadrants.
  \item Length \code{length(orientation)}: one colour per quadrant, in
    the order given by \code{orientation}.
  \item Other lengths: recycled (modulo) over quadrants.
}}

\item{CorePointFill}{Character vector (default \code{"#41b6c4"}). Fill
colour(s) for the central species nodes.
\itemize{
  \item Length 1: same colour for everyone.
  \item Length \code{length(spec_select)}: one colour per spec block,
    in the order of \code{names(spec_select)}.
  \item Other lengths: recycled (modulo) over spec blocks.
}}

\item{HeatmapTileColor}{Character or \code{NA} (default \code{NA}).
Border colour for heatmap tiles (passed to \code{geom_tile(colour =
...)}).}

\item{HeatmapTileSize}{Numeric (default \code{0}). Border line width for
heatmap tiles.}

\item{HeatmapScale}{Numeric (default \code{1}). Global scale for the
overall heatmap layout (tile spacing). \code{>1} enlarges, \code{<1}
shrinks.}

\item{SigLineAlpha}{Numeric in \code{[0, 1]} (default \code{0.5}).
Transparency of spec-env link segments (applied to both the significant
and non-significant layers).}

\item{fontsize}{Numeric (default \code{5}). Deprecated. Use
\code{HeatmapLabelSize} (which now also drives the central species
node label size).}

\item{orientation}{Character vector (default
\code{c("top_right","bottom_right","top_left","bottom_left")}). Which
heatmap quadrants to draw, in the same order as \code{env_select}'s
elements (i.e. \code{env_select[[1]]} -> \code{orientation[1]}).}

\item{r}{Numeric (default 6). Effective radius of a single central
network (in plot units). When \code{spec_collapse = TRUE} this only
affects how compact a single block looks before being collapsed and is
essentially cosmetic.}

\item{group_layout}{Character (default \code{"circle"}). Arrangement of
the per-block anchors when \code{spec_select} has multiple elements.
One of \code{"circle"}, \code{"row"}, \code{"column"},
\code{"square"}, \code{"diamond"}, \code{"triangle"},
\code{"triangle_down"}, \code{"snake"}, \code{"arc"}. \code{"arc"}
places anchors on a circular arc whose chord has the same row-like
footprint; curvature is controlled by \code{group_arc_angle}.}

\item{anchor_dist}{Numeric (default \code{6}). Spacing of the anchor
layout. For \code{row / column / snake} this is the centre-to-centre
distance between adjacent anchors; for \code{circle / square /
diamond / triangle} it is the radius from origin to each anchor; for
\code{arc} it is the chord-projected spacing (chord length =
\code{(n_blocks - 1) * anchor_dist}).}

\item{scale_networks}{Logical (default \code{TRUE}). If \code{TRUE},
normalise each per-block network to the same visual radius
(\code{r}); if \code{FALSE}, \code{r} is the minimum network radius and
larger networks scale proportionally to node count. Ignored when
\code{spec_collapse = TRUE}.}

\item{nrow, ncol}{Integer or NULL (default \code{NULL}). Grid dimensions
for \code{group_layout = "row" | "column" | "snake"}. If both are
NULL, defaults are inferred from the layout choice.}
}
\value{
A list of length 3:
- [[1]]: ggplot object with straight link segments.
- [[2]]: ggplot object with curved link segments.
- [[3]]: data.frame of full species-environment correlation statistics
         (unfiltered, not affected by \code{drop_nonsig}), with columns
         \code{ID}, \code{Type}, \code{Correlation}, \code{Pvalue}, \code{spec_block},
         \code{env_block}, and \code{method} (e.g. \code{"correlation"} or \code{"mantel"}).
}
\description{
An improved version of \code{\link{gglink_heatmaps}} that sizes each heatmap
quadrant independently according to its own number of variables.
All tiles share the same size; larger env blocks simply extend further.
The central species network is always kept at the centre of the canvas.
}
\examples{
\dontrun{
# Adaptive-sized variant of `gglink_heatmaps()`.
p <- gglink_heatmaps_2(
  env  = env,
  spec = spec
)
}
}
