R/interlayer_edge_density.R

In MultiTraits: Analyzing and Visualizing Multidimensional Plant Traits

#' Calculate Interlayer Edge Density for Plant Trait Multilayer Networks
#'
#' @description
#' This function calculates the interlayer edge density (IED) for a plant trait multilayer network (PTMN).
#' The IED measures the ratio of observed to maximally possible interlayer edges, indicating the
#' extent of direct connections among functional layers. A higher IED indicates greater
#' interdependency among layers, reflecting stronger overall network integration.
#'
#' @param data A data frame containing edge information for the multilayer network. The data frame
#'   must contain at least four columns: \code{layer.from}, \code{layer.to}, \code{node.from},
#'   and \code{node.to}, representing the source layer, target layer, source node, and target node
#'   for each edge, respectively.
#'
#' @return A numeric value representing the interlayer edge density, calculated as the ratio of
#'   actual interlayer edges to the maximum possible number of interlayer edges between all
#'   layer pairs.
#'
#' @details
#' The interlayer edge density is calculated using the formula:
#' \deqn{IED = \frac{\sum_{\alpha=1}^{M-1} \sum_{\beta=\alpha+1}^{M} L_{inter}^{\alpha,\beta}}{\sum_{\alpha=1}^{M-1} \sum_{\beta=\alpha+1}^{M} n_{\alpha} \cdot n_{\beta}}}
#' where M is the total number of layers, \eqn{L_{inter}^{\alpha,\beta}} is the number of observed
#' interlayer edges between layers \eqn{\alpha} and \eqn{\beta}, and \eqn{n_{\alpha}} and \eqn{n_{\beta}} are their
#' respective node counts.
#'
#' This parameter is one of the specially designed topological parameters for quantifying PTMN
#' topology, facilitating the effective identification of hub traits and key cross-layer
#' functional modules essential for understanding coordinated adaptation of plant traits across
#' functional levels.
#'
#' @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")
#' interlayer_edge_density(graph)
#'}
#'
#' @seealso
#' \code{\link{PTMN}} for constructing plant trait multilayer networks
#'
#' @export
interlayer_edge_density <- function(data) {
  # Filter out interlayer edges (layer.from != layer.to)
  interlayer_edges <- data[data$layer.from != data$layer.to, ]
  # Get all unique layers
  all_layers <- unique(c(data$layer.from, data$layer.to))
  n_layers <- length(all_layers)
  # Calculate the number of nodes per layer
  nodes_per_layer <- sapply(all_layers, function(layer) {
    unique_nodes <- unique(c(data$node.from[data$layer.from == layer],data$node.to[data$layer.to == layer]))
    return(length(unique_nodes))
  })
  # Calculate the maximum number of possible edges between layers
  max_possible_edges <- 0
  for (i in 1:(n_layers-1)) {
    for (j in (i+1):n_layers) {
      layer_i <- all_layers[i]
      layer_j <- all_layers[j]
      max_possible_edges <- max_possible_edges + (nodes_per_layer[layer_i] * nodes_per_layer[layer_j])
    }
  }
  # Calculate the actual number of edges between layers
  actual_interlayer_edges <- nrow(interlayer_edges)
  # Calculate interlayer edge density
  interlayer_edge_density <- actual_interlayer_edges / max_possible_edges
  return(as.numeric(interlayer_edge_density))
}