% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/ggnetview_modularity_heatmaps.R
\name{ggnetview_modularity_heatmaps}
\alias{ggnetview_modularity_heatmaps}
\title{Network + module-environment heatmaps with shared Mantel API}
\usage{
ggnetview_modularity_heatmaps(
  graph_obj,
  env,
  otu_mat,
  env_select = NULL,
  module_index = c("eigengene", "abundance"),
  abundance_type = c("sum", "mean"),
  relation_method = c("correlation", "mantel"),
  cor.method = c("pearson", "kendall", "spearman"),
  cor.use = c("everything", "all", "complete", "pairwise", "na"),
  mantel.method2 = c("pearson", "kendall", "spearman"),
  mantel_kind = c("block_vs_col", "col_vs_col"),
  spec_dist_method = "bray",
  env_dist_method = "euclidean",
  permutations = 999L,
  drop_nonsig = FALSE,
  layout = "gephi",
  layout.module = c("random", "adjacent", "order"),
  orientation = c("top_right", "bottom_right", "top_left", "bottom_left"),
  distance = 3,
  r = 6,
  HeatmapScale = 1,
  SigLineAlpha = 0.5,
  HeatmapLabelSize = 5,
  HeatmapSigSize = 5,
  HeatmapColorBar = NULL,
  HeatmapLabelOrient = 0,
  SigLineWidth = c(0.5, 2),
  SigLineColor = c("#fdbb84", "#d7301f"),
  HeatmapPointSize = 5,
  HeatmapPointFill = "#de77ae",
  HeatmapTileColor = NA,
  HeatmapTileSize = 0,
  ...
)
}
\arguments{
\item{graph_obj}{A \code{tbl_graph} (e.g. from \code{build_graph_from_mat}
or \code{build_graph_from_df}). Must have a node \code{name} attribute
and a module column (one of \code{"Modularity"}, \code{"modularity3"},
\code{"modularity2"}; auto-detected).}

\item{env}{Data frame or matrix of environmental variables. Rows are
samples (rownames matched against \code{otu_mat} columns), columns
are env factors.}

\item{otu_mat}{Numeric matrix. Rows = OTUs/ASVs (rownames matched
against \code{graph_obj} node names), columns = samples (colnames
matched against \code{env} rownames). Used to compute module
eigengenes / abundances and, in block-vs-col Mantel mode, to assemble
per-module community distance matrices.}

\item{env_select}{Named list (required). Column indices or names of
\code{env} that form each env block, one block per heatmap quadrant.
\code{length(env_select)} must equal \code{length(orientation)}. The
list names (\code{names(env_select)}) are used by
\code{comparisons_groups} and in the returned stats. Example:
\code{list(Env01 = 1:5, Env02 = 6:10, Env03 = 11:15, Env04 = 16:20)}.}

\item{module_index}{Character (default \code{"eigengene"}). How each
module is summarised into one per-sample value used downstream.
\code{"eigengene"} = PC1 of the module's OTU sub-matrix
(recommended); \code{"abundance"} = sum or mean of OTU abundances
within the module (controlled by \code{abundance_type}).}

\item{abundance_type}{Character (default \code{"sum"}). Only used when
\code{module_index = "abundance"}. Either \code{"sum"} or
\code{"mean"}.}

\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 (heatmap tiles)
and, when \code{relation_method = "correlation"}, for module-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.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_kind}{Character (default \code{"block_vs_col"}). Which
Mantel algorithm to use; see \strong{Details}. The same parameter is
exposed in \code{\link{gglink_heatmaps}}.}

\item{spec_dist_method}{Character (default \code{"bray"}). Dissimilarity
method (\code{vegan::vegdist}) used to convert a module's OTU
sub-matrix into ONE community distance matrix when
\code{mantel_kind = "block_vs_col"}.}

\item{env_dist_method}{Character (default \code{"euclidean"}). Distance
method (\code{vegan::vegdist}) used to convert each env column into
its own distance matrix when \code{relation_method = "mantel"}.}

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

\item{drop_nonsig}{Logical (default \code{FALSE}). If \code{TRUE},
non-significant links (p > 0.05) are removed from the plots; the
returned stats data frame is unaffected.}

\item{layout}{Character (default \code{"gephi"}). Layout passed to the
underlying \code{\link{ggNetView}} call (e.g. \code{"gephi"},
\code{"square"}, \code{"WGCNA"}).}

\item{layout.module}{Character (default \code{"random"}). Module
ordering strategy passed through to \code{\link{ggNetView}}. One of
\code{"random"}, \code{"adjacent"}, \code{"order"}.}

