@bgicli/bgicli 2.1.1 → 2.2.0

package/data/workflows/coexpression-network/scripts/export_wgcna_results.R

@@ -0,0 +1,117 @@
+# Export all WGCNA results
+
+library(WGCNA)
+
+#' Export all WGCNA results (including RDS objects for downstream skills)
+#'
+#' @param results Results object from run_wgcna_analysis()
+#' @param output_dir Directory to save results (default: "wgcna_results")
+#' @param output_prefix Prefix for output files (default: "wgcna")
+export_all <- function(results, output_dir = "wgcna_results", output_prefix = "wgcna") {
+
+  cat("\n=== Exporting WGCNA Results ===\n\n")
+
+  # Create output directory if needed
+  if (!dir.exists(output_dir)) {
+    dir.create(output_dir, recursive = TRUE)
+  }
+
+  # Extract components from results
+  gene_info <- results$hub_results$gene_info
+  hub_genes <- results$hub_results$hub_genes
+  trait_results <- results$trait_results
+
+  # 1. Export gene-module assignments
+  csv_path <- file.path(output_dir, paste0(output_prefix, "_gene_modules.csv"))
+  write.csv(gene_info, csv_path, row.names = FALSE)
+  cat("  Saved:", csv_path, "\n")
+
+  # 2. Export hub genes
+  hub_df <- do.call(rbind, lapply(names(hub_genes), function(mod) {
+    df <- hub_genes[[mod]]
+    df$module <- mod
+    df
+  }))
+  csv_path <- file.path(output_dir, paste0(output_prefix, "_hub_genes.csv"))
+  write.csv(hub_df, csv_path, row.names = FALSE)
+  cat("  Saved:", csv_path, "\n")
+
+  # 3. Export module-trait correlations
+  csv_path <- file.path(output_dir, paste0(output_prefix, "_module_trait_cor.csv"))
+  write.csv(trait_results$results, csv_path, row.names = FALSE)
+  cat("  Saved:", csv_path, "\n")
+
+  # 4. Export module eigengenes
+  csv_path <- file.path(output_dir, paste0(output_prefix, "_eigengenes.csv"))
+  write.csv(trait_results$MEs, csv_path)
+  cat("  Saved:", csv_path, "\n")
+
+  # 5. Save analysis objects as RDS for downstream skills (CRITICAL)
+  cat("\n  Saving analysis objects for downstream use:\n")
+
+  rds_path <- file.path(output_dir, paste0(output_prefix, "_network.rds"))
+  saveRDS(results$network, rds_path)
+  cat("    • wgcna_network.rds\n")
+  cat("      (Load with: net <- readRDS('", basename(rds_path), "'))\n", sep = "")
+
+  rds_path <- file.path(output_dir, paste0(output_prefix, "_module_colors.rds"))
+  saveRDS(results$module_colors, rds_path)
+  cat("    • wgcna_module_colors.rds\n")
+  cat("      (Load with: colors <- readRDS('", basename(rds_path), "'))\n", sep = "")
+
+  rds_path <- file.path(output_dir, paste0(output_prefix, "_expression_matrix.rds"))
+  saveRDS(results$datExpr, rds_path)
+  cat("    • wgcna_expression_matrix.rds\n")
+  cat("      (Load with: expr <- readRDS('", basename(rds_path), "'))\n", sep = "")
+
+  rds_path <- file.path(output_dir, paste0(output_prefix, "_full_results.rds"))
+  saveRDS(results, rds_path)
+  cat("    • wgcna_full_results.rds (complete results object)\n")
+  cat("      (Load with: results <- readRDS('", basename(rds_path), "'))\n", sep = "")
+
+  # 6. Create summary report
+  cat("\n  Creating summary report...\n")
+  summary_lines <- c(
+    "# WGCNA Co-expression Network Analysis Summary\n",
+    paste("**Total genes analyzed:**", nrow(gene_info)),
+    paste("**Total samples:**", nrow(trait_results$MEs)),
+    paste("**Number of modules:**", length(unique(gene_info$module)) - 1, "(excluding grey)\n"),
+    "## Module Sizes"
+  )
+
+  module_sizes <- table(gene_info$module)
+  for (mod in names(sort(module_sizes, decreasing = TRUE))) {
+    if (mod != "grey") {
+      summary_lines <- c(summary_lines, paste("-", mod, ":", module_sizes[mod], "genes"))
+    }
+  }
+
+  summary_lines <- c(summary_lines, "\n## Top Hub Genes per Module")
+  for (mod in names(hub_genes)) {
+    top_hubs <- head(hub_genes[[mod]]$gene, 5)
+    summary_lines <- c(summary_lines, paste("-", mod, ":", paste(top_hubs, collapse = ", ")))
+  }
+
+  report_path <- file.path(output_dir, paste0(output_prefix, "_report.md"))
+  writeLines(summary_lines, report_path)
+  cat("  Saved:", report_path, "\n")
+
+  cat("\n=== Export Complete ===\n\n")
+}
+
+# Keep old function name for backwards compatibility
+export_wgcna_results <- function(gene_info, hub_genes, trait_results,
+                                  output_prefix = "wgcna") {
+  .Deprecated("export_all", msg = "export_wgcna_results() is deprecated. Use export_all() instead.")
+
+  # Create minimal results object for compatibility
+  results <- list(
+    hub_results = list(gene_info = gene_info, hub_genes = hub_genes),
+    trait_results = trait_results,
+    datExpr = NULL,
+    network = NULL,
+    module_colors = NULL
+  )
+
+  export_all(results, output_dir = ".", output_prefix = output_prefix)
+}

