% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/gglink_heatmaps.R
\name{gglink_heatmaps}
\alias{gglink_heatmaps}
\title{Multi-orientation species-environment correlation / Mantel heatmap}
\usage{
gglink_heatmaps(
  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"),
  spec_dist_method = "bray",
  env_dist_method = "euclidean",
  mantel_kind = c("block_vs_col", "col_vs_col"),
  permutations = 999L,
  spec_collapse = FALSE,
  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"),
  SigLineMid = NULL,
  link_color_by = "Correlation",
  link_width_by = "-log10(Pvalue)",
  NonsigLineColor = "grey80",
  NonsigLineType = "dashed",
  sig_threshold = 0.05,
  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", "arc"),
  group_angle = 0,
  group_arc_angle = pi/2,
  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{spec_dist_method}{Character (default \code{"bray"}). Dissimilarity
method (passed to \code{vegan::vegdist}) used to convert the spec
block into ONE community distance matrix when
\code{mantel_kind = "block_vs_col"}.}

\item{env_dist_method}{Character (default \code{"euclidean"}). Distance
method used to convert each env column into its own distance matrix
under any \code{mantel_kind}.}

\item{mantel_kind}{Character (default \code{"block_vs_col"}). Which
Mantel variant to use; see \strong{Details}. Same parameter is exposed
in \code{\link{ggnetview_modularity_heatmaps}}.}

\item{permutations}{Integer (default \code{999L}). Number of permutations
passed to \code{vegan::mantel}.}

\item{spec_collapse}{Logical (default \code{FALSE}). If \code{TRUE}, each
block is rendered as ONE labelled point at its anchor position; the
point's label is the block name from \code{names(spec_select)}.
In this mode, \code{spec_layout}, \code{spec_relation},
\code{scale_networks} are all ignored, and link sources are always the
collapsed point regardless of \code{relation_method}. Pairs naturally
with \code{relation_method = "mantel"} +
\code{mantel_kind = "block_vs_col"}.}

\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{SigLineMid}{Character or \code{NULL} (default \code{NULL}). If
\code{NULL}, link colour uses \code{ggplot2::scale_colour_gradient(low,
high)} -- no centred midpoint, suitable when the mapped variable is
one-sided (e.g. \code{"Pvalue"}, \code{"-log10(Pvalue)"},
\code{"abs(Correlation)"}). If a single colour string (e.g.
\code{"white"}), link colour switches to
\code{ggplot2::scale_colour_gradient2(low, mid, high, midpoint = 0)}
-- recommended when \code{link_color_by = "Correlation"} and the
values span both signs.}

\item{link_color_by}{Character string (default \code{"Correlation"}).
An R expression, written as a string, that is parsed via
\code{rlang::parse_expr} and evaluated against the link data frame to
produce the values mapped to link line colour. Accepts a bare column
name (\code{"Correlation"}, \code{"Pvalue"}) or any numeric expression
of the available columns (see \strong{Details} for the full list).
Common choices:
\itemize{
  \item \code{"Correlation"} -- signed effect size; pair with
    \code{SigLineMid = "white"} for a diverging palette around 0.
  \item \code{"abs(Correlation)"} -- unsigned effect size.
  \item \code{"-log10(Pvalue)"} -- significance strength (large = more
    significant).
}
The expression must yield a numeric vector with one entry per link
row; otherwise the function errors out and lists the available
numeric columns. Only significant links (\code{Pvalue <=
sig_threshold}) flow through this colour scale; non-significant links
are drawn flat in \code{NonsigLineColor}.}

\item{link_width_by}{Character string (default \code{"-log10(Pvalue)"}).
An R expression (string) evaluated against the link data frame to
produce the values mapped to link line width. Same syntax and
evaluation rules as \code{link_color_by}; same set of available
columns. Common choices: \code{"-log10(Pvalue)"} (default; significance
strength), \code{"abs(Correlation)"}, \code{"Correlation^2"}. Only
significant links participate in this width scale; non-significant
links are drawn at \code{min(SigLineWidth)} as a flat background.}

\item{NonsigLineColor}{Character (default \code{"grey80"}). Fixed colour
for non-significant link segments (\code{Pvalue > sig_threshold}). Only
used when \code{drop_nonsig = FALSE}.}

\item{NonsigLineType}{Character (default \code{"dashed"}). Line type for
non-significant link segments. Any value accepted by ggplot2's
\code{linetype} aesthetic (e.g. \code{"solid"}, \code{"dashed"},
\code{"dotted"}).}

\item{sig_threshold}{Numeric in \code{(0, 1)} (default \code{0.05}).
P-value threshold separating significant from non-significant links.
Used to (a) decide which links go through the colour/width scales,
(b) drive \code{drop_nonsig} filtering.}

\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{group_angle}{Numeric (default \code{0}). Extra rotation applied to
the entire anchor set, on top of \code{group_layout}'s default
orientation. Accepts radians (\code{|x| <= 2*pi}) or degrees
(\code{|x| > 2*pi}); use \code{\link{deg}(x)} to force a small value
to mean degrees. Examples: \code{group_angle = 45} tilts a row by 45 degrees;
\code{group_angle = pi/2} turns a row into a column.}

\item{group_arc_angle}{Numeric (default \code{pi/2}). Only used when
\code{group_layout = "arc"}. Central angle subtended by the arc.
\code{0} degenerates to a flat row; \code{pi/2} (= 90 degrees) is a
quarter-circle (default); \code{pi} is a half-circle. Negative values
flip the arc to the opposite side. Same unit auto-detection as
\code{group_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:
\describe{
  \item{\code{[[1]]}}{A \code{ggplot} object with straight link segments
    (rendered with \code{ggplot2::geom_segment}).}
  \item{\code{[[2]]}}{A \code{ggplot} object with curved link segments
    (rendered with \code{ggplot2::geom_curve}, curvature \code{0.25}).}
  \item{\code{[[3]]}}{A data frame of the full spec-env statistics,
    \strong{unfiltered} (not affected by \code{drop_nonsig} or
    \code{sig_threshold}). Columns: \code{ID}, \code{Type},
    \code{Correlation}, \code{Pvalue}, \code{p_signif} (one of
    \code{""}, \code{"*"}, \code{"**"}, \code{"***"} at the fixed
    0.05 / 0.01 / 0.001 cutoffs), \code{spec_block}, \code{env_block},
    \code{method} (\code{"correlation"} or \code{"mantel"}). For
    \code{mantel_kind = "block_vs_col"}, \code{ID} is the spec_block
    name; otherwise \code{ID} is the spec column name.}
}
Both ggplot objects can be post-processed with the usual ggplot2 idioms
(\code{+ ggplot2::labs(...)}, \code{+ ggplot2::theme(...)}, etc.).
}
\description{
Render a "central species network(s)" surrounded by up to four
environmental-correlation heatmap quadrants, with curved or straight link
segments connecting each spec node (or each spec block) to each env
variable. Supports both Pearson/Spearman/Kendall correlation and
\code{vegan::mantel} tests, and exposes a unified Mantel API
(\code{mantel_kind = "block_vs_col" | "col_vs_col"}) shared with
\code{\link{ggnetview_modularity_heatmaps}}. Link line colour and width
are user-configurable through expression strings (\code{link_color_by},
\code{link_width_by}); non-significant links are rendered as a separate
flat-grey background layer for visual context.
}
\details{
\strong{Layered geometry.} The plot is built in three nested layers:
\enumerate{
  \item \strong{Single network geometry} (per spec block) controlled by
    \code{spec_layout} / \code{spec_orientation} -- how nodes inside one
    block are arranged.
  \item \strong{Group geometry} (across spec blocks) controlled by
    \code{group_layout} / \code{group_angle} / \code{group_arc_angle} /
    \code{anchor_dist} -- how the per-block anchors are scattered on the
    canvas.
  \item \strong{Heatmap geometry} (around the centre) controlled by
    \code{orientation} / \code{distance} / \code{HeatmapScale} -- where the
    four env heatmap quadrants sit relative to the central group.
}

\strong{Two collapse modes for \code{spec_select}.}
\itemize{
  \item \code{spec_collapse = FALSE} (default): each block is drawn as a
    small network and each spec column has its own node. Link sources are
    per-column nodes (correlation / col_vs_col mantel) or block centroids
    (block_vs_col mantel).
  \item \code{spec_collapse = TRUE}: each block becomes ONE labelled
    point at its anchor position. Pairs naturally with
    \code{relation_method = "mantel"} + \code{mantel_kind = "block_vs_col"},
    where one block = one statistical unit.
}

\strong{Mantel API.} Two algorithms exposed via \code{mantel_kind} and
shared with \code{\link{ggnetview_modularity_heatmaps}}:
\itemize{
  \item \code{"block_vs_col"} (default, ecological standard, linkET / ggcor
    style): the whole spec block becomes ONE community-distance matrix
    (\code{vegan::vegdist} with \code{spec_dist_method}); each env column
    becomes its own distance matrix (\code{env_dist_method}); one Mantel
    test per (spec_block, env_col). See \code{\link{mantel_block_vs_col}}.
  \item \code{"col_vs_col"} (legacy, kept for sensitivity / backwards
    compatibility): each spec column and each env column is reduced to a
    single-column distance matrix; the resulting "Mantel" is mathematically
    close to a rank correlation. See \code{\link{mantel_pairwise}}.
}

\strong{Angle inputs.} \code{group_angle} and \code{group_arc_angle}
auto-detect their unit from the magnitude: \code{|x| <= 2*pi} is taken as
radians, \code{|x| > 2*pi} as degrees. Use \code{\link{deg}} to force a
small value to mean degrees (e.g. \code{deg(5)} = 5 degrees).

\strong{Link line styling.} Spec-env links are rendered in two stacked
layers controlled by \code{sig_threshold}:
\itemize{
  \item \strong{Significant layer} (\code{Pvalue <= sig_threshold}):
    colour and width are mapped from user-supplied expressions
    \code{link_color_by} and \code{link_width_by} (each a string like
    \code{"Correlation"}, \code{"-log10(Pvalue)"}, or
    \code{"abs(Correlation)"}). The colour gradient endpoints come from
    \code{SigLineColor}; pass \code{SigLineMid} (e.g. \code{"white"}) to
    switch to a diverging \code{scale_colour_gradient2(midpoint = 0)},
    recommended whenever the mapped variable can be negative (signed
    correlations). The width scale range comes from \code{SigLineWidth}.
  \item \strong{Non-significant layer} (\code{Pvalue > sig_threshold}):
    drawn flat in \code{NonsigLineColor} (default light grey) with line
    type \code{NonsigLineType} (default dashed) at the minimum of
    \code{SigLineWidth}, purely as visual context. This layer is omitted
    when \code{drop_nonsig = TRUE}.
}
Both layers share \code{SigLineAlpha}. Because non-significant links do
not participate in the colour/width scales, the legends only reflect
the significant layer.

\strong{Available columns for link expressions.} \code{link_color_by}
and \code{link_width_by} are evaluated against the link data frame,
which contains the spec-env stat columns plus link-source / link-target
coordinates: \code{ID}, \code{Type}, \code{Correlation}, \code{Pvalue},
\code{p_signif}, \code{spec_block}, \code{env_block}, \code{method},
\code{is_sig}, plus \code{x}, \code{y}, \code{x_to}, \code{y_to}. Most
users will only build expressions from \code{Correlation} and
\code{Pvalue}.
}
\section{Data inputs}{

Matrices and block selectors that drive the whole computation: the env
and spec data tables plus the named lists that partition each into
visual blocks (heatmap quadrants and central networks).
}

\section{Per-block (spec) geometry}{

Controls how nodes are arranged inside one spec block: the layout shape
(e.g. circle vs diamond outline), its base orientation, whether the
block is collapsed to a single labelled point, and how its visual
radius scales.
}

\section{Across-block (group) geometry}{

Controls how the per-block anchors are scattered across the figure:
the macro arrangement (circle / row / arc / ...), its rotation, the
anchor-to-anchor spacing, and any grid dimensions when applicable.
}

\section{Heatmap geometry}{

Where the env-env heatmaps are placed and scaled relative to the
central spec blocks: which quadrants are drawn, how far the heatmaps
sit from the centre, and an overall size multiplier.
}

\section{Statistics -- correlation}{

Parameters that govern the env-env and (when
\code{relation_method = "correlation"}) spec-env correlation pipeline:
the correlation method, missing-value handling, and the choice between
correlation and Mantel as the spec-env relation.
}

\section{Statistics -- Mantel}{

Parameters used only when \code{relation_method = "mantel"}: the
Mantel variant, the dissimilarity / distance metrics applied to the
spec block and env columns, the Mantel correlation method, and the
permutation count.
}

\section{What gets analysed}{

Switches that decide which (env_block, spec_block) pairs are
actually computed and drawn -- the master on/off, the optional
restriction list, and the rule for hiding non-significant links.
}

\section{Heatmap aesthetics}{

Visual styling of the env-env heatmap tiles and labels: per-quadrant
colour palettes, label and significance-mark sizes, label rotation,
tile borders, and the diagonal anchor points where link lines land.
}

\section{Central node aesthetics}{

Visual styling of the central spec nodes (or the collapsed block
points when \code{spec_collapse = TRUE}): point size and per-block
fill colour.
}

\section{Link line aesthetics}{

Visual styling of the spec-env link segments: which numeric
expression drives the colour and width scales for significant
links, the colour endpoints and optional centred midpoint, line
widths, transparency, and the separate styling for non-significant
links.
}

\section{Deprecated / unused parameters}{

These arguments are kept in the signature for backwards compatibility
with old call sites but are NOT consumed by the active code path. They
may be removed in a future release.
}

\examples{
\dontrun{
# Minimal call (defaults: correlation, no collapse).
p <- gglink_heatmaps(
  env  = env,
  spec = spec,
  env_select  = list(Env01 = 1:14, Env02 = 15:28,
                     Env03 = 29:42, Env04 = 43:56),
  spec_select = list(Spec01 = 1:15, Spec02 = 16:30)
)
p[[1]]   # straight links
p[[2]]   # curved links
head(p[[3]])

# Ecologically standard Mantel + collapse each block to one point.
p2 <- gglink_heatmaps(
  env  = env,
  spec = spec,
  env_select  = list(Env01 = 1:14, Env02 = 15:28,
                     Env03 = 29:42, Env04 = 43:56),
  spec_select = list(Spec01 = 1:15, Spec02 = 16:30),
  relation_method  = "mantel",
  mantel_kind      = "block_vs_col",
  spec_dist_method = "bray",
  env_dist_method  = "euclidean",
  spec_collapse    = TRUE,
  group_layout     = "row",
  group_angle      = 45,            # degrees, auto-detected
  anchor_dist      = 4,
  distance         = -1,            # heatmaps pulled slightly inward
  CorePointFill    = c("#2166ac", "#b2182b"),
  CorePointSize    = 10
)
p2[[1]]

# Customise link aesthetics with R expressions passed as strings: colour
# by signed correlation (with a centred diverging palette), width by the
# absolute effect size, drop non-significant links, and tighten the
# threshold. Any string parseable as an expression of the link data
# frame's columns is accepted.
p3 <- gglink_heatmaps(
  env  = env,
  spec = spec,
  env_select  = list(Env01 = 1:14, Env02 = 15:28,
                     Env03 = 29:42, Env04 = 43:56),
  spec_select = list(Spec01 = 1:15, Spec02 = 16:30),
  link_color_by = "Correlation",
  link_width_by = "abs(Correlation)",
  SigLineColor  = c("#2166ac", "#b2182b"),
  SigLineMid    = "white",
  sig_threshold = 0.01,
  drop_nonsig   = TRUE
)
p3[[2]]
}
}
\seealso{
\code{\link{ggnetview_modularity_heatmaps}} for the modularity-based
counterpart with the same Mantel API;
\code{\link{mantel_block_vs_col}}, \code{\link{mantel_pairwise}} for the
underlying Mantel implementations;
\code{\link{deg}} to make a numeric explicitly mean degrees in
\code{group_angle} / \code{group_arc_angle}.
}
