% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/ggnetview_zipi.R
\name{ggnetview_zipi}
\alias{ggnetview_zipi}
\title{Compute Zi-Pi (within-module connectivity and participation coefficient)}
\usage{
ggnetview_zipi(
  nodes_bulk,
  z_bulk_mat,
  modularity_col,
  degree_col,
  zi_threshold = 2.5,
  pi_threshold = 0.62,
  na.rm = FALSE,
  point_colors = c(Peripherals = "#377eb8", Connectors = "#4daf4a", `Module hubs` =
    "#e41a1c", `Network hubs` = "#ff7f00"),
  bg_colors = c(Peripherals = "#b3cde3", Connectors = "#ccebc5", `Module hubs` =
    "#fbb4ae", `Network hubs` = "#fed9a6"),
  label_colors = c(Peripherals = "black", Connectors = "black", `Module hubs` = "black",
    `Network hubs` = "black"),
  label_size = 5.5,
  bg_alpha = 0.25
)
}
\arguments{
\item{nodes_bulk}{Data frame or tibble.
Node table with modularity and degree information.
Node IDs must be in \code{rownames} or in a \code{name} column (compatible
with \code{tidygraph::as_tibble} output).}

\item{z_bulk_mat}{Numeric matrix.
Adjacency or correlation matrix; rows and columns must correspond to nodes.
Non-zero entries are treated as edges. \code{NA}/\code{Inf} are replaced with 0.}

\item{modularity_col}{Character.
Column name in \code{nodes_bulk} containing module labels.}

\item{degree_col}{Character.
Column name in \code{nodes_bulk} containing node degree (number of edges).}

\item{zi_threshold}{Numeric (default = 2.5).
Threshold for within-module connectivity (Zi) in role classification.}

\item{pi_threshold}{Numeric (default = 0.62).
Threshold for among-module connectivity (Pi) in role classification.}

\item{na.rm}{Logical (default = \code{FALSE}).
If \code{TRUE}, remove rows with NA in Zi or Pi from the output.
If \code{FALSE}, keep all rows; NA in Zi/Pi results in \code{type = NA}.}

\item{point_colors}{Named character vector (or \code{NULL}).
Point/legend colours for the four node roles. Defaults to
\code{c("Peripherals" = "#377eb8", "Connectors" = "#4daf4a",
"Module hubs" = "#e41a1c", "Network hubs" = "#ff7f00")}.
You may override all four, a subset (by role name), or pass a single
colour to apply to every role.}

\item{bg_colors}{Named character vector (or \code{NULL}).
Background fill colours for the four quadrants, keyed by role. Defaults to
\code{c("Peripherals" = "#b3cde3", "Connectors" = "#ccebc5",
"Module hubs" = "#fbb4ae", "Network hubs" = "#fed9a6")}. Same override
rules as \code{point_colors}.}

\item{label_colors}{Named character vector or single colour (or \code{NULL}).
Colours for the four quadrant text labels, keyed by role. Defaults to
black for all four. Same override rules as \code{point_colors}.}

\item{label_size}{Numeric (default = 5.5).
Text size of the four quadrant labels.}

\item{bg_alpha}{Numeric (default = 0.25).
Opacity of the quadrant background shading (0 = transparent, 1 = opaque).}
}
\value{
A list with two elements:
  \itemize{
    \item \code{data}: Data frame merging \code{nodes_bulk} with
      \code{within_module_connectivities}, \code{among_module_connectivities},
      and \code{type} (node role).
    \item \code{plot}: ggplot object of the Zi-Pi scatter plot with quadrant
      labels and background shading.
  }
}
\description{
Calculates the within-module degree z-score (Zi) and among-module connectivity
(participation coefficient, Pi) for each node in a modular network.
These metrics classify nodes into roles such as module hubs, connectors,
and peripherals.
}
\details{
\strong{Zi (within-module connectivity):} Reflects how strongly a node is
connected within its own module. Higher values indicate the node has more
connections within the module and may play a core role inside it.

\strong{Pi (among-module connectivity):} Measures how much a node connects
to other modules. Higher values indicate the node acts as a bridge between
modules, facilitating information, material or energy flow across the network.

\strong{Node roles (by default thresholds Zi=2.5, Pi=0.62):}
\itemize{
  \item \code{Module hubs}: High Zi, low Pi. Core members within their module,
    important for module stability and function, but weakly connected to
    other modules.
  \item \code{Connectors}: Low Zi, high Pi. Not prominent within their module,
    but strongly connect across modules, acting as bridges.
  \item \code{Network hubs}: High Zi, high Pi. Core nodes both within and
    across modules, critical for overall network structure and stability.
  \item \code{Peripherals}: Low Zi, low Pi. Peripheral or satellite nodes
    with few connections within and across modules.
}
}
\examples{
\dontrun{
g <- build_graph_from_mat(otu_rare_relative, method = "WGCNA",
  transfrom.method = "none", cor.method = "pearson", proc = "Bonferroni",
  module.method = "Fast_greedy")
nodes_bulk <- get_graph_nodes(g)
adj_mat <- get_graph_adjacency(g)
res <- ggnetview_zipi(nodes_bulk, adj_mat, "Modularity", "Degree")
}
}
\references{
Guimera R, Amaral LAN (2005). "Functional cartography of complex metabolic
  networks." \emph{Nature} 433(7028):895-900.
}