package/data/workflows/coexpression-network/scripts/identify_hub_genes.R

@@ -0,0 +1,63 @@
+# Identify hub genes within each module
+
+library(WGCNA)
+
+#' Identify hub genes within each module
+#'
+#' @param datExpr Expression matrix
+#' @param module_colors Module assignments
+#' @param power Soft-thresholding power
+#' @param n_hub Number of hub genes per module
+#' @return List with gene info and hub genes per module
+identify_hub_genes <- function(datExpr, module_colors, power, n_hub = 10) {
+
+  # Calculate module membership (correlation with module eigengene)
+  MEs <- moduleEigengenes(datExpr, colors = module_colors)$eigengenes
+
+  # Calculate gene-module membership
+  gene_module_membership <- as.data.frame(cor(datExpr, MEs, use = "p"))
+  colnames(gene_module_membership) <- gsub("ME", "MM_", colnames(gene_module_membership))
+
+  # Calculate intramodular connectivity
+  adj <- adjacency(datExpr, power = power, type = "signed")
+
+  # Get connectivity for each gene
+  connectivity <- intramodularConnectivity(adj, module_colors)
+
+  # Combine results
+  gene_info <- data.frame(
+    gene = colnames(datExpr),
+    module = module_colors,
+    kWithin = connectivity$kWithin,
+    kOut = connectivity$kOut,
+    kTotal = connectivity$kTotal,
+    stringsAsFactors = FALSE
+  )
+
+  # Add module membership
+  gene_info <- cbind(gene_info, gene_module_membership)
+
+  # Identify hub genes per module
+  hub_genes <- list()
+  modules <- unique(module_colors)
+  modules <- modules[modules != "grey"]  # Exclude unassigned
+
+  for (mod in modules) {
+    mod_genes <- gene_info[gene_info$module == mod, ]
+    mm_col <- paste0("MM_", mod)
+
+    if (mm_col %in% colnames(mod_genes)) {
+      # Rank by module membership and connectivity
+      mod_genes$hub_score <- abs(mod_genes[[mm_col]]) * mod_genes$kWithin
+      mod_genes <- mod_genes[order(-mod_genes$hub_score), ]
+      hub_genes[[mod]] <- head(mod_genes, n_hub)
+    }
+  }
+
+  cat("Identified hub genes for", length(hub_genes), "modules\n")
+
+  return(list(
+    gene_info = gene_info,
+    hub_genes = hub_genes
+  ))
+}

package/data/workflows/coexpression-network/scripts/load_example_data.R

