| name | bulkrna-coexpression |
| description | Load when discovering gene co-expression modules and hub genes in a bulk RNA-seq cohort via WGCNA-style soft-thresholded networks. Skip for direct DE comparison (use bulkrna-de) or PPI lookup of an existing gene list (use bulkrna-ppi-network); single-cell co-expression uses sc-grn instead. |
| version | 0.3.0 |
| author | OmicsClaw |
| license | MIT |
| tags | ["bulkrna","coexpression","WGCNA","network","modules","hub-genes"] |
bulkrna-coexpression
When to use
Run on a bulk RNA-seq cohort (≥15 samples recommended; works on smaller
sets but module structure is unstable below that) when you want to find
groups of co-regulated genes ("modules") and the hub genes within each.
Soft-thresholded correlation network in the WGCNA style; outputs module
assignments, hub genes, and module-trait correlations.
Inputs & Outputs
| Input | Format | Required |
|---|
| Count matrix | .csv (gene × sample) | yes (or --demo) |
| Sample traits | --traits CSV | optional, for module-trait correlation |
| Output | Path | Notes |
|---|
| Module assignments | tables/module_assignments.csv | gene → module colour |
| Hub genes | tables/hub_genes.csv | per-module top-connectivity genes |
| Soft-threshold diagnostic | tables/threshold_fit.csv + figures/scale_free_fit.png | per-power scale-free fit + connectivity |
| Module sizes | figures/module_sizes.png | bar chart of gene count per module |
| Module assignments | figures/module_dendrogram.png | colour-strip of per-gene module label |
| Report | report.md + result.json | summary keys: n_genes_used, n_samples, soft_power, n_modules, module_sizes, method_used |
Flow
- Load count matrix; validate
--input (bulkrna_coexpression.py:721,724 parser-error / FileNotFoundError). Demo path uses :54's built-in fixture.
- Validate sample count:
:377 raises ValueError("WGCNA requires >= 8 samples ...") below 8; :382 warns "Low sample count" between 8 and 15 but proceeds.
- Try the R WGCNA bridge (
_run_wgcna_r via subprocess); :390 raises RuntimeError("R WGCNA failed: ...") if R or the WGCNA package is unavailable.
- The Python helper
_select_soft_threshold (:70) is a sanity-check / diagnostic that scores candidate powers by scale-free R² — used as a fallback / exploratory aid, not the production estimator. R WGCNA's own pickSoftThreshold drives the real run.
- Build modules in R; collect assignments + hub genes; emit
module_assignments.csv, hub_genes.csv, threshold_fit.csv.
Gotchas
- WGCNA hard-fails below 8 samples.
bulkrna_coexpression.py:377 raises ValueError. Between 8 and 15 the run proceeds but :382 warns "Low sample count (N). WGCNA recommends >= 15 samples for reliable module detection." — treat any modules from <15-sample cohorts as exploratory.
- R WGCNA is required for the production path.
:390 raises RuntimeError with installation instructions if R or the WGCNA package isn't importable. There is no Python-only fallback that produces module assignments — installing R+WGCNA is mandatory for non-demo runs.
- Per-power scale-free R² is in
tables/threshold_fit.csv, not result.json. The summary dict (:455-464) carries soft_power (the chosen power) but no R² value; inspect the threshold-fit table to assess scale-free quality. Below R² ≈ 0.8 the network is not scale-free and modules become noise.
- No biological-replicate filter. Unlike PyDESeq2, this skill makes no distinction between technical and biological replicates. Modules built on a cohort with hidden batch structure will reflect the batch, not biology — run
bulkrna-batch-correction upstream if PCA shows batch separation.
- Gene IDs must match between counts and traits. No automatic mapping — feed counts and traits with consistent identifier system, or run
bulkrna-geneid-mapping first.
- Hub genes are connectivity-based, not necessarily biology-load-bearing. A hub in WGCNA means "highest intramodular correlation" — useful as a starting hypothesis but not proof of regulatory primacy. Validate with knockdown / knockout data or eQTL evidence.
Key CLI
python omicsclaw.py run bulkrna-coexpression --demo
python omicsclaw.py run bulkrna-coexpression \
--input counts.csv --output results/
python omicsclaw.py run bulkrna-coexpression \
--input counts.csv --traits clinical.csv --output results/
See also
references/parameters.md — every CLI flag and tuning hintreferences/methodology.md — soft-thresholding, module detection, hub-gene definitionreferences/output_contract.md — exact output directory layout- Adjacent skills:
bulkrna-batch-correction (run upstream if batches suspected), bulkrna-de (parallel: differential expression), bulkrna-ppi-network (parallel: STRING PPI on a gene list), sc-grn (single-cell sibling using GRNBoost2 / pySCENIC)
