easyLSEA

easyLSEA is an R package for biology-aware Lipid Set Enrichment Analysis (LSEA) designed for untargeted lipidomics data. It provides a dual-engine framework (Kolmogorov-Smirnov + fgsea) for testing whether lipid classes, LIPID MAPS categories, and functional categories are coordinately shifted between experimental groups, alongside a dedicated fatty acid chain analysis module.

Key features

• Dual-engine enrichment – KS-based LSEA and fgsea run in parallel; a Convergence column flags sets significant in both.
• Biology-aware annotation – hierarchical prefix matching covering all major lipid classes (GPL, SL, GL, FA, ST, acylcarnitines, oxylipins, bile acids), validated against real VLDL lipidomics data.
• Chain analysis – class-aware parsing of sn-2 (PC, PE, PE O), N-acyl (SM, Cer, HexCer, GlcCer, Hex2Cer, Hex3Cer), long-format (TG, DG, PI, PS, PG, PA, CL), and single-chain (LPC, LPE, LPI, LPG, LPA, LPS, CAR, FFA, CE) species with tile and trend plots. Classes without resolved chain annotations fall back to class-level LSEA automatically.
• Transparent parsing – a per-lipid summary table reports the parsing status of every species, making it easy to audit which lipids entered chain analysis and why others were excluded.
• Three analysis levels – LipidClass, LipidCategory_LMAPS, and LipidCategory_functional tested simultaneously.
• Flexible export – CSV tables, multi-sheet Excel workbook, PDF/PNG plots, and a standalone HTML report via a single export_lsea() call.
• Reproducible – withr::with_seed() for RNG isolation; all parameters exposed as arguments with documented defaults.

Installation

# Install from GitHub
# install.packages("remotes")
remotes::install_github("DavidGO464/easyLSEA")

For the fgsea engine (optional but recommended):

# install.packages("BiocManager")
BiocManager::install("fgsea")

Quick start

library(easyLSEA)

# Load the built-in example dataset
data("lipid_example")

# Run the full pipeline in one call
result <- easyLSEA(
  data      = lipid_example,
  lipid_col = "LipidName",
  fc_col    = "logFC",
  case_lbl  = "NASH",
  ref_lbl   = "Control",
  engine    = "ks"          # or "fgsea" or "both"
)

# Inspect results
print(result)
summary(result)

# Access individual tables
head(result$lsea$ks)         # KS enrichment table
head(result$chains$parsed)   # parsed chain observations

# Export everything
export_lsea(result, dir = "results/", format = c("csv", "excel", "pdf"))

Workflow

Raw lipidomics data (data.frame)
        |
        v
annotate_lipids()          -- assign LipidClass, LipidCategory
        |
        +--------> run_lsea()            -- KS + fgsea enrichment
        |                |
        |                +--> plot_lsea()
        |
        +--------> parse_lipid_chains()  -- chain length & unsaturation
                         |
                         +--> plot_chains()
        |
        v
export_lsea()              -- CSV / Excel / PDF / HTML

Or use the one-call wrapper:

result <- easyLSEA(data, ...)   # runs all of the above

Modular use

Each step can be run independently:

# Step 1 -- annotate
annotated <- annotate_lipids(data, lipid_col = "LipidName")

# Step 2 -- enrichment only
lsea_out <- run_lsea(
  data       = annotated,
  fc_col     = "logFC",
  engine     = "both",
  case_lbl   = "NASH",
  ref_lbl    = "Control"
)

# Step 3 -- chain analysis
chains_out <- parse_lipid_chains(annotated)

# Inspect parsed chains (one row per acyl chain observation)
head(chains_out$parsed)

# Audit parsing: see which lipids were parsed and which were excluded
table(chains_out$summary$status)
#> excluded_class                             parsed
#>            142                                389
#> excluded_total_notation_unresolved_PI          23
#>             23

chain_plots <- plot_chains(chains_out, case_lbl = "NASH", ref_lbl = "Control")

# Step 4 -- export
export_lsea(lsea_out, format = c("csv", "excel"))

Lipid class coverage

Classes follow LIPID MAPS shorthand nomenclature.

Oxylipins are not a formal LIPID MAPS category; oxidized fatty acid species (e.g. HETE, HODE, PGE2) are classified as Fatty Acyls and handled at class-level LSEA only.

Chain analysis framework

The strategy applied to each lipid class depends on its biological structure and the annotation resolution available in the dataset. When individual chains are not resolved, all classes fall back to class-level LSEA automatically.

Citation

If you use easyLSEA in your research, please cite:

Guardamino Ojeda D, et al. (2026). easyLSEA: biology-aware lipid set enrichment analysis with dual KS and fgsea engines. GitHub: https://github.com/DavidGO464/easyLSEA. DOI: https://doi.org/10.5281/zenodo.20341372

Optional dependencies

License

MIT – see LICENSE for details.