@@ -0,0 +1,214 @@
+#' Load Example WGCNA Dataset
+#'
+#' Loads the female mouse liver dataset from the WGCNA tutorial.
+#' This dataset contains 135 samples of liver tissue from female mice
+#' with multiple physiological traits measured.
+#'
+#' Auto-installs required packages if missing.
+#'
+#' @return List with three elements:
+#'   \item{datExpr}{Expression matrix in WGCNA format (samples × genes)}
+#'   \item{meta}{Sample metadata with traits}
+#'   \item{description}{Character string describing the dataset}
+#' @export
+#'
+#' @examples
+#' \dontrun{
+#' data <- load_example_wgcna_data()
+#' datExpr <- data$datExpr
+#' meta <- data$meta
+#' }
+load_example_wgcna_data <- function() {
+  # Set CRAN mirror FIRST (common failure point)
+  if (length(getOption("repos")) == 0 || getOption("repos")["CRAN"] == "@CRAN@") {
+    options(repos = c(CRAN = "https://cloud.r-project.org"))
+  }
+
+  # Auto-install BiocManager if needed
+  if (!requireNamespace("BiocManager", quietly = TRUE)) {
+    cat("Installing BiocManager...\n")
+    install.packages("BiocManager")
+  }
+
+  # Auto-install WGCNA if needed
+  if (!requireNamespace("WGCNA", quietly = TRUE)) {
+    cat("Installing WGCNA package (~5 min)...\n")
+    BiocManager::install("WGCNA", update = FALSE, ask = FALSE)
+  }
+
+  library(WGCNA)
+
+  # Download tutorial data from WGCNA website
+  cat("Downloading female mouse liver dataset (~2MB)...\n")
+
+  # URLs for the female mouse liver data
+  expr_url <- "https://horvath.genetics.ucla.edu/html/CoexpressionNetwork/Rpackages/WGCNA/Tutorials/FemaleLiver-Data/LiverFemale3600.csv"
+  traits_url <- "https://horvath.genetics.ucla.edu/html/CoexpressionNetwork/Rpackages/WGCNA/Tutorials/FemaleLiver-Data/ClinicalTraits.csv"
+
+  # Create temporary directory for downloads
+  temp_dir <- tempdir()
+  expr_file <- file.path(temp_dir, "LiverFemale3600.csv")
+  traits_file <- file.path(temp_dir, "ClinicalTraits.csv")
+
+  # Download files
+  tryCatch({
+    download.file(expr_url, expr_file, method = "auto", quiet = FALSE)
+    download.file(traits_url, traits_file, method = "auto", quiet = FALSE)
+  }, error = function(e) {
+    stop("Failed to download example data. Please check your internet connection.\n",
+         "Error: ", e$message)
+  })
+
+  # Load expression data
+  cat("Loading expression data...\n")
+  femData <- read.csv(expr_file)
+
+  # Transpose to WGCNA format (samples × genes)
+  # First column is gene names, rest are samples
+  datExpr0 <- as.data.frame(t(femData[, -1]))
+  colnames(datExpr0) <- femData[, 1]
+  rownames(datExpr0) <- names(femData)[-1]
+
+  # Check for excessive missing values and outliers
+  gsg <- goodSamplesGenes(datExpr0, verbose = 3)
+
+  if (!gsg$allOK) {
+    # Optionally, print the gene and sample names that were removed
+    if (sum(!gsg$goodGenes) > 0)
+      cat("Removing genes:", paste(names(datExpr0)[!gsg$goodGenes], collapse = ", "), "\n")
+    if (sum(!gsg$goodSamples) > 0)
+      cat("Removing samples:", paste(rownames(datExpr0)[!gsg$goodSamples], collapse = ", "), "\n")
+    # Remove the offending genes and samples from the data
+    datExpr0 <- datExpr0[gsg$goodSamples, gsg$goodGenes]
+  }
+
+  # Load clinical traits
+  cat("Loading clinical traits...\n")
+  traitData <- read.csv(traits_file)
+
+  # Match samples between expression and traits
+  # Remove columns that hold information we do not need
+  allTraits <- traitData[, -c(31, 16)]
+  allTraits <- allTraits[, c(2, 11:36)]
+
+  # Form a data frame analogous to expression data that will hold the clinical traits
+  femaleSamples <- rownames(datExpr0)
+  traitRows <- match(femaleSamples, allTraits$Mice)
+  datTraits <- allTraits[traitRows, -1]
+  rownames(datTraits) <- allTraits[traitRows, 1]
+
+  # Ensure sample names match exactly
+  if (!all(rownames(datExpr0) == rownames(datTraits))) {
+    warning("Sample names don't match exactly. Subsetting to common samples.")
+    common_samples <- intersect(rownames(datExpr0), rownames(datTraits))
+    datExpr0 <- datExpr0[common_samples, ]
+    datTraits <- datTraits[common_samples, ]
+  }
+
+  cat("\n")
+  cat("✓ Successfully loaded female mouse liver dataset\n")
+  cat("  Samples:", nrow(datExpr0), "\n")
+  cat("  Genes:", ncol(datExpr0), "\n")
+  cat("  Traits:", ncol(datTraits), "\n")
+  cat("  Available traits:", paste(colnames(datTraits)[1:5], collapse = ", "), "...\n")
+  cat("\n")
+
+  # Return standardized format
+  return(list(
+    datExpr = datExpr0,
+    meta = datTraits,
+    description = paste(
+      "Female mouse liver dataset from WGCNA tutorial.",
+      nrow(datExpr0), "samples,", ncol(datExpr0), "genes.",
+      "Microarray expression data with", ncol(datTraits), "clinical traits",
+      "including weight, glucose, insulin, and lipid measurements."
+    )
+  ))
+}
+
+
+#' Validate Input Data for WGCNA
+#'
+#' Checks if user-provided data meets WGCNA requirements.
+#' Validates format, sample size, missing values, and data quality.
+#'
+#' @param expr_data Expression matrix (samples × genes) or (genes × samples)
+#' @param meta_data Sample metadata (optional)
+#' @param min_samples Minimum required samples (default: 15)
+#'
+#' @return List with validation results and reformatted data if successful
+#' @export
+validate_input_data <- function(expr_data, meta_data = NULL, min_samples = 15) {
+
+  cat("Validating input data...\n")
+
+  # Check if data is a data frame or matrix
+  if (!is.data.frame(expr_data) && !is.matrix(expr_data)) {
+    stop("Expression data must be a data frame or matrix")
+  }
+
+  # Determine orientation (genes × samples or samples × genes)
+  if (nrow(expr_data) > ncol(expr_data)) {
+    cat("  Detected genes × samples format. Transposing to samples × genes...\n")
+    expr_data <- t(expr_data)
+  }
+
+  # Check sample size
+  n_samples <- nrow(expr_data)
+  n_genes <- ncol(expr_data)
+
+  cat("  Samples:", n_samples, "\n")
+  cat("  Genes:", n_genes, "\n")
+
+  if (n_samples < min_samples) {
+    stop("Insufficient samples: WGCNA requires at least ", min_samples, " samples. ",
+         "You have ", n_samples, " samples.")
+  }
+
+  if (n_samples < 20) {
+    warning("Sample size is low (", n_samples, " samples). ",
+            "WGCNA works best with 20+ samples. Results may be less robust.")
+  }
+
+  # Check for missing values
+  missing_pct <- sum(is.na(expr_data)) / (nrow(expr_data) * ncol(expr_data)) * 100
+  cat("  Missing values:", round(missing_pct, 2), "%\n")
+
+  if (missing_pct > 5) {
+    warning("High proportion of missing values (", round(missing_pct, 2), "%). ",
+            "Consider imputation or removing genes/samples with excessive missingness.")
+  }
+
+  # Check for sample metadata if provided
+  if (!is.null(meta_data)) {
+    if (nrow(meta_data) != n_samples) {
+      stop("Metadata has ", nrow(meta_data), " rows but expression data has ",
+           n_samples, " samples")
+    }
+    cat("  Metadata:", ncol(meta_data), "traits\n")
+  }
+
+  # Use WGCNA's goodSamplesGenes function
+  if (requireNamespace("WGCNA", quietly = TRUE)) {
+    library(WGCNA)
+    gsg <- goodSamplesGenes(expr_data, verbose = 0)
+
+    if (!gsg$allOK) {
+      cat("  Removing", sum(!gsg$goodGenes), "genes and",
+          sum(!gsg$goodSamples), "samples with excessive missing values...\n")
+      expr_data <- expr_data[gsg$goodSamples, gsg$goodGenes]
+      if (!is.null(meta_data)) {
+        meta_data <- meta_data[gsg$goodSamples, ]
+      }
+    }
+  }
+
+  cat("✓ Data validation successful\n\n")
+
+  return(list(
+    datExpr = expr_data,
+    meta = meta_data,
+    n_samples = nrow(expr_data),
+    n_genes = ncol(expr_data)
+  ))
+}

