bulkrna-coexpression

name	bulkrna-coexpression
description	WGCNA-style weighted gene co-expression network analysis — module detection, soft thresholding, hub genes.
version	0.3.0
author	OmicsClaw
license	MIT
tags	["bulkrna","coexpression","WGCNA","network","modules","hub-genes"]
metadata	{"omicsclaw":{"domain":"bulkrna","emoji":"🕸️","trigger_keywords":["coexpression","WGCNA","gene network","co-expression modules","hub genes","gene modules"],"allowed_extra_flags":["--min-module-size","--power"],"legacy_aliases":["bulk-wgcna"],"saves_h5ad":false}}

Bulk RNA-seq Co-expression Network Analysis

WGCNA-style weighted gene co-expression network analysis. Detects gene modules via soft thresholding, topological overlap, and hierarchical clustering, then identifies hub genes per module.

CLI Reference

python omicsclaw.py run bulkrna-coexpression --demo
python omicsclaw.py run bulkrna-coexpression --input <counts.csv> --output <dir>
python bulkrna_coexpression.py --input counts.csv --output results/
python bulkrna_coexpression.py --demo --output /tmp/coexpression_demo
python bulkrna_coexpression.py --input counts.csv --output results/ --power 6 --min-module-size 15

Why This Exists

• Without it: Researchers must install the WGCNA R package, manually tune soft-thresholding power, interpret topological overlap matrices, and write custom scripts to extract hub genes from each module.
• With it: A single Python command runs the full WGCNA-style pipeline — soft threshold selection, TOM-based module detection, hub gene extraction — and produces publication-ready figures and tables.
• Why OmicsClaw: Implements the core WGCNA methodology in pure Python (numpy/scipy) with no R dependency, integrated into the OmicsClaw reporting framework with automatic scale-free topology fitting.

Workflow

1. Load: Read a genes-by-samples raw count matrix (CSV with a gene column and sample columns).
2. Transform: Log2-transform counts (log2(x + 1)) and filter low-variance genes (keep top 80% by variance).
3. Correlate: Compute Pearson correlation matrix across all retained genes.
4. Soft Threshold: Test a range of soft-thresholding powers and select the first power achieving scale-free topology fit (R^2 > 0.8).
5. Module Detection: Compute adjacency matrix, topological overlap matrix (TOM), and apply hierarchical clustering with tree cutting to identify co-expression modules.
6. Hub Genes: For each module, rank genes by intra-module connectivity and report the top hub genes.
7. Report: Write markdown report, result.json, module assignment and hub gene tables, and a reproducibility script.

Example Queries

• "Run WGCNA on my bulk RNA-seq data"
• "Find co-expression modules and hub genes"
• "Detect gene co-expression networks from my count matrix"
• "What soft threshold power should I use for my RNA-seq data?"
• "Identify hub genes in co-expression modules"

Output Structure

output_directory/
├── report.md
├── result.json
├── figures/
│   ├── scale_free_fit.png
│   ├── module_sizes.png
│   └── module_dendrogram.png
├── tables/
│   ├── module_assignments.csv
│   ├── hub_genes.csv
│   └── threshold_fit.csv
└── reproducibility/
    └── commands.sh

Safety

• Local-first: All processing runs locally; no data is uploaded to external services.
• Disclaimer: Every report includes the standard OmicsClaw disclaimer.
• Audit trail: Parameters, method details, and input checksums are recorded in result.json.

Integration with Orchestrator

Trigger conditions:

• Automatically invoked when user intent matches co-expression, WGCNA, gene network, or hub gene keywords.

Chaining partners:

• bulkrna-de -- Upstream: differentially expressed genes can be used as input
• bulkrna-enrichment -- Downstream: pathway/GO enrichment of module gene sets
• bulkrna-qc -- Upstream: count matrix QC

Parameters

Parameter	Default	Description
--power	auto	Soft-thresholding power (auto-selected if omitted)
--min-module-size	10	Minimum number of genes per module

Version Compatibility

Reference examples tested with: scipy 1.11+, pandas 2.0+, numpy 1.24+, matplotlib 3.7+

Dependencies

Required: numpy, pandas, scipy, matplotlib

Citations

• WGCNA -- Langfelder & Horvath, BMC Bioinformatics 2008
• Scale-free topology -- Zhang & Horvath, Statistical Applications in Genetics and Molecular Biology 2005
• Topological Overlap Matrix -- Yip & Horvath, BMC Bioinformatics 2007

Related Skills

• bulkrna-de -- Differential expression analysis upstream
• bulkrna-enrichment -- Pathway enrichment of module gene sets downstream
• bulkrna-qc -- Count matrix QC upstream