Normalized Enrichment Score Computation

---
name: normalized-enrichment-score-computation
description: 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.
license: CC-BY-4.0
metadata:
  edam_operation: http://edamontology.org/operation_3501
  edam_topics:
  - http://edamontology.org/topic_0639
  - http://edamontology.org/topic_3520
  tools:
  - R
  - fgsea
  - readr
  - readxl
  - enrichmet
  - KEGGREST
  - readr / readxl
  license_tier: open
  provenance_tier: literature
derived_from:
- doi: 10.1101/2025.08.28.672951v2
  title: EnrichMET
evidence_spans:
- simplifies pathway enrichment analysis by allowing the complete workflow to be executed
  through a single R function call
- enrichmet integrates fgsea for fast MetSEA
- library(readr)
- library(readxl)
claims: []
provenance:
  collection: https://w3id.org/holobiomicslab/asb-skill/collection/metabolomics/v2
  assembled_by: scripts/collect_metabolomics_collection.py
  sources:
  - build: coll_enrichmet_cq
    doi: 10.1101/2025.08.28.672951v2
    title: EnrichMET
  dedup_kept_from: coll_enrichmet_cq
schema_version: 0.2.0
attribution:
  generator: AgenticScienceBuilder
  original_doi: 10.1101/2025.08.28.672951v2
  all_source_dois:
  - 10.1101/2025.08.28.672951v2
  zenodo_doi: 10.5281/zenodo.20794027
  curators: []
  promoter: Louis-Félix Nothias
  sponsor: CNRS & Université Côte d'Azur
---

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