package/data/workflows/coexpression-network/scripts/module_enrichment.R

@@ -0,0 +1,159 @@
+#' Run enrichment analysis on module genes
+#'
+#' Performs GO and KEGG enrichment analysis on genes within each module.
+#' Supports multiple organisms with automatic installation of required packages.
+#'
+#' @param gene_info Data frame with gene-module assignments (must have 'gene' and 'module' columns)
+#' @param organism Character string specifying organism. One of:
+#'   "human", "mouse", "rat", "zebrafish", "fly", "worm", "yeast"
+#'   Default: "human"
+#' @param modules Character vector of modules to analyze (default: all non-grey modules)
+#' @param ont GO ontology to use: "BP" (Biological Process), "MF" (Molecular Function),
+#'   "CC" (Cellular Component), or "ALL". Default: "BP"
+#' @param pvalueCutoff P-value cutoff for enrichment (default: 0.05)
+#' @param qvalueCutoff Q-value cutoff for enrichment (default: 0.1)
+#'
+#' @return List of enrichment results per module. Each element contains a data frame
+#'   with enriched GO terms, p-values, q-values, and gene lists.
+#'
+#' @details
+#' Supported organisms and their annotation packages:
+#' \itemize{
+#'   \item human: org.Hs.eg.db
+#'   \item mouse: org.Mm.eg.db
+#'   \item rat: org.Rn.eg.db
+#'   \item zebrafish: org.Dr.eg.db
+#'   \item fly: org.Dm.eg.db
+#'   \item worm: org.Ce.eg.db
+#'   \item yeast: org.Sc.sgd.db
+#' }
+#'
+#' The function automatically installs the required organism annotation package
+#' if it's not already installed.
+#'
+#' @examples
+#' \dontrun{
+#' # Human genes
+#' enrichment_results <- module_enrichment(gene_info, organism = "human")
+#'
+#' # Mouse genes
+#' enrichment_results <- module_enrichment(gene_info, organism = "mouse")
+#'
+#' # Specific modules only
+#' enrichment_results <- module_enrichment(gene_info, organism = "human",
+#'                                        modules = c("blue", "turquoise"))
+#' }
+#'
+#' @export
+module_enrichment <- function(gene_info,
+                              organism = "human",
+                              modules = NULL,
+                              ont = "BP",
+                              pvalueCutoff = 0.05,
+                              qvalueCutoff = 0.1) {
+
+  # Set CRAN mirror if not set
+  if (length(getOption("repos")) == 0 || getOption("repos")["CRAN"] == "@CRAN@") {
+    options(repos = c(CRAN = "https://cloud.r-project.org"))
+  }
+
+  # Map organism names to annotation packages
+  organism_map <- c(
+    "human" = "org.Hs.eg.db",
+    "mouse" = "org.Mm.eg.db",
+    "rat" = "org.Rn.eg.db",
+    "zebrafish" = "org.Dr.eg.db",
+    "fly" = "org.Dm.eg.db",
+    "worm" = "org.Ce.eg.db",
+    "yeast" = "org.Sc.sgd.db"
+  )
+
+  # Validate organism
+  if (!organism %in% names(organism_map)) {
+    stop("Unsupported organism: ", organism, "\n",
+         "Supported organisms: ", paste(names(organism_map), collapse = ", "))
+  }
+
+  org_pkg <- organism_map[organism]
+  cat("Using organism:", organism, "(", org_pkg, ")\n")
+
+  # Auto-install BiocManager if needed
+  if (!requireNamespace("BiocManager", quietly = TRUE)) {
+    cat("Installing BiocManager...\n")
+    install.packages("BiocManager")
+  }
+
+  # Auto-install clusterProfiler if needed
+  if (!requireNamespace("clusterProfiler", quietly = TRUE)) {
+    cat("Installing clusterProfiler...\n")
+    BiocManager::install("clusterProfiler", update = FALSE, ask = FALSE)
+  }
+
+  # Auto-install organism package if needed
+  if (!requireNamespace(org_pkg, quietly = TRUE)) {
+    cat("Installing", org_pkg, "annotation package (~50MB, ~2 min)...\n")
+    BiocManager::install(org_pkg, update = FALSE, ask = FALSE)
+  }
+
+  # Load required libraries
+  library(clusterProfiler)
+  library(org_pkg, character.only = TRUE)
+
+  # Get OrgDb object
+  orgDb <- get(org_pkg)
+
+  # Determine modules to analyze
+  if (is.null(modules)) {
+    modules <- unique(gene_info$module)
+    modules <- modules[modules != "grey"]
+  }
+
+  cat("Analyzing", length(modules), "modules\n\n")
+
+  enrichment_results <- list()
+
+  for (mod in modules) {
+    mod_genes <- gene_info$gene[gene_info$module == mod]
+
+    cat("Module", mod, "(", length(mod_genes), "genes):\n")
+
+    # GO enrichment
+    tryCatch({
+      ego <- enrichGO(
+        gene = mod_genes,
+        OrgDb = orgDb,
+        keyType = "SYMBOL",
+        ont = ont,
+        pAdjustMethod = "BH",
+        pvalueCutoff = pvalueCutoff,
+        qvalueCutoff = qvalueCutoff
+      )
+
+      if (nrow(ego) > 0) {
+        enrichment_results[[mod]] <- list(
+          GO = as.data.frame(ego)
+        )
+        cat("  ✓ Found", nrow(ego), "enriched GO terms\n")
+
+        # Show top 3 terms
+        top_terms <- head(ego@result$Description, 3)
+        for (i in seq_along(top_terms)) {
+          cat("   ", i, ".", top_terms[i], "\n")
+        }
+      } else {
+        cat("  No significant GO enrichment found\n")
+      }
+    }, error = function(e) {
+      cat("  ✗ Error in GO enrichment:", e$message, "\n")
+    })
+
+    cat("\n")
+  }
+
+  if (length(enrichment_results) == 0) {
+    warning("No enrichment results found for any module. ",
+            "Check that gene symbols match the organism annotation.")
+  }
+
+  return(enrichment_results)
+}

