metabolite-network-diffusion-propagation
Summary
Propagate candidate metabolite scores through a KEGG-derived metabolic network graph to prioritize annotations by network proximity and topology. This skill ranks metabolite identifications by diffusing association scores across the network, accounting for graph structure via z-score normalization, to produce a final ranked annotation table.
When to use
After cluster-based filtering of KEGG candidates has produced a set of candidate metabolites with assigned scores, but before final annotation ranking. Use this skill when you need to leverage metabolic network context to disambiguate or re-rank candidates—particularly when multiple compounds map to the same peak cluster and you want to prioritize compounds that are topologically central or connected to high-scoring neighbors in the KEGG metabolite network.
When NOT to use
- Input candidate set is empty or contains no valid KEGG compound identifiers that map to the graph
- KEGG metabolite network graph is unavailable, incomplete, or does not cover the metabolite space of interest
- All peaks have been retained by cluster-based filtering and no recovery of removed peaks is needed (though diffusion prioritization may still be useful)
Inputs
- cluster-filtered candidate assignments (compound identifiers with cluster membership and p-value or frequency scores)
- FELLA sample.graph (igraph object: undirected metabolite network from KEGG database)
- input.type specification ('probability' or 'binary')
Outputs
- diffusion scores (propagated association values with z-score normalization)
- recovered peaks (features completely removed by cluster-based filtering)
- Ranked.Tab (final ranked annotation table, ordered by diffusion-prioritized scores)
How to apply
Compute diffusion input scores from cluster-filtered candidate assignments using the diffusion.input function with input.type set to either 'probability' (continuous scores) or 'binary' (presence/absence). Execute set.diffusion on the sample.graph (FELLA R package) to propagate these scores through the metabolite network, allowing high scores to influence neighbors and cascade through connected pathways. Apply z-score normalization to the resulting diffusion scores to account for network topology and node degree heterogeneity. Recover peaks that were completely removed during cluster-based filtering using recoveringPeaks, then merge these recovered peaks with diffusion results by compound identifier. Finally, compile and rank all results using the finalResults function with z-score normalization to generate the final diffusion-prioritized ranked annotation table (Ranked.Tab output).
Related tools
- FELLA (Provides the sample.graph (metabolite network) and set.diffusion function for network-based score propagation with graph topology integration)
- igraph (Underlying graph representation and manipulation library; used to construct and traverse the undirected metabolite network)
- mWISE (Parent package providing diffusion.input, recoveringPeaks, and finalResults functions; orchestrates the full diffusion prioritization workflow) — https://dev.b2s.club/b2slab/mWISE
- R (Execution environment for all diffusion computation, graph operations, and statistical normalization)
Examples
diffusion_scores <- set.diffusion(method = 'z', object = sample.graph, scores = diffusion.input(candidates_filtered, input.type = 'probability')); recovered <- recoveringPeaks(candidates_all, candidates_filtered); ranked_tab <- finalResults(diffusion_scores, recovered, scores = 'z')
Evaluation signals
- Diffusion scores are properly z-score normalized: mean ≈ 0, standard deviation ≈ 1; no NaN or infinite values
- All recovered peaks are successfully merged back into the diffusion results by compound identifier; no missing or duplicated compound entries in final Ranked.Tab
- Final Ranked.Tab is sorted in descending order by diffusion score; ranks are monotonically increasing or decreasing as expected
- Compounds with high-scoring neighbors in the KEGG network receive higher diffusion scores than isolated low-scoring candidates, confirming network topology influence
- Number of rows in final Ranked.Tab equals the union of diffusion-scored candidates and recovered peaks; no data loss
Limitations
- Diffusion prioritization relies on KEGG network completeness and accuracy; missing or incorrect pathway edges will propagate biased scores
- Z-score normalization assumes a roughly normal distribution of raw diffusion scores; highly skewed or bimodal score distributions may not normalize effectively
- Recovered peaks (completely filtered candidates) are re-ranked by diffusion without their original cluster context, potentially placing them lower in the final table regardless of network position
- Network diffusion is sensitive to starting score distribution (input.type choice) and graph density; sparse or disconnected subgraphs may produce uninformative diffusion
- The FELLA sample.graph represents a static metabolic network snapshot; real metabolic capability and context-specific pathway activation are not captured
Evidence
- [other] The diffusion prioritization stage operates by: (1) computing diffusion input from filtered candidates using
diffusion.input; (2) applying set.diffusion with z-score normalization on the FELLA graph to obtain diffusion scores; (3) recovering completely removed peaks with recoveringPeaks; (4) merging the recovered peaks with diffusion results by compound identifier; and (5) building a final ranked table using finalResults function with z-score normalization.: "The diffusion prioritization stage operates by: (1) computing diffusion input from filtered candidates using diffusion.input; (2) applying set.diffusion with z-score normalization on the FELLA"
- [intro] The different diffusion inputs can be computed using the
diffusion.input function. The input.type argument can be set to probability or binary.: "The different diffusion inputs can be computed using the diffusion.input function. The input.type argument can be set to probability or binary."
- [intro] The
z score normalizes the diffusion scores by taking into account the topology of the graph. On the other hand, when scores = raw, no normalization is applied.: "The z score normalizes the diffusion scores by taking into account the topology of the graph. On the other hand, when scores = raw, no normalization is applied."
- [intro] we will now use the sample graph provided by FELLA R package: "we will now use the sample graph provided by FELLA R package"
- [intro] mWISE integrates several strategies to provide a fast annotation of peak-intensity tables. It consists of three main steps aimed at i) matching mass-to-charge ratio values to KEGG database, ii) clustering and filtering the potential KEGG candidates, iii) building a final prioritized list using diffusion in networks: "building a final prioritized list using diffusion in networks"
1---2name: metabolite-network-diffusion-propagation3description: Use when after cluster-based filtering of KEGG candidates has produced a set of candidate metabolites with assigned scores, but before final annotation ranking.4license: CC-BY-4.05---67# metabolite-network-diffusion-propagation89## Summary1011Propagate candidate metabolite scores through a KEGG-derived metabolic network graph to prioritize annotations by network proximity and topology. This skill ranks metabolite identifications by diffusing association scores across the network, accounting for graph structure via z-score normalization, to produce a final ranked annotation table.1213## When to use1415After cluster-based filtering of KEGG candidates has produced a set of candidate metabolites with assigned scores, but before final annotation ranking. Use this skill when you need to leverage metabolic network context to disambiguate or re-rank candidates—particularly when multiple compounds map to the same peak cluster and you want to prioritize compounds that are topologically central or connected to high-scoring neighbors in the KEGG metabolite network.1617## When NOT to use1819- Input candidate set is empty or contains no valid KEGG compound identifiers that map to the graph20- KEGG metabolite network graph is unavailable, incomplete, or does not cover the metabolite space of interest21- All peaks have been retained by cluster-based filtering and no recovery of removed peaks is needed (though diffusion prioritization may still be useful)2223## Inputs2425- cluster-filtered candidate assignments (compound identifiers with cluster membership and p-value or frequency scores)26- FELLA sample.graph (igraph object: undirected metabolite network from KEGG database)27- input.type specification ('probability' or 'binary')2829## Outputs3031- diffusion scores (propagated association values with z-score normalization)32- recovered peaks (features completely removed by cluster-based filtering)33- Ranked.Tab (final ranked annotation table, ordered by diffusion-prioritized scores)3435## How to apply3637Compute diffusion input scores from cluster-filtered candidate assignments using the `diffusion.input` function with `input.type` set to either 'probability' (continuous scores) or 'binary' (presence/absence). Execute `set.diffusion` on the sample.graph (FELLA R package) to propagate these scores through the metabolite network, allowing high scores to influence neighbors and cascade through connected pathways. Apply z-score normalization to the resulting diffusion scores to account for network topology and node degree heterogeneity. Recover peaks that were completely removed during cluster-based filtering using `recoveringPeaks`, then merge these recovered peaks with diffusion results by compound identifier. Finally, compile and rank all results using the `finalResults` function with z-score normalization to generate the final diffusion-prioritized ranked annotation table (Ranked.Tab output).3839## Related tools4041- **FELLA** (Provides the sample.graph (metabolite network) and set.diffusion function for network-based score propagation with graph topology integration)42- **igraph** (Underlying graph representation and manipulation library; used to construct and traverse the undirected metabolite network)43- **mWISE** (Parent package providing diffusion.input, recoveringPeaks, and finalResults functions; orchestrates the full diffusion prioritization workflow) — https://dev.b2s.club/b2slab/mWISE44- **R** (Execution environment for all diffusion computation, graph operations, and statistical normalization)4546## Examples4748```49diffusion_scores <- set.diffusion(method = 'z', object = sample.graph, scores = diffusion.input(candidates_filtered, input.type = 'probability')); recovered <- recoveringPeaks(candidates_all, candidates_filtered); ranked_tab <- finalResults(diffusion_scores, recovered, scores = 'z')50```5152## Evaluation signals5354- Diffusion scores are properly z-score normalized: mean ≈ 0, standard deviation ≈ 1; no NaN or infinite values55- All recovered peaks are successfully merged back into the diffusion results by compound identifier; no missing or duplicated compound entries in final Ranked.Tab56- Final Ranked.Tab is sorted in descending order by diffusion score; ranks are monotonically increasing or decreasing as expected57- Compounds with high-scoring neighbors in the KEGG network receive higher diffusion scores than isolated low-scoring candidates, confirming network topology influence58- Number of rows in final Ranked.Tab equals the union of diffusion-scored candidates and recovered peaks; no data loss5960## Limitations6162- Diffusion prioritization relies on KEGG network completeness and accuracy; missing or incorrect pathway edges will propagate biased scores63- Z-score normalization assumes a roughly normal distribution of raw diffusion scores; highly skewed or bimodal score distributions may not normalize effectively64- Recovered peaks (completely filtered candidates) are re-ranked by diffusion without their original cluster context, potentially placing them lower in the final table regardless of network position65- Network diffusion is sensitive to starting score distribution (input.type choice) and graph density; sparse or disconnected subgraphs may produce uninformative diffusion66- The FELLA sample.graph represents a static metabolic network snapshot; real metabolic capability and context-specific pathway activation are not captured6768## Evidence6970- [other] The diffusion prioritization stage operates by: (1) computing diffusion input from filtered candidates using `diffusion.input`; (2) applying `set.diffusion` with z-score normalization on the FELLA graph to obtain diffusion scores; (3) recovering completely removed peaks with `recoveringPeaks`; (4) merging the recovered peaks with diffusion results by compound identifier; and (5) building a final ranked table using `finalResults` function with z-score normalization.: "The diffusion prioritization stage operates by: (1) computing diffusion input from filtered candidates using `diffusion.input`; (2) applying `set.diffusion` with z-score normalization on the FELLA"71- [intro] The different diffusion inputs can be computed using the `diffusion.input` function. The `input.type` argument can be set to `probability` or `binary`.: "The different diffusion inputs can be computed using the `diffusion.input` function. The `input.type` argument can be set to `probability` or `binary`."72- [intro] The `z` score normalizes the diffusion scores by taking into account the topology of the graph. On the other hand, when `scores = raw`, no normalization is applied.: "The `z` score normalizes the diffusion scores by taking into account the topology of the graph. On the other hand, when `scores = raw`, no normalization is applied."73- [intro] we will now use the sample graph provided by FELLA R package: "we will now use the sample graph provided by FELLA R package"74- [intro] mWISE integrates several strategies to provide a fast annotation of peak-intensity tables. It consists of three main steps aimed at i) matching mass-to-charge ratio values to KEGG database, ii) clustering and filtering the potential KEGG candidates, iii) building a final prioritized list using diffusion in networks: "building a final prioritized list using diffusion in networks"