\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}.}

\item{distance}{Numeric (default \code{3}). Offset between the central
network's outer boundary and the env heatmaps. Positive pushes
heatmaps outward; \code{0} places them flush; negative values pull
them inward and may overlap the network.}

\item{r}{Numeric (default \code{6}). Effective radius for scaling the
central network.}

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

\item{SigLineAlpha}{Numeric in \code{[0, 1]} (default \code{0.5}).
Transparency for module-env link segments.}

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

\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}: built-in defaults.
  \item Length-2 named list \code{list(low = ..., high = ...)}:
    applied to all quadrants.
  \item List of length \code{length(orientation)}: each element is
    either \code{c(low, high)} or \code{list(low = ..., high = ...)}.
    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. Try 45 or 90 to avoid label
overlap.}

\item{SigLineWidth}{Numeric vector of length 2 (default
\code{c(0.5, 2)}). Min / max line width for module-env links; mapped
from \code{-log10(p-value)} so smaller p -> thicker line.}

\item{SigLineColor}{Character vector of length 2 (default
\code{c("#fdbb84", "#d7301f")}). Colour gradient for module-env
links, mapped from low / high correlation (or Mantel r).}

\item{HeatmapPointSize}{Numeric (default \code{5}). Point size for the
central module anchor where the heatmap link lands.}

\item{HeatmapPointFill}{Character (default \code{"#de77ae"}). Fill
colour for the central module anchor point.}

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

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

