Dynamic Branch-Cutting Module Detection
License: restricted — no clear open-source license detected for the underlying tool; verify licensing before commercial use or redistribution.
Summary
Identify metabolic co-expression modules from hierarchical dendrograms using adaptive branch-cutting thresholds rather than fixed height cutoffs, enabling robust detection of metabolite clusters even on complex dendrograms. This skill partitions normalized metabolite abundance data into functionally coherent modules annotated by pathway membership.
When to use
Apply this skill after constructing a hierarchical dendrogram from a biweight midcorrelation dissimilarity matrix of metabolite measurements, when your dendrogram exhibits complicated structure (multiple scales, varying branch heights) that would be poorly captured by a single fixed-height cutoff, and you need to assign each metabolite to exactly one module for downstream trait association or pathway enrichment.
When NOT to use
- Input dissimilarity matrix was not computed from biweight midcorrelation or lacks robustness to outliers.
- Module assignments are already available from prior analysis; re-clustering would discard existing biological interpretation.
- Dendrogram is simple and unimodal; a constant height cutoff would be faster and equally interpretable.
Inputs
- hierarchical dendrogram object from hclust()
- biweight midcorrelation dissimilarity matrix (1 − adjacency)
- metabolite annotation table (rowData with SUB_PATHWAY field, optional)
Outputs
- module color vector (one color per metabolite)
- module assignment table (metabolite ID → module name/color)
- module summary statistics (size, pathway composition)
How to apply
Begin with a hierarchical clustering dendrogram computed from a dissimilarity matrix (1 − adjacency, where adjacency is derived from biweight midcorrelation with soft-thresholding power β=3). Apply the dynamic branch cutting algorithm (developed by Langfelder et al.) to automatically detect cluster boundaries at variable heights across the tree. Set a minimum module size threshold (e.g., 5 metabolites) to filter out small, potentially spurious clusters. Extract the module color vector and metabolite-to-module assignments from the output. Optionally, annotate each module by identifying its most abundant SUB_PATHWAY label from the rowData annotation. The dynamic method outperforms constant height cutoffs on dendrograms with heterogeneous branching structure, as it adapts the cutting threshold to local branch topology.
Related tools
- WGCNA (Implements cutreeDynamic() function for dynamic branch cutting and module definition on hierarchical dendrograms.)
- MetaboDiff (Wraps WGCNA dynamic branch cutting workflow for metabolomics, handles MultiAssayExperiment object input and outputs named module assignments.) — https://github.com/andreasmock/MetaboDiff
- R (Runtime environment; required version ≥ 4.0.2 for MetaboDiff compatibility.)
- MultiAssayExperiment (Data container for normalized, imputed metabolite abundance assay and rowData annotation; input to module detection workflow.)
Examples
# After loading norm_imputed MultiAssayExperiment and computing biweight midcorr. dissimilarity:
# library(WGCNA); dynamicTreeCut::cutreeDynamic(dendro=hc, distM=dissim_matrix, minClusterSize=5, method='hybrid')
Evaluation signals
- Module size distribution respects minimum threshold (all modules ≥ 5 metabolites); no singleton or very small clusters remain.
- Module color assignments are consistent and unique: every metabolite belongs to exactly one module, and colors are visually distinct in dendrogram plots.
- Module pathway composition is coherent: most metabolites in a module share the same or related SUB_PATHWAY label, indicating biological relevance.
- Dendrogram visualization shows branch colors matching module assignments; cutting positions adapt locally to branch heights and cluster tightness, not locked to a single horizontal line.
- Module assignments are stable under small perturbations: recomputing with slightly altered soft-threshold power (β=2.5–3.5) yields similar module boundaries and pathway coherence.
Limitations
- Dynamic branch cutting requires manual setting of minimum module size; no automatic data-driven choice for this threshold is provided in the article.
- Module quality depends critically on upstream correlation metric choice (biweight midcorrelation); if raw data contain systematic biases or unmodeled batch effects, dendrogram structure may be misleading.
- Pathway annotation (SUB_PATHWAY) is optional and tied to external databases (SMPDB, KEGG, HMDB, ChEBI); metabolites without annotation cannot contribute to module naming and require manual interpretation.
- The method assumes metabolites are the only clustering variables; it does not account for sample-level traits or phenotypes during module detection—trait association is performed post-hoc.
Evidence
- [methods] dynamic branch cutting definition: "We employed the dynamic branch cut method developed by Langfelder and colleagues, as constant height cutoffs exhibit suboptimal performance on complicated dendrograms."
- [methods] module detection parameters: "modules are detected by applying a branch cutting method with a minimal module size of 5 metabolites"
- [methods] biweight midcorrelation rationale: "Biweight midcorrelation was used as a similiarity measure as it is more robust to outliers than the absolute correlation coefficient"
- [methods] module naming by pathway: "For each module, identify the most abundant SUB_PATHWAY annotation and assign module names accordingly."
- [readme] key functionality in package: "MetaboDiffs offers the exploration of sample traits in a data-derived metabolic correlation network."
1---2name: dynamic-branch-cutting-module-detection3description: Use when after constructing a hierarchical dendrogram from a biweight midcorrelation dissimilarity matrix of metabolite measurements, when your dendrogram exhibits complicated structure (multiple scales, varying branch heights) that would be poorly captured by a single fixed-height cutoff, and you.4license: CC-BY-4.05---67# Dynamic Branch-Cutting Module Detection89> **License: restricted** — no clear open-source license detected for the underlying tool; verify licensing before commercial use or redistribution. <!-- asb-license-banner -->10## Summary1112Identify metabolic co-expression modules from hierarchical dendrograms using adaptive branch-cutting thresholds rather than fixed height cutoffs, enabling robust detection of metabolite clusters even on complex dendrograms. This skill partitions normalized metabolite abundance data into functionally coherent modules annotated by pathway membership.1314## When to use1516Apply this skill after constructing a hierarchical dendrogram from a biweight midcorrelation dissimilarity matrix of metabolite measurements, when your dendrogram exhibits complicated structure (multiple scales, varying branch heights) that would be poorly captured by a single fixed-height cutoff, and you need to assign each metabolite to exactly one module for downstream trait association or pathway enrichment.1718## When NOT to use1920- Input dissimilarity matrix was not computed from biweight midcorrelation or lacks robustness to outliers.21- Module assignments are already available from prior analysis; re-clustering would discard existing biological interpretation.22- Dendrogram is simple and unimodal; a constant height cutoff would be faster and equally interpretable.2324## Inputs2526- hierarchical dendrogram object from hclust()27- biweight midcorrelation dissimilarity matrix (1 − adjacency)28- metabolite annotation table (rowData with SUB_PATHWAY field, optional)2930## Outputs3132- module color vector (one color per metabolite)33- module assignment table (metabolite ID → module name/color)34- module summary statistics (size, pathway composition)3536## How to apply3738Begin with a hierarchical clustering dendrogram computed from a dissimilarity matrix (1 − adjacency, where adjacency is derived from biweight midcorrelation with soft-thresholding power β=3). Apply the dynamic branch cutting algorithm (developed by Langfelder et al.) to automatically detect cluster boundaries at variable heights across the tree. Set a minimum module size threshold (e.g., 5 metabolites) to filter out small, potentially spurious clusters. Extract the module color vector and metabolite-to-module assignments from the output. Optionally, annotate each module by identifying its most abundant SUB_PATHWAY label from the rowData annotation. The dynamic method outperforms constant height cutoffs on dendrograms with heterogeneous branching structure, as it adapts the cutting threshold to local branch topology.3940## Related tools4142- **WGCNA** (Implements cutreeDynamic() function for dynamic branch cutting and module definition on hierarchical dendrograms.)43- **MetaboDiff** (Wraps WGCNA dynamic branch cutting workflow for metabolomics, handles MultiAssayExperiment object input and outputs named module assignments.) — https://github.com/andreasmock/MetaboDiff44- **R** (Runtime environment; required version ≥ 4.0.2 for MetaboDiff compatibility.)45- **MultiAssayExperiment** (Data container for normalized, imputed metabolite abundance assay and rowData annotation; input to module detection workflow.)4647## Examples4849```50# After loading norm_imputed MultiAssayExperiment and computing biweight midcorr. dissimilarity:51# library(WGCNA); dynamicTreeCut::cutreeDynamic(dendro=hc, distM=dissim_matrix, minClusterSize=5, method='hybrid')52```5354## Evaluation signals5556- Module size distribution respects minimum threshold (all modules ≥ 5 metabolites); no singleton or very small clusters remain.57- Module color assignments are consistent and unique: every metabolite belongs to exactly one module, and colors are visually distinct in dendrogram plots.58- Module pathway composition is coherent: most metabolites in a module share the same or related SUB_PATHWAY label, indicating biological relevance.59- Dendrogram visualization shows branch colors matching module assignments; cutting positions adapt locally to branch heights and cluster tightness, not locked to a single horizontal line.60- Module assignments are stable under small perturbations: recomputing with slightly altered soft-threshold power (β=2.5–3.5) yields similar module boundaries and pathway coherence.6162## Limitations6364- Dynamic branch cutting requires manual setting of minimum module size; no automatic data-driven choice for this threshold is provided in the article.65- Module quality depends critically on upstream correlation metric choice (biweight midcorrelation); if raw data contain systematic biases or unmodeled batch effects, dendrogram structure may be misleading.66- Pathway annotation (SUB_PATHWAY) is optional and tied to external databases (SMPDB, KEGG, HMDB, ChEBI); metabolites without annotation cannot contribute to module naming and require manual interpretation.67- The method assumes metabolites are the only clustering variables; it does not account for sample-level traits or phenotypes during module detection—trait association is performed post-hoc.6869## Evidence7071- [methods] dynamic branch cutting definition: "We employed the dynamic branch cut method developed by Langfelder and colleagues, as constant height cutoffs exhibit suboptimal performance on complicated dendrograms."72- [methods] module detection parameters: "modules are detected by applying a branch cutting method with a minimal module size of 5 metabolites"73- [methods] biweight midcorrelation rationale: "Biweight midcorrelation was used as a similiarity measure as it is more robust to outliers than the absolute correlation coefficient"74- [methods] module naming by pathway: "For each module, identify the most abundant SUB_PATHWAY annotation and assign module names accordingly."75- [readme] key functionality in package: "MetaboDiffs offers the exploration of sample traits in a data-derived metabolic correlation network."
