Introducción a easyLSEA

resultado$meta

Lista con metadatos del análisis: fecha, etiquetas de comparación, motor utilizado, número de lípidos y la llamada original a la función.

resultado$meta$date
resultado$meta$case_lbl
resultado$meta$n_lipids

resultado$lsea

Contiene las estadísticas de enriquecimiento. Los sub-elementos principales son:

# Resultados KS — una fila por conjunto lipídico por nivel de agrupación
head(resultado$lsea$ks)

# Resultados fgsea
head(resultado$lsea$fgsea)

# Tabla combinada con columna de Convergencia
head(resultado$lsea$combined)

Columnas principales en los resultados KS:

Columnas principales en los resultados fgsea:

La columna Convergence en la tabla combinada clasifica cada conjunto como:

resultado$chains

Resultados del análisis de cadenas de ácidos grasos, disponible cuando run_chains = TRUE:

# Long format — una fila por cadena acilo por lípido
head(resultado$chains$parsed)

# Resumen del estado de parseo — una fila por lípido
head(resultado$chains$summary)

# Wide format — una fila por lípido con posiciones sn y totales
head(resultado$chains$wide)

La tabla wide es la más conveniente para reportes. Cada fila es un lípido, con columnas sn1, sn2, sn3, sn4 con las cadenas individuales (e.g. "18:1"), y total_carbons / total_unsat con los totales sumados. La columna chain_type indica cómo interpretar las posiciones sn:

resultado$plots

Lista de objetos ggplot2, disponible cuando plots = TRUE:

# Ver todos los plots disponibles
names(resultado$plots$lsea)
names(resultado$plots$chains)

Convención de nombres para los bubble plots de LSEA:

Niveles: 01_Class (clase lipídica), 02_LMAPS (categoría LIPID MAPS), 03_Functional (categoría funcional).

resultado$input

Los datos de entrada anotados y las columnas de agrupación utilizadas:

# Datos anotados con LipidClass, LipidCategory_LMAPS, etc.
head(resultado$input$data)

# Columnas de agrupación evaluadas
resultado$input$group_cols

Ejecutar los motores por separado

# Paso 1: anotar
anotado <- annotate_lipids(mis_datos_lipidicos, lipid_col = "LipidName")

# Paso 2: ejecutar el enriquecimiento
lsea_res <- run_lsea(
  data      = anotado,
  fc_col    = "logFC",
  engine    = "both",
  case_lbl  = "NASH",
  ref_lbl   = "Control"
)

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

# Paso 4: gráfico de distribución para un nivel específico
p_dist <- plot_distribution(
  data        = anotado,
  lsea_result = lsea_res,
  group_col   = "LipidClass",
  case_lbl    = "NASH",
  ref_lbl     = "Control"
)

Cambiar la métrica de ranking de fgsea

# Por defecto: pi-valor = signo(logFC) × −log10(P.Value)
# Combina magnitud del efecto y significancia estadística

# Alternativa: solo logFC
resultado_fc <- easyLSEA(
  data        = mis_datos_lipidicos,
  engine      = "fgsea",
  fgsea_rank  = "logFC"
)

# Alternativa: estadístico t de LIMMA (requiere columna 't')
resultado_t <- easyLSEA(
  data        = mis_datos_lipidicos,
  engine      = "fgsea",
  fgsea_rank  = "t_stat"
)

Ajustar umbrales de significancia

resultado <- easyLSEA(
  data        = mis_datos_lipidicos,
  min_n       = 5L,      # mínimo 5 lípidos por conjunto
  n_perm      = 5000L,   # más permutaciones para DS_perm_pval
  fgsea_nperm = 20000L   # más permutaciones para fgsea
)

Filtrar por nivel de confianza de anotación

Cuando las anotaciones lipídicas incluyen un rank de confianza (A > B > C > D > E > P), el parámetro min_rank controla qué lípidos entran al análisis de cadenas:

# Por defecto: incluye todos excepto P y NA
resultado_todos <- easyLSEA(data = mis_datos_lipidicos, min_rank = "E")

# Estricto: solo anotaciones de alta confianza (A y B)
resultado_estricto <- easyLSEA(data = mis_datos_lipidicos, min_rank = "B")

# O directamente en parse_lipid_chains
cadenas_estrictas <- parse_lipid_chains(anotado, min_rank = "B")
table(cadenas_estrictas$summary$status)

Los lípidos excluidos por min_rank aparecen en resultado$chains$summary con status excluded_rank_below_X (donde X es el umbral elegido), facilitando auditar qué lípidos fueron filtrados.

KS vs fgsea — ¿cuál usar?

Ambos motores evalúan la misma hipótesis nula (ausencia de enriquecimiento sistemático) pero son sensibles a patrones de señal distintos:

• KS es potente cuando muchos lípidos de una clase se desplazan moderadamente en la misma dirección. Un resultado KS significativo con DirectionalScore ≈ 0 sugiere una diferencia en varianza o forma de la distribución, no un desplazamiento neto — interpretar con precaución.
• fgsea es potente cuando un número reducido de lípidos genera una señal extrema. Un resultado fgsea significativo sin respaldo del KS sugiere que el enriquecimiento es impulsado por pocos lípidos, no por la clase en su conjunto.

Los resultados convergentes (significativos por ambos motores) proporcionan la evidencia más sólida de remodelación coordinada de una clase lipídica.

El DirectionalScore

El DirectionalScore es una diferencia de medias estandarizada (análogo al d de Cohen):

DS = (media_logFC_conjunto − media_logFC_fondo) / DS_combinada

Cuantifica la dirección y magnitud del desplazamiento, independientemente del p-valor KS. Un conjunto puede tener un p-valor KS significativo con un DirectionalScore cercano a cero — este patrón sugiere regulación heterogénea dentro del conjunto.

La métrica pi-valor

Por defecto, fgsea ordena los lípidos por:

pi-valor = signo(logFC) × −log10(P.Value)

Esta métrica combina la dirección del cambio con la confianza estadística, dando mayor peso a los lípidos que están regulados de forma tanto intensa como significativa. Se prefiere al logFC solo cuando los p-valores están disponibles.