\item{...}{Additional arguments forwarded to the underlying
\code{\link{ggNetView}} network call. Commonly used:
\code{shrink}, \code{inner_shrink} (intra-module compactness, only
for \code{layout = "WGCNA"}), \code{jitter}, \code{add_outer},
\code{add_group_outer}, \code{label} (logical or character -- module
labels in ggNetView style), \code{labelsize},
\code{labelsegmentsize}, \code{labelsegmentalpha}, \code{fill},
\code{color}, \code{pointsize}.}
}
\value{
A list of length 3:
\describe{
  \item{\code{[[1]]}}{ggplot object with straight link segments
    (\code{geom_segment}).}
  \item{\code{[[2]]}}{ggplot object with curved link segments
    (\code{geom_curve}).}
  \item{\code{[[3]]}}{Data frame of module-env stats (unfiltered, not
    affected by \code{drop_nonsig}). Columns: \code{ID} (module name),
    \code{Type} (env column name), \code{Correlation}, \code{Pvalue},
    \code{p_signif}, \code{spec_block}, \code{env_block}, \code{method}
    (\code{"correlation"} or \code{"mantel"}). Schema is identical
    across all \code{relation_method} / \code{mantel_kind} combinations.}
}
}
\description{
Render a \code{ggNetView} network in the centre, surrounded by up to four
environmental-correlation heatmap quadrants, with link segments
connecting each module's anchor to the corresponding env-variable points
on the diagonals. Each module is represented by a single per-sample
summary (eigengene or abundance) for downstream statistics. Supports
both Pearson/Spearman/Kendall correlation and \code{vegan::mantel}
tests, and exposes the same Mantel API as
\code{\link{gglink_heatmaps}}.
}
\details{
\strong{Pipeline.}
\enumerate{
  \item Read module membership from \code{graph_obj} (the node attribute
    selected by the package's module column, e.g. \code{"Modularity"}).
  \item Build a per-sample module summary matrix \code{spec_df} of shape
    (samples x modules) using either \code{module_eigengene} (PC1 of the
    module's OTU sub-matrix; recommended) or \code{module_abundance}
    (sum / mean of OTU abundances inside the module).
  \item For each \code{(env_block, modules)} pair, compute either a
    correlation or a Mantel test (see \strong{Mantel API} below).
  \item Render the network via \code{\link{ggNetView}} (parameters
    forwarded through \code{...}), draw four heatmap quadrants for env-env
    correlations, and overlay link segments from module anchors to env
    diagonals.
}

\strong{Mantel API (shared with \code{\link{gglink_heatmaps}}).} Two
algorithms exposed via \code{mantel_kind}; both go through the helpers
in \code{\link{mantel_block_vs_col}} / \code{\link{mantel_pairwise}} so
the two top-level functions stay numerically identical:
\itemize{
  \item \code{"block_vs_col"} (default, ecological standard): for each
    module, the OTUs that belong to it are pulled out of \code{otu_mat}
    (transposed to samples x OTUs) and turned into ONE community
    distance matrix with \code{spec_dist_method}; each env column is
    turned into its own distance matrix with \code{env_dist_method};
    one Mantel test per (module, env_col).
  \item \code{"col_vs_col"} (legacy): the module's representative vector
    (eigengene or abundance) is treated as a single variable; its
    single-column distance matrix is tested against each env column's
    single-column distance matrix. Mathematically close to a rank
    correlation. Kept for backwards compatibility / sensitivity
    comparisons.
}
Prior versions of this function used the equivalent of
\code{"col_vs_col"} implicitly. The default has been switched to
\code{"block_vs_col"} (with a one-time \code{message()} on the first
Mantel call) to match the standard ecological interpretation; pass
\code{mantel_kind = "col_vs_col"} to reproduce the old numbers.

\strong{Output schema is stable across modes.} The returned stats data
frame always has columns \code{ID, Type, Correlation, Pvalue, p_signif,
spec_block, env_block, method}. \code{ID} is the module name in all
cases (\code{"M1"}, \code{"M2"}, ...), \code{Type} is the env column
name. This makes \code{drop_nonsig} and \code{comparisons_groups} work
identically across \code{relation_method} / \code{mantel_kind}
combinations.
}
\section{Data inputs}{

The graph carrying module assignments, the env data table that defines
the heatmap quadrants, the OTU abundance matrix used to summarise each
module, and the named list that partitions env into blocks.
}

\section{Module representation}{

How each module's per-sample value is computed before being correlated
with env: either as the eigengene (PC1 of the OTU sub-matrix) or as a
summary (sum / mean) of within-module abundances.
}

\section{Statistics -- correlation}{

Parameters that govern the env-env tile correlations and (when
\code{relation_method = "correlation"}) the module-env link
correlations: the correlation method and missing-value handling.
}

\section{Statistics -- Mantel}{

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

\section{What gets analysed / drawn}{

Filters and selectors that decide what ends up on the plot: dropping
non-significant links, and which heatmap quadrants are rendered.
}

\section{Geometry}{

Spatial parameters that position the env heatmaps relative to the
central network and select the network's own layout: heatmap offset,
network radius, overall heatmap scale, and the layout/module-ordering
choices forwarded to \code{ggNetView()}.
}

\section{Heatmap aesthetics}{

Visual styling of the env-env heatmap tiles: per-quadrant colour
palettes, label and significance-mark sizes, label rotation, the
central anchor point on each heatmap, and tile border styling.
}

\section{Link line aesthetics}{

Visual styling of the module-env link segments: line-width range
(mapped from p-value), colour gradient (mapped from correlation /
Mantel r), and overall transparency.
}

\section{Forwarded to ggNetView}{

Extra arguments captured via \code{...} and forwarded verbatim to the
underlying \code{\link{ggNetView}} call. Use them to customise the
central network's appearance (labels, fills, jitter, outer rings,
point sizes) without leaving this wrapper.
}

\examples{
\dontrun{
# Default: correlation, eigengene as module summary, four quadrants.
p <- ggnetview_modularity_heatmaps(
  graph_obj  = g,
  env        = env,
  otu_mat    = otu_mat,
  env_select = list(Env01 = 1:5, Env02 = 6:10,
                    Env03 = 11:15, Env04 = 16:20)
)
p[[1]]            # straight links
head(p[[3]])      # stats data frame

# Ecologically standard Mantel: one test per (module, env_col).
p2 <- ggnetview_modularity_heatmaps(
  graph_obj        = g,
  env              = env,
  otu_mat          = otu_mat,
  env_select       = list(Env01 = 1:5, Env02 = 6:10,
                          Env03 = 11:15, Env04 = 16:20),
  relation_method  = "mantel",
  mantel_kind      = "block_vs_col",
  spec_dist_method = "bray",
  env_dist_method  = "euclidean",
  permutations     = 999
)

# Reproduce legacy column-vs-column Mantel results.
p3 <- ggnetview_modularity_heatmaps(
  graph_obj       = g,
  env             = env,
  otu_mat         = otu_mat,
  env_select      = list(Env01 = 1:5, Env02 = 6:10,
                         Env03 = 11:15, Env04 = 16:20),
  relation_method = "mantel",
  mantel_kind     = "col_vs_col"
)
}
}
\seealso{
\code{\link{gglink_heatmaps}} for the spec-select counterpart that
shares the same Mantel API;
\code{\link{mantel_block_vs_col}}, \code{\link{mantel_pairwise}} for
the underlying Mantel implementations;
\code{\link{ggNetView}} for the central network rendering and the
parameters forwarded via \code{...}.
}
