Introduction to easyLSEA

result$meta

A named list with run metadata: date, comparison labels, engine used, number of lipids, and the original function call.

result$meta$date
result$meta$case_lbl
result$meta$n_lipids

result$lsea

Contains the enrichment statistics. The key sub-elements are:

# KS results — one row per lipid set per grouping level
head(result$lsea$ks)

# fgsea results
head(result$lsea$fgsea)

# Combined table with Convergence column
head(result$lsea$combined)

Key columns in the KS results:

Key columns in the fgsea results:

The Convergence column in the combined table classifies each set as:

result$chains

Fatty acid chain analysis results, available when run_chains = TRUE:

# Long format — one row per acyl chain per lipid
head(result$chains$parsed)

# Parsing status — one row per lipid
head(result$chains$summary)

# Wide format — one row per lipid with sn positions and totals
head(result$chains$wide)

The wide table is the most convenient for reporting. Each row is one lipid, with columns sn1, sn2, sn3, sn4 containing the individual acyl chain positions (e.g. "18:1"), and total_carbons / total_unsat with the summed totals. The chain_type column clarifies how to interpret the sn columns:

result$plots

A named list of ggplot2 objects, available when plots = TRUE:

# List all available plots
names(result$plots$lsea)
names(result$plots$chains)

Plot naming convention for LSEA bubble plots:

Levels: 01_Class (lipid class), 02_LMAPS (LIPID MAPS category), 03_Functional (functional category).

result$input

The annotated input data and the grouping columns used:

# Annotated data with LipidClass, LipidCategory_LMAPS, etc.
head(result$input$data)

# Grouping columns tested
result$input$group_cols

Running engines separately

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

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

# Step 3: generate plots manually
plots <- plot_lsea(
  lsea_res,
  case_lbl     = "NASH",
  ref_lbl      = "Control",
  fdr_thresh   = 0.05,
  bubble_label = c("FDR", "DS", "NES", "n")
)

# Step 4: distribution plot for a specific level
p_dist <- plot_distribution(
  data        = annotated,
  lsea_result = lsea_res,
  group_col   = "LipidClass",
  case_lbl    = "NASH",
  ref_lbl     = "Control"
)

Changing the fgsea rank metric

# Default: pi-value = sign(logFC) * -log10(P.Value)
# Combines effect size and statistical evidence

# Alternative: logFC only
result_fc <- easyLSEA(
  data        = my_lipid_data,
  engine      = "fgsea",
  fgsea_rank  = "logFC"
)

# Alternative: LIMMA t-statistic (requires a 't' column)
result_t <- easyLSEA(
  data        = my_lipid_data,
  engine      = "fgsea",
  fgsea_rank  = "t_stat"
)

Adjusting significance thresholds

result <- easyLSEA(
  data      = my_lipid_data,
  min_n     = 5L,      # require at least 5 lipids per set
  n_perm    = 5000L,   # more permutations for DS_perm_pval
  fgsea_nperm = 20000L # more permutations for fgsea
)

Filtering by annotation confidence rank

When lipid annotations include a confidence rank (A > B > C > D > E > P), min_rank controls which lipids enter the chain analysis:

# Default: include all except P and NA
result_all <- easyLSEA(data = my_lipid_data, min_rank = "E")

# Strict: include only high-confidence annotations (A and B)
result_strict <- easyLSEA(data = my_lipid_data, min_rank = "B")

# Or apply directly to parse_lipid_chains
chains_strict <- parse_lipid_chains(annotated, min_rank = "B")
table(chains_strict$summary$status)

Lipids excluded by min_rank appear in result$chains$summary with status excluded_rank_below_X (where X is the chosen threshold), making it easy to audit which lipids were filtered.

KS vs fgsea — which to trust?

Both engines test the same null hypothesis (no systematic enrichment) but are sensitive to different signal patterns:

• KS is powerful when many lipids in a class shift moderately in the same direction. A significant KS result with DirectionalScore ≈ 0 suggests a variance or shape difference rather than a net directional shift — interpret with caution.
• fgsea is powerful when a small number of lipids drive an extreme signal. A significant fgsea result without KS support suggests the enrichment is carried by a few lipids rather than the class as a whole.

Convergent results (significant by both) provide the strongest evidence for coordinated lipid class remodeling.

The DirectionalScore

The DirectionalScore is a standardized mean difference (Cohen’s d analog):

DS = (mean_logFC_set - mean_logFC_background) / SD_pooled

It quantifies the direction and magnitude of the shift, independent of the KS p-value. A set can have a significant KS p-value (distributional difference) with a near-zero DirectionalScore (no net direction) — this pattern suggests heterogeneous within-set regulation.

The pi-value rank metric

By default, fgsea ranks lipids by:

pi-value = sign(logFC) × −log10(P.Value)

This combines the direction of change with statistical confidence, giving more weight to lipids that are both strongly and significantly regulated. It is preferred over logFC alone when p-values are available.