# Metabolite Network Diffusion Propagation

> Use when after cluster-based filtering of KEGG candidates has produced a set of candidate metabolites with assigned scores, but before final annotation ranking.

- Skill: `holobiomicslab/metabolite-network-diffusion-propagation` (Agent Skill)
- Install (CLI): `npx skillmds@latest add holobiomicslab/metabolite-network-diffusion-propagation`
- Raw SKILL.md: https://api.skillmd.com/api/skills/holobiomicslab/metabolite-network-diffusion-propagation/raw
- Safety review: PASS (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: CC-BY-4.0
- Author: HolobiomicsLab (https://skillmd.com/u/holobiomicslab)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/holobiomicslab/metabolite-network-diffusion-propagation

---


# 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"