package/data/workflows/coexpression-network/scripts/pick_soft_power.R

@@ -0,0 +1,70 @@
+# Pick soft-thresholding power for scale-free topology
+
+library(WGCNA)
+
+#' Pick soft-thresholding power for scale-free topology
+#'
+#' @param datExpr Expression matrix (samples x genes)
+#' @param powers Vector of powers to test
+#' @param output_file Path to save power selection plot
+#' @return List with scale-free topology fit results and recommended power
+pick_soft_power <- function(datExpr, powers = c(1:20), output_file = "soft_power_selection.svg") {
+
+  # Calculate scale-free topology fit for each power
+  sft <- pickSoftThreshold(datExpr, powerVector = powers, verbose = 5,
+                           networkType = "signed")
+
+  # Remove extension if provided
+  output_file <- sub("\\.(svg|png)$", "", output_file)
+
+  # Function to create the plot
+  .make_power_plot <- function() {
+    par(mfrow = c(1, 2))
+
+    # Scale-free topology fit
+    plot(sft$fitIndices[, 1], -sign(sft$fitIndices[, 3]) * sft$fitIndices[, 2],
+         xlab = "Soft Threshold (power)", ylab = "Scale Free Topology Model Fit (signed R^2)",
+         type = "n", main = "Scale Independence")
+    text(sft$fitIndices[, 1], -sign(sft$fitIndices[, 3]) * sft$fitIndices[, 2],
+         labels = powers, col = "red")
+    abline(h = 0.85, col = "blue", lty = 2)
+
+    # Mean connectivity
+    plot(sft$fitIndices[, 1], sft$fitIndices[, 5],
+         xlab = "Soft Threshold (power)", ylab = "Mean Connectivity",
+         type = "n", main = "Mean Connectivity")
+    text(sft$fitIndices[, 1], sft$fitIndices[, 5], labels = powers, col = "red")
+  }
+
+  # Save PNG (always)
+  png_path <- paste0(output_file, ".png")
+  png(png_path, width = 10, height = 5, units = "in", res = 300)
+  .make_power_plot()
+  dev.off()
+
+  # Try SVG with fallback
+  svg_path <- paste0(output_file, ".svg")
+  tryCatch({
+    svg(svg_path, width = 10, height = 5)
+    .make_power_plot()
+    dev.off()
+  }, error = function(e) {
+    # SVG failed silently
+  })
+
+  # Recommend power
+  recommended_power <- sft$powerEstimate
+  if (is.na(recommended_power)) {
+    # If no power reaches R^2 > 0.85, pick the one closest
+    recommended_power <- powers[which.max(-sign(sft$fitIndices[, 3]) * sft$fitIndices[, 2])]
+  }
+
+  cat("Recommended soft-thresholding power:", recommended_power, "\n")
+  cat("Scale-free R^2:", sft$fitIndices[recommended_power, 2], "\n")
+  cat("   Saved:", png_path, "\n")
+  if (file.exists(svg_path)) {
+    cat("   Saved:", svg_path, "\n")
+  }
+
+  return(list(sft = sft, power = recommended_power))
+}