R/average_interlayer_clustering_coefficient.R

In MultiTraits: Analyzing and Visualizing Multidimensional Plant Traits

#' Calculate Average Interlayer Clustering Coefficient
#'
#' @title Average Interlayer Clustering Coefficient for Plant Trait Multilayer Networks
#'
#' @description
#' Computes the Average Interlayer Clustering Coefficient (AICC) for a plant trait
#' multilayer network (PTMN). The AICC is the mean interlayer clustering coefficient
#' across all nodes in the network, capturing the overall prevalence of tightly knit
#' cross-layer modules. High AICC values indicate that integrated, modular
#' cross-layer structures are prevalent, reflecting strong phenotypic integration and
#' modularity, which can allow flexible responses to multidimensional environmental
#' pressures.
#'
#' @param data A PTMN object created by the \code{PTMN()} function, containing the
#'   multilayer network structure with nodes representing plant traits and edges
#'   representing trait relationships within and across functional layers.
#'
#' @return A numeric value representing the average interlayer clustering coefficient.
#'   Values range from 0 to 1, where higher values indicate stronger cross-layer
#'   integration and more tightly connected functional modules.
#'
#' @details
#' The Average Interlayer Clustering Coefficient is calculated as:
#'
#' \deqn{AICC = \frac{1}{n} \sum_{i=1}^{n} ICC_i}
#'
#' where \eqn{n} is the total number of nodes and \eqn{ICC_i} denotes the interlayer clustering
#' coefficient of node \eqn{v_i}. This parameter is particularly useful for
#' understanding multidimensional plant adaptations and coordinated responses across
#' different plant organs and functional systems.
#'
#' In the context of plant ecology, higher AICC values suggest that plants have
#' evolved integrated trait networks that facilitate coordinated responses to
#' environmental challenges. For example, non-native woody species have been shown
#' to exhibit higher AICC values compared to native species, potentially contributing
#' to their invasion success.
#'
#' @examples
#' \dontrun{
#' data(forest_invader_tree)
#' data(forest_invader_traits)
#' traits <- forest_invader_traits[, 6:73]
#' layers <- list(
#'   shoot_dynamics = c("LeafDuration", "LeafFall50", "LeafRate_max",
#'                      "Chl_shade50", "LAgain", "FallDuration",
#'                      "LeafOut", "Chl_sun50", "EmergeDuration",
#'                      "LeafTurnover"),
#'   leaf_structure = c("PA_leaf", "Mass_leaf", "Lifespan_leaf",
#'                      "Thick_leaf", "SLA", "Lobe", "LDMC",
#'                      "Stomate_size", "Stomate_index"),
#'   leaf_metabolism = c("J_max", "Vc_max", "Asat_area", "CC_mass",
#'                       "LSP", "AQY", "CC_area", "Rd_area",
#'                       "Asat_mass", "WUE", "Rd_mass", "PNUE"),
#'   leaf_chemistry = c("N_area", "Chl_area", "DNA", "Phenolics",
#'                      "Cellulose", "N_mass", "N_litter", "Chl_ab",
#'                      "Chl_mass", "N_res", "C_litter", "C_area",
#'                      "C_mass", "Ash", "Lignin", "Solubles",
#'                      "Decomp_leaf", "Hemi"),
#'   root = c("NPP_root", "SS_root", "SRL", "RTD", "RDMC",
#'            "NSC_root", "Decomp_root", "Starch_root",
#'            "C_root", "N_root", "Lignin_root"),
#'   stem = c("Latewood_diam", "Metaxylem_diam", "Earlywood_diam",
#'            "NSC_stem", "Vessel_freq", "SS_stem", "Cond_stem",
#'            "Starch_stem")
#' )
#' graph <- PTMN(traits, layers_list = layers, method = "pearson")
#' average_interlayer_clustering_coefficient(graph)
#'}
#'
#' @seealso
#' \code{\link{PTMN}} for constructing plant trait multilayer networks
#'
#' @export
average_interlayer_clustering_coefficient <- function(data) {
  # Calculate the interlayer clustering coefficient for each node
  node_coefficients <- interlayer_clustering_coefficient(data)
  # Calculate the overall average interlayer clustering coefficient
  avg_coefficient <- mean(node_coefficients$interlayer_clustering_coefficient)
  return(avg_coefficient)
}