Source: https://github.com/aipoch/medical-research-skills

WGCNA Analysis

When to Read External Files

AI Agent: This section tells you when to read additional files.

When Not to Use

• Do not use for single-cell RNA-seq matrices.
• Do not use for methylation data, DEG testing, or other non-WGCNA workflows.
• Do not use if the user only wants exploratory discussion and does not want the analysis executed.
• Do not proceed if the dataset is obviously too small for WGCNA or becomes too small after QC.

When an input is out of scope, stop early and state which limitation applies.

Usage

Rscript scripts/main.R \
  --input_file ./expression_matrix.csv \
  --group_file ./group_info.csv \
  --output_dir ./output/ \
  --sample_column sample \
  --group_column group \
  --network_type unsigned \
  --cor_type pearson \
  --mad_quantile 0.25 \
  --min_mad 0.01 \
  --max_genes 5000 \
  --min_module_size 30 \
  --merge_cut_height 0.25 \
  --soft_r2_cutoff 0.85 \
  --module_of_interest auto \
  --top_modules 1 \
  --tom_sample_size 400 \
  --chunk_size 0 \
  --seed 42 \
  --timeout_seconds 0

Arguments

Input Format

Expression Matrix (input_file)

CSV file with gene identifiers in the first column and sample IDs in the header row. All expression columns must be numeric.

,TCGA-78-7156,TCGA-44-6774,TCGA-69-A59K
A1BG,2.612908495,2.077948602,3.865545859
A1BG-AS1,3.526391179,3.221923473,4.684308865
A1CF,1.179552278,1.136255654,1.188781778

Requirements:

• First column contains non-empty gene IDs
• Sample column names are unique and non-empty
• Expression values are numeric
• After QC, the matrix must remain large enough for WGCNA

Group File (group_file)

CSV file with at least two columns: one sample ID column and one group column.

sample,group
TCGA-78-7156,Control
TCGA-44-6774,Control
TCGA-69-A59K,Control
TCGA-44-6147,Case

Requirements:

• Sample IDs must match expression matrix column names
• Sample IDs must be unique
• Group values must be non-empty
• At least two groups are required

Output Files

All files are written under output_dir.

Workflow

Step 1: Load and validate inputs

• Validate file existence and CLI parameters
• Read the expression matrix and group file
• Check sample ID consistency between files

Step 2: Filter variable genes

• Compute per-gene MAD values
• Keep genes above the quantile-based MAD cutoff
• Optionally cap the retained genes with max_genes

Step 3: Build the WGCNA network

• Transpose the matrix into the WGCNA sample-by-gene format
• Select soft-threshold power with pickSoftThreshold()
• Build modules with blockwiseModules()

Step 4: Associate modules with traits

• Encode groups as a trait matrix
• Compute module-trait and gene-trait correlations
• Rank modules by absolute correlation with the selected trait

Step 5: Export results

• Save summary tables, module assignments, and per-module gene exports
• Generate dendrogram, heatmap, TOM, and scatter plot PDFs
• Save session info and serialized R objects

Error Handling

Common Errors

IF error persists, READ: references/troubleshooting.md

Testing

Smoke Test

# Check CLI help
Rscript scripts/main.R --help

# Run with bundled test data
Rscript scripts/main.R \
  --input_file tests/data/expression.csv \
  --group_file tests/data/group.csv \
  --output_dir tests/output-skill/ \
  --sample_column sample \
  --group_column group \
  --network_type unsigned \
  --cor_type pearson \
  --mad_quantile 0.25 \
  --min_mad 0.01 \
  --max_genes 500 \
  --min_module_size 20 \
  --merge_cut_height 0.25 \
  --soft_r2_cutoff 0.8 \
  --module_of_interest auto \
  --top_modules 1 \
  --tom_sample_size 150 \
  --chunk_size 0 \
  --seed 42 \
  --timeout_seconds 0

# Validate required outputs
Rscript tests/validate_outputs.R tests/output-skill/

Validation Commands

Rscript tests/validate_outputs.R tests/output-skill/

Expected outputs include session_info.txt, the plot PDFs, table CSVs, and the serialized R objects listed above.

Additional Verification

• When exporting explicit modules, confirm the matching tables/module_genes_<module>.csv files exist.
• When generating module membership plots, confirm the matching plots/module_membership_vs_trait_<module>_<trait>.pdf files exist.
• If chunked loading is enabled, compare tables/analysis_summary.csv against a non-chunked run on the same input.

Notes

• Re-running the same command with the same seed is expected to be reproducible.
• Failed runs may still create output_dir and session_info.txt before exiting; this is expected and safe to overwrite on retry.

Implementation Checklist

• CLI parsing with optparse
• set.seed() for reproducibility
• Dependency checks with explicit package loading
• Relative source() paths via get_script_dir()
• Optional timeout parameter
• Optional chunked loading for large matrices
• Session info recording
• Error handling with SKILL_* codes
• SKILL.md parameters match the implemented CLI
• File reading instructions in SKILL.md
• Test data provided in tests/data/
• Smoke-test output validation script provided

Last updated: 2026-04-17 | Version: 1.0.0