normalized-enrichment-score-computation
Summary
Compute Normalized Enrichment Scores (NES) for metabolite sets using the fgsea algorithm to rank and evaluate pathway enrichment. This skill integrates ranked metabolite lists (sorted by test statistic) with pathway-to-metabolite gene set definitions to produce NES values, p-values, and adjusted p-values for each metabolic pathway.
When to use
Apply this skill when you have differential analysis results (p-values and log2 fold changes) from metabolomics data and need to assess whether predefined sets of metabolites (metabolic pathways) show coordinated enrichment patterns. Use it specifically when working with ranked metabolite lists and a PathwayVsMetabolites reference mapping to test if pathway metabolites tend toward high or low ranks in your test statistic distribution.
When NOT to use
- Input metabolites have not been subjected to differential analysis or do not have associated test statistics (p-values, log2 fold changes) — use descriptive or Fisher's exact test enrichment instead.
- The PathwayVsMetabolites mapping is missing, incomplete, or contains pathways with fewer than 5 metabolites after filtering — fgsea requires sufficient pathway size for reliable permutation testing.
- Ranked list contains fewer than ~15–20 metabolites or the metabolite set is too small relative to pathway definitions — permutation-based methods lose power with small sample sizes.
Inputs
- Ranked metabolite list (vector of KEGG IDs or identifiers, sorted by test statistic such as signed p-value or log2 fold change)
- PathwayVsMetabolites reference file (data.frame mapping pathway names to comma-separated metabolite identifiers)
- Differential analysis results (p-values and log2 fold changes; can be precomputed or generated via run_de())
- KEGG lookup table or kegg_id mapping (for resolving metabolite identifiers to KEGG IDs if needed)
Outputs
- MetSEA results table (data.frame with columns: pathway name, Normalized Enrichment Score (NES), nominal p-value, adjusted p-value (padj), and pathway statistics)
- Filtered MetSEA table after significance filtering (padj < 0.05 or user-specified threshold)
- MetSEA plot visualization (S3/S4 ggplot or ComplexHeatmap object showing NES and significance across pathways)
How to apply
Load differential analysis results (p-values, log2 fold changes) and prepare a ranked metabolite list sorted by a combined test statistic (e.g., -log10(p-value) × sign(log2fc) or log2 fold change directly). Load or construct the PathwayVsMetabolites mapping file defining which metabolites belong to each pathway. Execute fgsea with the ranked list and pathway gene set definitions; fgsea computes NES for each pathway by comparing the observed enrichment to a null distribution generated by permutation. Apply significance filtering (typically padj < 0.05) to identify significantly enriched or depleted pathways. Extract the resulting MetSEA table containing pathway names, NES values, nominal p-values, and Benjamini–Hochberg adjusted p-values for downstream interpretation and visualization.
Related tools
- fgsea (Performs fast Metabolite Set Enrichment Analysis, computing Normalized Enrichment Scores and p-values for each pathway via permutation testing against the ranked metabolite list.) — https://bioconductor.org/packages/fgsea
- enrichmet (R package wrapper that orchestrates the complete MetSEA workflow: loads data, prepares ranked lists, calls fgsea, filters results, and generates MetSEA plots alongside pathway enrichment and centrality analyses.) — https://github.com/biodatalab/enrichmet
- KEGGREST (Retrieves pathway-to-metabolite mappings from the KEGG database; used to construct or validate the PathwayVsMetabolites reference file.) — https://bioconductor.org/packages/KEGGREST
- readr / readxl (Loads differential analysis results and reference mapping files (CSV, Excel) into R data.frames for ranking and fgsea input.)
Examples
results <- enrichmet(inputMetabolites = NULL, PathwayVsMetabolites = PathwayVsMetabolites, da_results = da_out, analysis_type = c("gsea"), p_value_cutoff = 0.05)
Evaluation signals
- Ranked metabolite list is properly sorted by test statistic (verify monotonic ordering and expected range, e.g., -log10(p-value) range 0–6+ for typical metabolomics).
- fgsea output contains expected columns: pathway name, NES, pval, padj, and ES (enrichment score) with NES values in the range [−∞, +∞] and p-values in [0, 1].
- Significance filtering produces a reasonable fraction of pathways (typically 5–20% of tested pathways pass padj < 0.05 in well-powered studies; zero or >50% may indicate statistical or biological anomalies).
- Positive NES indicates metabolites in the pathway rank high (toward the top of the ranked list), consistent with upregulation or high fold change; negative NES indicates downregulation or low fold change.
- MetSEA plot shows pathways sorted by NES or padj, with color/size reflecting significance and direction, enabling rapid visual identification of enriched and depleted pathway sets.
Limitations
- fgsea requires ranked lists with sufficient size (~15+ metabolites) and statistical power; underpowered or small studies may produce unreliable NES and permutation p-values.
- PathwayVsMetabolites mapping must be curated and kept up-to-date; outdated or incomplete mappings can miss true enrichment or produce spurious signals.
- NES and p-values are sensitive to the choice of ranking statistic (e.g., log2 fold change vs. signed p-value); different rankings may yield different pathway rankings.
- fgsea uses permutation testing, which is stochastic; results may vary slightly between runs unless a random seed is set.
- Multiple-testing correction (e.g., Benjamini–Hochberg padj) assumes independence across pathway tests, which may be violated if pathways share metabolites.
Evidence
- [other] Prepare ranked metabolite list sorted by test statistic (e.g., log2 fold change or -log10(p-value)) for input to fgsea.: "Prepare ranked metabolite list sorted by test statistic (e.g., log2 fold change or -log10(p-value)) for input to fgsea."
- [other] Execute fgsea with the ranked metabolite list and pathway-to-metabolite gene set definitions, computing Normalized Enrichment Scores (NES) for each metabolite set.: "Execute fgsea with the ranked metabolite list and pathway-to-metabolite gene set definitions, computing Normalized Enrichment Scores (NES) for each metabolite set."
- [other] Apply significance filtering (e.g., padj < 0.05) and extract the MetSEA results table containing pathway names, NES values, p-values, and adjusted p-values.: "Apply significance filtering (e.g., padj < 0.05) and extract the MetSEA results table containing pathway names, NES values, p-values, and adjusted p-values."
- [other] enrichmet integrates fgsea for fast MetSEA and produces a MetSEA results table as one of three output data.frame objects, alongside metabolite centrality and pathway enrichment results.: "enrichmet integrates fgsea for fast MetSEA and produces a MetSEA results table as one of three output data.frame objects"
- [readme] Pathway to metabolite mappings are obtained from the KEGG resource using the KEGGREST package: "pathway to metabolite mappings are obtained from the KEGG resource using the KEGGREST package"
1---2name: normalized-enrichment-score-computation3description: Use when you have differential analysis results (p-values and log2 fold changes) from metabolomics data and need to assess whether predefined sets of metabolites (metabolic pathways) show coordinated enrichment patterns.4license: CC-BY-4.05---67# normalized-enrichment-score-computation89## Summary1011Compute Normalized Enrichment Scores (NES) for metabolite sets using the fgsea algorithm to rank and evaluate pathway enrichment. This skill integrates ranked metabolite lists (sorted by test statistic) with pathway-to-metabolite gene set definitions to produce NES values, p-values, and adjusted p-values for each metabolic pathway.1213## When to use1415Apply this skill when you have differential analysis results (p-values and log2 fold changes) from metabolomics data and need to assess whether predefined sets of metabolites (metabolic pathways) show coordinated enrichment patterns. Use it specifically when working with ranked metabolite lists and a PathwayVsMetabolites reference mapping to test if pathway metabolites tend toward high or low ranks in your test statistic distribution.1617## When NOT to use1819- Input metabolites have not been subjected to differential analysis or do not have associated test statistics (p-values, log2 fold changes) — use descriptive or Fisher's exact test enrichment instead.20- The PathwayVsMetabolites mapping is missing, incomplete, or contains pathways with fewer than 5 metabolites after filtering — fgsea requires sufficient pathway size for reliable permutation testing.21- Ranked list contains fewer than ~15–20 metabolites or the metabolite set is too small relative to pathway definitions — permutation-based methods lose power with small sample sizes.2223## Inputs2425- Ranked metabolite list (vector of KEGG IDs or identifiers, sorted by test statistic such as signed p-value or log2 fold change)26- PathwayVsMetabolites reference file (data.frame mapping pathway names to comma-separated metabolite identifiers)27- Differential analysis results (p-values and log2 fold changes; can be precomputed or generated via run_de())28- KEGG lookup table or kegg_id mapping (for resolving metabolite identifiers to KEGG IDs if needed)2930## Outputs3132- MetSEA results table (data.frame with columns: pathway name, Normalized Enrichment Score (NES), nominal p-value, adjusted p-value (padj), and pathway statistics)33- Filtered MetSEA table after significance filtering (padj < 0.05 or user-specified threshold)34- MetSEA plot visualization (S3/S4 ggplot or ComplexHeatmap object showing NES and significance across pathways)3536## How to apply3738Load differential analysis results (p-values, log2 fold changes) and prepare a ranked metabolite list sorted by a combined test statistic (e.g., -log10(p-value) × sign(log2fc) or log2 fold change directly). Load or construct the PathwayVsMetabolites mapping file defining which metabolites belong to each pathway. Execute fgsea with the ranked list and pathway gene set definitions; fgsea computes NES for each pathway by comparing the observed enrichment to a null distribution generated by permutation. Apply significance filtering (typically padj < 0.05) to identify significantly enriched or depleted pathways. Extract the resulting MetSEA table containing pathway names, NES values, nominal p-values, and Benjamini–Hochberg adjusted p-values for downstream interpretation and visualization.3940## Related tools4142- **fgsea** (Performs fast Metabolite Set Enrichment Analysis, computing Normalized Enrichment Scores and p-values for each pathway via permutation testing against the ranked metabolite list.) — https://bioconductor.org/packages/fgsea43- **enrichmet** (R package wrapper that orchestrates the complete MetSEA workflow: loads data, prepares ranked lists, calls fgsea, filters results, and generates MetSEA plots alongside pathway enrichment and centrality analyses.) — https://github.com/biodatalab/enrichmet44- **KEGGREST** (Retrieves pathway-to-metabolite mappings from the KEGG database; used to construct or validate the PathwayVsMetabolites reference file.) — https://bioconductor.org/packages/KEGGREST45- **readr / readxl** (Loads differential analysis results and reference mapping files (CSV, Excel) into R data.frames for ranking and fgsea input.)4647## Examples4849```50results <- enrichmet(inputMetabolites = NULL, PathwayVsMetabolites = PathwayVsMetabolites, da_results = da_out, analysis_type = c("gsea"), p_value_cutoff = 0.05)51```5253## Evaluation signals5455- Ranked metabolite list is properly sorted by test statistic (verify monotonic ordering and expected range, e.g., -log10(p-value) range 0–6+ for typical metabolomics).56- fgsea output contains expected columns: pathway name, NES, pval, padj, and ES (enrichment score) with NES values in the range [−∞, +∞] and p-values in [0, 1].57- Significance filtering produces a reasonable fraction of pathways (typically 5–20% of tested pathways pass padj < 0.05 in well-powered studies; zero or >50% may indicate statistical or biological anomalies).58- Positive NES indicates metabolites in the pathway rank high (toward the top of the ranked list), consistent with upregulation or high fold change; negative NES indicates downregulation or low fold change.59- MetSEA plot shows pathways sorted by NES or padj, with color/size reflecting significance and direction, enabling rapid visual identification of enriched and depleted pathway sets.6061## Limitations6263- fgsea requires ranked lists with sufficient size (~15+ metabolites) and statistical power; underpowered or small studies may produce unreliable NES and permutation p-values.64- PathwayVsMetabolites mapping must be curated and kept up-to-date; outdated or incomplete mappings can miss true enrichment or produce spurious signals.65- NES and p-values are sensitive to the choice of ranking statistic (e.g., log2 fold change vs. signed p-value); different rankings may yield different pathway rankings.66- fgsea uses permutation testing, which is stochastic; results may vary slightly between runs unless a random seed is set.67- Multiple-testing correction (e.g., Benjamini–Hochberg padj) assumes independence across pathway tests, which may be violated if pathways share metabolites.6869## Evidence7071- [other] Prepare ranked metabolite list sorted by test statistic (e.g., log2 fold change or -log10(p-value)) for input to fgsea.: "Prepare ranked metabolite list sorted by test statistic (e.g., log2 fold change or -log10(p-value)) for input to fgsea."72- [other] Execute fgsea with the ranked metabolite list and pathway-to-metabolite gene set definitions, computing Normalized Enrichment Scores (NES) for each metabolite set.: "Execute fgsea with the ranked metabolite list and pathway-to-metabolite gene set definitions, computing Normalized Enrichment Scores (NES) for each metabolite set."73- [other] Apply significance filtering (e.g., padj < 0.05) and extract the MetSEA results table containing pathway names, NES values, p-values, and adjusted p-values.: "Apply significance filtering (e.g., padj < 0.05) and extract the MetSEA results table containing pathway names, NES values, p-values, and adjusted p-values."74- [other] enrichmet integrates fgsea for fast MetSEA and produces a MetSEA results table as one of three output data.frame objects, alongside metabolite centrality and pathway enrichment results.: "enrichmet integrates fgsea for fast MetSEA and produces a MetSEA results table as one of three output data.frame objects"75- [readme] Pathway to metabolite mappings are obtained from the KEGG resource using the KEGGREST package: "pathway to metabolite mappings are obtained from the KEGG resource using the KEGGREST package"
