multiGSEA

https://github.com/yigbt/multigsea
Admin
multiGSEA is an R package for GSEA-based pathway enrichment analysis that integrates multiple omics...
Tokens:13,954
Snippets:110
Trust Score:5.3
Update:6 months ago
Show doc for...
Tokens:
Raw
### Install multiGSEA via Bioconductor

Source: https://github.com/yigbt/multigsea/blob/devel/README.md

Standard installation method using the BiocManager package.

```R
if (!requireNamespace("BiocManager", quietly = TRUE))
  install.packages("BiocManager")

BiocManager::install("multiGSEA")
```

--------------------------------

### Install multiGSEA via GitHub

Source: https://github.com/yigbt/multigsea/blob/devel/README.md

Installation method for the latest development version using devtools.

```R
install.packages("devtools")
devtools::install_github("https://github.com/yigbt/multiGSEA")
```

--------------------------------

### Install multiGSEA Package

Source: https://context7.com/yigbt/multigsea/llms.txt

Installs the multiGSEA package from Bioconductor or development version from GitHub. Load the package using library(multiGSEA).

```r
if (!requireNamespace("BiocManager", quietly = TRUE))
    install.packages("BiocManager")

BiocManager::install("multiGSEA")

# Or install development version from GitHub
install.packages("devtools")
devtools::install_github("https://github.com/yigbt/multiGSEA")

# Load the package
library(multiGSEA)
```

--------------------------------

### Load multiGSEA package

Source: https://github.com/yigbt/multigsea/blob/devel/README.md

Load the package into the R session after installation.

```R
library(multiGSEA)
```

--------------------------------

### Get Supported Organisms for ID Mapping

Source: https://context7.com/yigbt/multigsea/llms.txt

Retrieves a list of organisms for which AnnotationDbi packages are available, enabling ID mapping for pathway analysis. Lists the organism codes and their corresponding AnnotationDbi packages.

```r
library(multiGSEA)

# Get all supported organisms
organisms <- getOrganisms()
print(organisms)
# [1] "hsapiens"      "rnorvegicus"   "mmusculus"     "sscrofa"
# [5] "btaurus"       "celegans"      "dmelanogaster" "drerio"
# [9] "ggallus"       "xlaevis"       "cfamiliaris"

# Organism mapping to AnnotationDbi packages:
# hsapiens      -> org.Hs.eg.db (Human)
# mmusculus     -> org.Mm.eg.db (Mouse)
# rnorvegicus   -> org.Rn.eg.db (Rat)
# cfamiliaris   -> org.Cf.eg.db (Dog)
# btaurus       -> org.Bt.eg.db (Cow)
# sscrofa       -> org.Ss.eg.db (Pig)
# ggallus       -> org.Gg.eg.db (Chicken)
# drerio        -> org.Dr.eg.db (Zebrafish)
# xlaevis       -> org.Xl.eg.db (Frog)
# dmelanogaster -> org.Dm.eg.db (Fruit Fly)
# celegans      -> org.Ce.eg.db (C.elegans)
```

--------------------------------

### Get Multi-Omics Features

Source: https://context7.com/yigbt/multigsea/llms.txt

Retrieves pathway definitions from multiple databases (KEGG, Reactome) for specified omics layers. Handles organism and feature ID mapping. Use `useLocal = TRUE` to leverage cached data.

```r
# Applied internally when pathways from multiple databases have same names
pathways <- getMultiOmicsFeatures(
    dbs = c("kegg", "reactome"),
    layer = c("transcriptome")
)
# Duplicate pathway titles are automatically renamed:
# "(KEGG) Apoptosis" and "(REACTOME) Apoptosis" remain distinct
# But if same database has duplicate titles, they become "Apoptosis_1", "Apoptosis_2"
```

--------------------------------

### Rank Features for GSEA

Source: https://context7.com/yigbt/multigsea/llms.txt

Ranks features using the formula: sign(logFC) * -log10(p-value). This function is essential for preparing data for GSEA. Example shows ranking random data and then applying it to loaded omics datasets.

```r
library(multiGSEA)

# Example with random data
logFC <- c(2.5, -1.3, 0.8, -2.1, 1.5)
pvalues <- c(0.001, 0.05, 0.2, 0.0001, 0.01)

ranked <- rankFeatures(logFC, pvalues)
# Result: 3.0 -1.30103 0.69897 -4.0 2.0

# Complete workflow with real data
data(transcriptome)
data(proteome)
data(metabolome)

omics_data <- initOmicsDataStructure(layer = c("transcriptome", "proteome", "metabolome"))

# Rank transcriptome features
omics_data$transcriptome <- rankFeatures(transcriptome$logFC, transcriptome$pValue)
names(omics_data$transcriptome) <- transcriptome$Symbol

# Rank proteome features
omics_data$proteome <- rankFeatures(proteome$logFC, proteome$pValue)
names(omics_data$proteome) <- proteome$Symbol

# Rank metabolome features (update HMDB format if needed)
omics_data$metabolome <- rankFeatures(metabolome$logFC, metabolome$pValue)
names(omics_data$metabolome) <- gsub("HMDB", "HMDB00", metabolome$HMDB)

# View ranked features
head(omics_data$transcriptome)
#     A1BG    A1CF    A2M A2ML1   A4GALT  A4GNT
# 2.154902 0.457575 -1.234568 3.201654 0.891234 -2.345678
```

--------------------------------

### Display Supported Organisms Table

Source: https://github.com/yigbt/multigsea/blob/devel/vignettes/multiGSEA.rmd

Generates a table of supported organisms and their corresponding AnnotationDbi packages.

```r
caption <- "Supported organisms, their abbreviations being used in `multiGSEA`,
            and mapping database that are needed for feature conversion.
            Supported abbreviations can be seen with `getOrganisms()`"
df <- data.frame(
  Organisms = c(
    "Human", "Mouse", "Rat", "Dog", "Cow", "Pig",
    "Chicken", "Zebrafish", "Frog", "Fruit Fly",
    "C.elegans"
  ),
  Abbreviations = c(
    "hsapiens", "mmusculus", "rnorvegicus",
    "cfamiliaris", "btaurus", "sscrofa",
    "ggallus", "drerio", "xlaevis",
    "dmelanogaster", "celegans"
  ),
  Mapping = c(
    "org.Hs.eg.db", "org.Mm.eg.db", "org.Rn.eg.db",
    "org.Cf.eg.db", "org.Bt.eg.db", "org.Ss.eg.db",
    "org.Gg.eg.db", "org.Xl.eg.db", "org.Dr.eg.db",
    "org.Dm.eg.db", "org.Ce.eg.db"
  )
)

knitr::kable(df, caption = caption)
```

--------------------------------

### multiGSEA Core Function

Source: https://context7.com/yigbt/multigsea/llms.txt

This section demonstrates the core workflow of the multiGSEA package, from initializing the omics data structure to running the multiGSEA enrichment analysis and viewing the results.

```APIDOC
## multiGSEA

Performs multi-omics Gene Set Enrichment Analysis (GSEA).

### Description
This function takes ranked omics data and pathway features to compute enrichment scores for each pathway across different omics layers.

### Method
`multiGSEA(pathways, omics_data, eps = 1e-100)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **pathways** (list) - A list of pathway features, typically generated by `getMultiOmicsFeatures`.
- **omics_data** (list) - A list where each element is a named vector of ranked features for a specific omics layer (e.g., transcriptome, proteome, metabolome).
- **eps** (numeric, optional) - A small value to adjust p-value precision. Defaults to 1e-100.

### Request Example
```r
# Assuming omics_data and pathways are already prepared as shown in the package vignette
# omics_data <- initOmicsDataStructure(...)
# omics_data$transcriptome <- rankFeatures(...)
# ... (similar for proteome and metabolome)
# pathways <- getMultiOmicsFeatures(...)

enrichment_scores <- multiGSEA(pathways, omics_data)
```

### Response
#### Success Response (200)
- **enrichment_scores** (list) - A list where each element corresponds to an omics layer (e.g., 'transcriptome', 'proteome', 'metabolome'). Each element is a data frame containing pathway enrichment results, including columns like 'pathway', 'pval', 'padj', 'log2err', and 'ES'.

#### Response Example
```r
# Example structure of enrichment_scores$transcriptome
#                                pathway     pval     padj   log2err        ES
# 1  (KEGG) Glycolysis / Gluconeogenesis 0.001234 0.023456 0.4567890 0.4521234
# 2      (KEGG) Citrate cycle (TCA cycle) 0.000123 0.004567 0.5678901 0.5234567
```
```

--------------------------------

### Load and Prepare Multi-Omics Data

Source: https://context7.com/yigbt/multigsea/llms.txt

Loads transcriptome, proteome, and metabolome data, then initializes the omics data structure and ranks features using logFC and p-value. Ensure feature IDs match expected formats (Symbol, HMDB, etc.).

```r
library(multiGSEA)
library(org.Hs.eg.db)
library(magrittr)
library(dplyr)

# ====================
# 1. Load omics data
# ====================
data(transcriptome)
data(proteome)
data(metabolome)

# Data format required: data frame with columns:
# - Feature ID (Symbol, HMDB, etc.)
# - logFC (log2 fold change)
# - pValue

# ====================
# 2. Create ranked data structure
# ====================
omics_data <- initOmicsDataStructure(
    layer = c("transcriptome", "proteome", "metabolome")
)

omics_data$transcriptome <- rankFeatures(transcriptome$logFC, transcriptome$pValue)
names(omics_data$transcriptome) <- transcriptome$Symbol

omics_data$proteome <- rankFeatures(proteome$logFC, proteome$pValue)
names(omics_data$proteome) <- proteome$Symbol

omics_data$metabolome <- rankFeatures(metabolome$logFC, metabolome$pValue)
names(omics_data$metabolome) <- gsub("HMDB", "HMDB00", metabolome$HMDB)
```

--------------------------------

### Initialize Data Structure and Rank Features

Source: https://github.com/yigbt/multigsea/blob/devel/vignettes/multiGSEA.rmd

Initializes the multiGSEA data structure and calculates ranked features for each omics layer.

```r
# create data structure
omics_data <- initOmicsDataStructure(layer = c(
  "transcriptome",
  "proteome",
  "metabolome"
))

## add transcriptome layer
omics_data$transcriptome <- rankFeatures(
  transcriptome$logFC,
  transcriptome$pValue
)
names(omics_data$transcriptome) <- transcriptome$Symbol

## add proteome layer
omics_data$proteome <- rankFeatures(proteome$logFC, proteome$pValue)
names(omics_data$proteome) <- proteome$Symbol

## add metabolome layer
```

--------------------------------

### Initialize multiGSEA analysis

Source: https://context7.com/yigbt/multigsea/llms.txt

Entry point for calculating enrichment scores across multiple omics layers.

```r
library(multiGSEA)
library(org.Hs.eg.db)
```

--------------------------------

### Load multiGSEA Package

Source: https://github.com/yigbt/multigsea/blob/devel/vignettes/multiGSEA.rmd

Loads the multiGSEA package and magrittr for pipeline operations.

```r
library(multiGSEA)
library(magrittr)
```

--------------------------------

### Initialize Omics Data Structure

Source: https://context7.com/yigbt/multigsea/llms.txt

Creates an empty nested list structure to hold ranked omics features for pathway enrichment. Supports specifying which omics layers to include.

```r
library(multiGSEA)

# Create data structure for all three omics layers
omics_data <- initOmicsDataStructure(layer = c("transcriptome", "proteome", "metabolome"))

# Create data structure for two layers only
omics_data_2layer <- initOmicsDataStructure(c("transcriptome", "proteome"))

# Result structure:
# List of 3
#  $ transcriptome: list()
#  $ proteome     : list()
#  $ metabolome   : list()
```

--------------------------------

### Load Mapping Library

Source: https://github.com/yigbt/multigsea/blob/devel/vignettes/multiGSEA.rmd

Loads the required annotation database for human cell line data.

```r
library("org.Hs.eg.db")
```

--------------------------------

### Download Pathway Definitions

Source: https://context7.com/yigbt/multigsea/llms.txt

Downloads pathway definitions from KEGG and Reactome for specified omics layers. Uses cached data if available and maps features to SYMBOL for transcriptome/proteome and HMDB for metabolome.

```r
pathways <- getMultiOmicsFeatures(
    dbs = c("kegg", "reactome"),
    layer = names(omics_data),
    returnTranscriptome = "SYMBOL",
    returnProteome = "SYMBOL",
    returnMetabolome = "HMDB",
    organism = "hsapiens",
    useLocal = TRUE  # Use cached data if available
)
```

--------------------------------

### Display results table

Source: https://github.com/yigbt/multigsea/blob/devel/vignettes/multiGSEA.rmd

Generates a formatted table of the top 15 pathways sorted by combined adjusted p-values.

```R
caption <- "Table summarizing the top 15 pathways where we can calculate an
            enrichment for all three layers . Pathways from KEGG, Reactome,
            and BioCarta are listed based on their aggregated adjusted p-value.
            Corrected p-values are displayed for each omics layer separately and
            aggregated by means of the Stouffer's Z-method."

knitr::kable(
  df %>%
    dplyr::arrange(combined_padj) %>%
    dplyr::filter(!is.na(metabolome_padj)) %>%
    dplyr::select(c(pathway, transcriptome_padj, proteome_padj, metabolome_padj, combined_pval)) %>%
    dplyr::slice(1:15),
  caption = caption
)
```

--------------------------------

### Download pathway definitions

Source: https://github.com/yigbt/multigsea/blob/devel/vignettes/multiGSEA.rmd

Selects databases and omics layers to download and map pathway features.

```R
databases <- c("kegg", "reactome")
layers <- names(omics_data)

pathways <- getMultiOmicsFeatures(
  dbs = databases, layer = layers,
  returnTranscriptome = "SYMBOL",
  returnProteome = "SYMBOL",
  returnMetabolome = "HMDB",
  useLocal = FALSE
)
```

--------------------------------

### Run multi-omics GSEA enrichment

Source: https://context7.com/yigbt/multigsea/llms.txt

Initializes the omics data structure, retrieves pathway features, and executes the multiGSEA enrichment analysis.

```r
data(transcriptome)
data(proteome)
data(metabolome)

# Step 1: Create and rank omics data structure
omics_data <- initOmicsDataStructure(layer = c("transcriptome", "proteome", "metabolome"))

omics_data$transcriptome <- rankFeatures(transcriptome$logFC, transcriptome$pValue)
names(omics_data$transcriptome) <- transcriptome$Symbol

omics_data$proteome <- rankFeatures(proteome$logFC, proteome$pValue)
names(omics_data$proteome) <- proteome$Symbol

omics_data$metabolome <- rankFeatures(metabolome$logFC, metabolome$pValue)
names(omics_data$metabolome) <- gsub("HMDB", "HMDB00", metabolome$HMDB)

# Step 2: Get pathway features
pathways <- getMultiOmicsFeatures(
    dbs = c("kegg", "reactome"),
    layer = c("transcriptome", "proteome", "metabolome"),
    returnTranscriptome = "SYMBOL",
    returnProteome = "SYMBOL",
    returnMetabolome = "HMDB",
    organism = "hsapiens"
)

# Step 3: Run multi-omics GSEA enrichment
enrichment_scores <- multiGSEA(pathways, omics_data)

# Optional: adjust eps parameter for p-value precision
enrichment_scores <- multiGSEA(pathways, omics_data, eps = 1e-50)
```

--------------------------------

### getOrganisms

Source: https://context7.com/yigbt/multigsea/llms.txt

Retrieves a list of supported organisms for ID mapping and pathway annotation.

```APIDOC
## getOrganisms

### Description
Returns a list of all supported organisms that have AnnotationDbi packages available for ID mapping and graphite pathway annotations.

### Request Example
```r
organisms <- getOrganisms()
```
```

--------------------------------

### Inspect pathway definitions

Source: https://github.com/yigbt/multigsea/blob/devel/vignettes/multiGSEA.rmd

Displays the first two pathway definitions for each omics layer.

```R
pathways_short <- lapply(names(pathways), function(name) {
  head(pathways[[name]], 2)
})
names(pathways_short) <- names(pathways)
pathways_short
```

--------------------------------

### Custom Gene Sets with MSigDB

Source: https://context7.com/yigbt/multigsea/llms.txt

Demonstrates using custom gene sets from MSigDB for enrichment analysis. Requires data with Ensembl IDs and prepares a custom pathway structure for a single omics layer.

```r
library(multiGSEA)
library(msigdbr)
library(dplyr)

# Retrieve HALLMARK gene sets from MSigDB
hallmark <- msigdbr(species = "Rattus norvegicus", category = "H") %>%
    dplyr::select(gs_name, ensembl_gene) %>%
    dplyr::filter(!is.na(ensembl_gene)) %>%
    unstack(ensembl_gene ~ gs_name)

# Create custom pathway structure (single omics layer)
custom_pathways <- list("transcriptome" = hallmark)

# Create ranked data with matching ID format (Ensembl)
omics_data <- initOmicsDataStructure(layer = c("transcriptome"))
omics_data$transcriptome <- rankFeatures(your_data$logFC, your_data$pValue)
names(omics_data$transcriptome) <- your_data$ensembl_id

# Run enrichment with custom gene sets
enrichment <- multiGSEA(custom_pathways, omics_data)
```

--------------------------------

### Map metabolite identifiers with getMetaboliteMapping

Source: https://context7.com/yigbt/multigsea/llms.txt

Convert metabolite identifiers using the metaboliteIDmapping package. Supports various common chemical identifier formats.

```r
library(multiGSEA)
library(graphite)

# Extract KEGG compound IDs from a pathway
pathway <- graphite::pathways("hsapiens", "kegg")[[1]]
features <- graphite::nodes(pathway, which = "metabolites")
features <- gsub("KEGGCOMP:", "", features)
head(features)

# Map KEGG IDs to HMDB (default)
hmdb_ids <- getMetaboliteMapping(features, keytype = "KEGG")
head(hmdb_ids)

# Map KEGG IDs to PubChem CID
pubchem_ids <- getMetaboliteMapping(
    features,
    keytype = "KEGG",
    returntype = "CID"
)

# Map ChEBI IDs to Drugbank
chebi_features <- c("CHEBI:15361", "CHEBI:16236")
chebi_features <- gsub("CHEBI:", "", chebi_features)
drugbank_ids <- getMetaboliteMapping(
    chebi_features,
    keytype = "ChEBI",
    returntype = "Drugbank"
)
```

--------------------------------

### Display Session Information

Source: https://github.com/yigbt/multigsea/blob/devel/vignettes/multiGSEA.rmd

Outputs the session information of the R environment, which is useful for debugging and ensuring reproducibility of analyses.

```r
sessionInfo()
```

--------------------------------

### getMetaboliteMapping

Source: https://context7.com/yigbt/multigsea/llms.txt

Maps metabolite identifiers between different formats using the metaboliteIDmapping AnnotationHub package.

```APIDOC
## getMetaboliteMapping

### Description
Maps metabolite identifiers between different formats using the metaboliteIDmapping AnnotationHub package, which contains extensive compound mappings.

### Method
`getMetaboliteMapping`

### Parameters
#### Arguments
- **features** (character vector) - Required - A vector of metabolite identifiers.
- **keytype** (character) - Required - The ID type of the input `features` (e.g., "KEGG", "ChEBI").
- **returntype** (character) - Optional - The desired output ID format (e.g., "HMDB", "CID"). Defaults to "HMDB".

### Request Example
```R
features <- c("C00022", "C00024") # Example KEGG compound IDs
hmdb_ids <- getMetaboliteMapping(features, keytype = "KEGG", returntype = "HMDB")
```

### Response
#### Success Response
A character vector of mapped metabolite identifiers in the specified `returntype`.

#### Response Example
```R
# Example for mapping KEGG IDs to HMDB
# [1] "HMDB0000243" "HMDB0001206"
```
```

--------------------------------

### Download Pathway Features for Multi-Omics Analysis

Source: https://context7.com/yigbt/multigsea/llms.txt

Downloads pathway definitions from specified databases and extracts relevant features for given omics layers and organism. The output is a nested list structure required for multi-omics enrichment calculations.

```r
library(multiGSEA)
library(org.Hs.eg.db)

# Basic usage: get pathway features for transcriptome and proteome from KEGG
pathways <- getMultiOmicsFeatures(
    dbs = c("kegg"),
    layer = c("transcriptome", "proteome"),
    organism = "hsapiens"
)

```

--------------------------------

### Load Omics Data

Source: https://github.com/yigbt/multigsea/blob/devel/vignettes/multiGSEA.rmd

Loads preprocessed transcriptomic, proteomic, and metabolomic datasets.

```r
# load transcriptomic features
data(transcriptome)

# load proteomic features
data(proteome)

# load metabolomic features
data(metabolome)
```

--------------------------------

### Display Omics Data Structure

Source: https://github.com/yigbt/multigsea/blob/devel/vignettes/multiGSEA.rmd

Displays the first six rows of the transcriptome data frame.

```r
caption <- "Structure of the necessary omics data. For each layer
            (here: transcriptome), feature IDs, log2FCs, and p-values
            are needed."

knitr::kable(
  transcriptome %>%
    dplyr::arrange(Symbol) %>%
    dplyr::slice(1:6),
  caption = caption
)
```

--------------------------------

### Map gene identifiers with getGeneMapping

Source: https://context7.com/yigbt/multigsea/llms.txt

Convert gene or protein identifiers between formats using AnnotationDbi. Ensure the appropriate organism-specific database package is loaded.

```r
library(multiGSEA)
library(graphite)
library(org.Hs.eg.db)

# Extract Entrez IDs from a KEGG pathway
pathway <- graphite::pathways("hsapiens", "kegg")[[1]]
features <- graphite::nodes(pathway)
features <- gsub("ENTREZID:", "", features)
head(features)

# Map Entrez IDs to Gene Symbols (default)
symbols <- getGeneMapping(features, keytype = "ENTREZID")
head(symbols)

# Map Entrez IDs to Uniprot
uniprot <- getGeneMapping(
    features,
    keytype = "ENTREZID",
    returntype = "UNIPROT"
)

# Map Entrez IDs to Ensembl
ensembl <- getGeneMapping(
    features,
    keytype = "ENTREZID",
    returntype = "ENSEMBL"
)

# Rat mapping example
library(org.Rn.eg.db)
rat_pathway <- graphite::pathways("rnorvegicus", "reactome")[[1]]
rat_features <- graphite::nodes(rat_pathway)
rat_features <- gsub("UNIPROT:", "", rat_features)
rat_symbols <- getGeneMapping(
    rat_features,
    keytype = "UNIPROT",
    org = "rnorvegicus",
    returntype = "SYMBOL"
)
```

--------------------------------

### Inspect omics data layers

Source: https://github.com/yigbt/multigsea/blob/devel/vignettes/multiGSEA.rmd

Displays the first elements of each omics layer.

```R
omics_short <- lapply(names(omics_data), function(name) {
  head(omics_data[[name]])
})
names(omics_short) <- names(omics_data)
omics_short
```

--------------------------------

### getGeneMapping

Source: https://context7.com/yigbt/multigsea/llms.txt

Maps gene/protein identifiers between different ID formats using AnnotationDbi packages.

```APIDOC
## getGeneMapping

### Description
Maps gene/protein identifiers between different ID formats using AnnotationDbi packages. Useful for converting pathway-encoded features to your measurement ID format.

### Method
`getGeneMapping`

### Parameters
#### Arguments
- **features** (character vector) - Required - A vector of gene/protein identifiers.
- **keytype** (character) - Required - The ID type of the input `features` (e.g., "ENTREZID", "UNIPROT").
- **org** (character) - Optional - Organism identifier (e.g., "hsapiens", "rnorvegicus"). Defaults to human if not specified.
- **returntype** (character) - Optional - The desired output ID format (e.g., "SYMBOL", "ENSEMBL"). Defaults to "SYMBOL".

### Request Example
```R
library(org.Hs.eg.db)
features <- c("2632", "2645", "5230") # Example Entrez IDs
symbols <- getGeneMapping(features, keytype = "ENTREZID", org = "hsapiens", returntype = "SYMBOL")
```

### Response
#### Success Response
A character vector of mapped gene/protein identifiers in the specified `returntype`.

#### Response Example
```R
# Example for mapping Entrez IDs to Symbols
# [1] "ACSS2" "GCK"   "PGK1"
```
```

--------------------------------

### Run Multi-Omics Enrichment Analysis

Source: https://context7.com/yigbt/multigsea/llms.txt

Performs Gene Set Enrichment Analysis (GSEA) across multiple omics layers using the prepared omics data and downloaded pathways.

```r
# ====================
# 4. Run multi-omics enrichment
# ====================
enrichment_scores <- multiGSEA(pathways, omics_data)
```

--------------------------------

### getMultiOmicsFeatures

Source: https://context7.com/yigbt/multigsea/llms.txt

Downloads pathway definitions and extracts features for specified omics layers.

```APIDOC
## getMultiOmicsFeatures

### Description
Downloads pathway definitions from specified databases and extracts features for each omics layer, mapping them to the required ID format.

### Parameters
#### Arguments
- **dbs** (vector) - Required - Character vector of databases (e.g., c("kegg")).
- **layer** (vector) - Required - Character vector of omics layers.
- **organism** (string) - Required - The organism identifier (e.g., "hsapiens").

### Request Example
```r
pathways <- getMultiOmicsFeatures(dbs = c("kegg"), layer = c("transcriptome", "proteome"), organism = "hsapiens")
```
```

--------------------------------

### initOmicsDataStructure

Source: https://context7.com/yigbt/multigsea/llms.txt

Creates a nested list structure required for storing ranked omics features across specified layers.

```APIDOC
## initOmicsDataStructure

### Description
Creates an empty nested list data structure for storing ranked omics features. Each sublist represents one omics layer (transcriptome, proteome, metabolome).

### Parameters
#### Arguments
- **layer** (vector) - Required - A character vector specifying the omics layers to include (e.g., c("transcriptome", "proteome", "metabolome")).

### Request Example
```r
omics_data <- initOmicsDataStructure(layer = c("transcriptome", "proteome", "metabolome"))
```
```

--------------------------------

### Query multi-omics features

Source: https://context7.com/yigbt/multigsea/llms.txt

Retrieve pathway features across multiple omics layers and organisms. Use the returnType arguments to specify the desired identifier format for each layer.

```r
pathways <- getMultiOmicsFeatures(
    dbs = c("kegg", "reactome"),
    layer = c("transcriptome", "proteome", "metabolome"),
    returnTranscriptome = "SYMBOL",
    returnProteome = "SYMBOL",
    returnMetabolome = "HMDB",
    organism = "hsapiens",
    useLocal = FALSE  # Force re-download, not using cache
)
```

```r
pathways_mouse <- getMultiOmicsFeatures(
    dbs = c("kegg", "reactome"),
    layer = c("transcriptome", "metabolome"),
    returnTranscriptome = "ENSEMBL",
    returnMetabolome = "KEGG",
    organism = "mmusculus"
)
```

```r
pathways_rat <- getMultiOmicsFeatures(
    dbs = c("reactome"),
    layer = c("proteome"),
    organism = "rnorvegicus",
    returnProteome = "ENTREZID"
)
```

--------------------------------

### Extract pathway features with getFeatures

Source: https://context7.com/yigbt/multigsea/llms.txt

Extract protein or metabolite nodes from a specific pathway object. Requires a graphite pathway object as input.

```r
library(multiGSEA)
library(graphite)

# Get a single pathway from KEGG
pathway <- graphite::pathways("hsapiens", "kegg")[[1]]

# Extract protein features with default SYMBOL format
protein_features <- getFeatures(pathway, which = "proteins", org = "hsapiens")
head(protein_features)

# Extract protein features as Uniprot IDs
protein_uniprot <- getFeatures(
    pathway,
    which = "proteins",
    org = "hsapiens",
    returntype = "UNIPROT"
)

# Extract metabolite features
metabolite_features <- getFeatures(
    pathway,
    which = "metabolites",
    org = "hsapiens",
    returntype = "HMDB"
)
head(metabolite_features)

# Mouse pathway with Ensembl IDs
mouse_pathway <- graphite::pathways("mmusculus", "kegg")[[1]]
mouse_features <- getFeatures(
    mouse_pathway,
    which = "proteins",
    org = "mmusculus",
    returntype = "ENSEMBL"
)
```

--------------------------------

### Retrieve and Format HALLMARK Gene Sets

Source: https://github.com/yigbt/multigsea/blob/devel/vignettes/multiGSEA.rmd

Retrieves HALLMARK gene sets for Rattus norvegicus from MSigDB, selects relevant columns, filters out NA values, and restructures the data into a list format suitable for transcriptomics input. Ensure feature sets across multiple omics layers are in the same order and have identical names.

```r
library(msigdbr)
library(dplyr)

hallmark <- msigdbr(species = "Rattus norvegicus", category = "H") %>%
  dplyr::select(gs_name, ensembl_gene) %>%
  dplyr::filter(!is.na(ensembl_gene)) %>%
  unstack(ensembl_gene ~ gs_name)

pathways <- list("transcriptome" = hallmark)
```

--------------------------------

### getFeatures

Source: https://context7.com/yigbt/multigsea/llms.txt

Extracts features (nodes) from a single pathway definition, supporting both protein/gene and metabolite features with various ID mappings.

```APIDOC
## getFeatures

### Description
Extracts features (nodes) from a single pathway definition. Can extract either protein/gene features or metabolite features and map them to desired ID formats.

### Method
`getFeatures`

### Parameters
#### Arguments
- **pathway** (graphite pathway object) - Required - The pathway object from which to extract features.
- **which** (character) - Required - Specifies the type of features to extract: "proteins" or "metabolites".
- **org** (character) - Required - Organism identifier (e.g., "hsapiens", "mmusculus").
- **returntype** (character) - Optional - The desired ID format for the returned features (e.g., "SYMBOL", "UNIPROT", "HMDB"). Defaults to organism-specific defaults.

### Request Example
```R
library(graphite)
pathway <- graphite::pathways("hsapiens", "kegg")[[1]]
protein_features <- getFeatures(pathway, which = "proteins", org = "hsapiens", returntype = "UNIPROT")
```

### Response
#### Success Response
A character vector of features (e.g., gene symbols, Uniprot IDs, HMDB IDs) corresponding to the specified pathway and type.

#### Response Example
```R
# Example for protein features as Uniprot IDs
# [1] "P00533" "P00532" "P04626" ...
```
```

--------------------------------

### Calculate pathway enrichment

Source: https://github.com/yigbt/multigsea/blob/devel/vignettes/multiGSEA.rmd

Calculates enrichment scores for all omics layers simultaneously.

```R
# use the multiGSEA function to calculate the enrichment scores
# for all omics layer at once.
enrichment_scores <- multiGSEA(pathways, omics_data)
```

--------------------------------

### rename_duplicates

Source: https://context7.com/yigbt/multigsea/llms.txt

A utility function to ensure uniqueness of pathway names by appending enumeration to duplicates.

```APIDOC
## rename_duplicates

Utility function to make duplicate strings in a list unique by appending enumeration.

### Description
This function is useful when pathway names might be repeated across different databases or omics layers. It iterates through a list of names and appends a number (e.g., `_1`, `_2`) to any name that appears more than once, ensuring each name is unique.

### Method
`rename_duplicates(names)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **names** (character vector) - A vector of strings (e.g., pathway names) that may contain duplicates.

### Request Example
```r
# Example with duplicate pathway names
pathway_names <- c("Glycolysis", "TCA Cycle", "Glycolysis", "Apoptosis", "Glycolysis")

unique_names <- rename_duplicates(pathway_names)
print(unique_names)
```

### Response
#### Success Response (200)
- **unique_names** (character vector) - A vector of strings where duplicate names have been enumerated to ensure uniqueness.

#### Response Example
```r
# [1] "Glycolysis_1" "TCA Cycle" "Glycolysis_2" "Apoptosis" "Glycolysis_3"
```
```

--------------------------------

### Rename duplicate pathway names

Source: https://context7.com/yigbt/multigsea/llms.txt

Utility to ensure uniqueness in a list of strings by appending enumeration, useful for handling overlapping pathway names.

```r
library(multiGSEA)

# Example with duplicate pathway names
pathway_names <- c("Glycolysis", "TCA Cycle", "Glycolysis", "Apoptosis", "Glycolysis")

unique_names <- rename_duplicates(pathway_names)
print(unique_names)
```

--------------------------------

### rankFeatures

Source: https://context7.com/yigbt/multigsea/llms.txt

Pre-ranks features based on fold change and significance for GSEA calculations.

```APIDOC
## rankFeatures

### Description
Pre-ranks features based on the direction of fold change and the magnitude of significance using the formula: sign(logFC) * -log10(p-value).

### Parameters
#### Arguments
- **logFC** (numeric) - Required - Vector of log fold change values.
- **pvalues** (numeric) - Required - Vector of p-values corresponding to the logFC values.

### Request Example
```r
ranked <- rankFeatures(logFC, pvalues)
```
```

--------------------------------

### getMultiOmicsFeatures

Source: https://context7.com/yigbt/multigsea/llms.txt

Queries multi-omics features (genes, proteins, metabolites) from specified databases and layers, returning them in desired ID formats.

```APIDOC
## getMultiOmicsFeatures

### Description
Retrieves features from multiple omics layers (transcriptome, proteome, metabolome) across specified databases (e.g., KEGG, Reactome) and returns them in user-defined ID formats.

### Method
`getMultiOmicsFeatures`

### Parameters
#### Arguments
- **dbs** (character vector) - Required - Databases to query (e.g., "kegg", "reactome").
- **layer** (character vector) - Required - Omics layers to query (e.g., "transcriptome", "proteome", "metabolome").
- **returnTranscriptome** (character) - Optional - ID format for transcriptome features (e.g., "SYMBOL", "ENSEMBL").
- **returnProteome** (character) - Optional - ID format for proteome features (e.g., "SYMBOL", "UNIPROT").
- **returnMetabolome** (character) - Optional - ID format for metabolome features (e.g., "HMDB", "KEGG").
- **organism** (character) - Required - Organism identifier (e.g., "hsapiens", "mmusculus").
- **useLocal** (logical) - Optional - Whether to use local cache (default is TRUE).

### Request Example
```R
pathways <- getMultiOmicsFeatures(
    dbs = c("kegg", "reactome"),
    layer = c("transcriptome", "proteome", "metabolome"),
    returnTranscriptome = "SYMBOL",
    returnProteome = "SYMBOL",
    returnMetabolome = "HMDB",
    organism = "hsapiens",
    useLocal = FALSE
)
```

### Response
#### Success Response
A list where each element corresponds to an omics layer, containing pathways with mapped features.

#### Response Example
```R
# Example structure for transcriptome layer
# pathways$transcriptome$`(KEGG) Glycolysis / Gluconeogenesis`
# [1] "ACSS2" "GCK"   "PGK1"  "PGK2"  "HKDC1" ...
```
```

--------------------------------

### Combine p-values across omics layers

Source: https://context7.com/yigbt/multigsea/llms.txt

Aggregates p-values from multiple independent tests using methods like Stouffer's Z-method, Fisher's, or Edgington's.

```r
library(multiGSEA)

# Example with simulated p-values
df <- data.frame(
    trans_pval = c(0.01, 0.05, 0.001, 0.2),
    prot_pval = c(0.03, 0.1, 0.02, 0.15),
    meta_pval = c(0.02, 0.08, 0.005, 0.3)
)

# Stouffer's Z-method (default, recommended)
combined_stouffer <- combinePvalues(df, method = "stouffer")

# Fisher's combined probability test
combined_fisher <- combinePvalues(df, method = "fisher")

# Edgington's method
combined_edgington <- combinePvalues(df, method = "edgington")

# Weighted Stouffer's method (e.g., weight transcriptome more)
combined_weighted <- combinePvalues(df, method = "stouffer", weights = c(2, 1, 1))

# Full workflow with real multiGSEA output
df <- extractPvalues(
    enrichmentScores = enrichment_scores,
    pathwayNames = names(pathways[[1]])
)

# Combine p-values (uses raw p-values by default)
df$combined_pval <- combinePvalues(df, method = "stouffer", col_pattern = "pval")

# Apply multiple testing correction on combined p-values
df$combined_padj <- p.adjust(df$combined_pval, method = "BH")

# Add pathway names and sort by significance
df <- cbind(data.frame(pathway = names(pathways[[1]])), df)
df <- df[order(df$combined_padj), ]

# View top enriched pathways
head(df[, c("pathway", "combined_pval", "combined_padj")], 10)
```

--------------------------------

### Extract p-values from multiGSEA output

Source: https://context7.com/yigbt/multigsea/llms.txt

Reshapes multiGSEA results into a structured data frame containing raw and adjusted p-values for each omics layer.

```r
library(multiGSEA)

# Extract p-values into a structured data frame
df <- extractPvalues(
    enrichmentScores = enrichment_scores,
    pathwayNames = names(pathways[[1]])
)

head(df)
```

--------------------------------

### combinePvalues

Source: https://context7.com/yigbt/multigsea/llms.txt

Aggregates p-values from multiple omics layers into a single significance score using various statistical methods.

```APIDOC
## combinePvalues

Combines p-values from multiple independent tests into a single aggregated p-value.

### Description
This function allows for the aggregation of p-values across different omics layers using methods like Stouffer's Z-method, Fisher's combined probability test, and Edgington's method. It can also handle weighted combinations.

### Method
`combinePvalues(df, method = "stouffer", weights = NULL, col_pattern = "pval")`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **df** (data.frame) - A data frame containing p-values. Typically the output from `extractPvalues`.
- **method** (character, optional) - The method for combining p-values. Options: "stouffer" (default, unbiased), "fisher" (biased toward small p-values), "edgington" (favors large p-values).
- **weights** (numeric vector, optional) - A vector of weights to be used with the "stouffer" method. Must be the same length as the number of omics layers.
- **col_pattern** (character, optional) - A pattern to identify the columns containing p-values to be combined. Defaults to "pval".

### Request Example
```r
# Assuming df is a data frame with p-values from extractPvalues
# df <- extractPvalues(...)

# Combine using default Stouffer's method
combined_stouffer <- combinePvalues(df, method = "stouffer")

# Combine using Fisher's method
combined_fisher <- combinePvalues(df, method = "fisher")

# Combine using weighted Stouffer's method
combined_weighted <- combinePvalues(df, method = "stouffer", weights = c(2, 1, 1)) # Example weights
```

### Response
#### Success Response (200)
- **combined_pvalues** (numeric vector) - A vector of aggregated p-values, one for each pathway.

#### Response Example
```r
# Example output structure
# [1] 0.002341 0.034567 0.000234 0.123456
```
```

--------------------------------

### extractPvalues

Source: https://context7.com/yigbt/multigsea/llms.txt

This function reshapes the output of multiGSEA into a single data frame, making it easier to compare p-values and adjusted p-values across different omics layers for each pathway.

```APIDOC
## extractPvalues

Reshapes the multiGSEA output into a single data frame.

### Description
This function takes the `enrichmentScores` object from `multiGSEA` and reorganizes it so that each row represents a pathway, and columns contain the p-values and adjusted p-values for each omics layer.

### Method
`extractPvalues(enrichmentScores, pathwayNames)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **enrichmentScores** (list) - The output list from the `multiGSEA` function.
- **pathwayNames** (character vector) - A vector of pathway names. Typically obtained from the `pathways` object used in `multiGSEA`.

### Request Example
```r
# Assuming enrichment_scores is the output from multiGSEA
# and pathways is the list of pathways used

df <- extractPvalues(
    enrichmentScores = enrichment_scores,
    pathwayNames = names(pathways[[1]]) # Example: using names from the first database
)
```

### Response
#### Success Response (200)
- **df** (data.frame) - A data frame where rows are pathways and columns are `{layer}_pval` and `{layer}_padj` for each omics layer. `NA` values indicate pathways not found in a specific omics layer.

#### Response Example
```r
# head(df)
#   transcriptome_pval transcriptome_padj proteome_pval proteome_padj metabolome_pval metabolome_padj
# 1           0.001234           0.023456      0.045678      0.123456        0.012345        0.056789
# 2           0.000123           0.004567      0.234567      0.456789        0.002345        0.034567
# 3           0.012345           0.078901      0.123456      0.345678              NA              NA
```
```

--------------------------------

### Aggregate and Filter Enrichment Results

Source: https://context7.com/yigbt/multigsea/llms.txt

Extracts and aggregates p-values from enrichment scores, combining them using Stouffer's method. Filters results to include pathways present across all three omics layers and selects the top 20 pathways by combined adjusted p-value.

```r
# ====================
# 5. Aggregate p-values
# ====================
df <- extractPvalues(
    enrichmentScores = enrichment_scores,
    pathwayNames = names(pathways[[1]])
)

df$combined_pval <- combinePvalues(df, method = "stouffer")
df$combined_padj <- p.adjust(df$combined_pval, method = "BH")
df <- cbind(data.frame(pathway = names(pathways[[1]])), df)

# ====================
# 6. Filter and display results
# ====================
results <- df %>%
    dplyr::arrange(combined_padj) %>%
    dplyr::filter(!is.na(metabolome_padj)) %>%  # Pathways with all three layers
    dplyr::select(pathway, transcriptome_padj, proteome_padj,
                  metabolome_padj, combined_pval, combined_padj) %>%
    dplyr::slice(1:20)

print(results)
```

--------------------------------

### Aggregate p-values

Source: https://github.com/yigbt/multigsea/blob/devel/vignettes/multiGSEA.rmd

Combines p-values from independent tests using the Stouffer's Z-method and adjusts for multiple testing.

```R
df <- extractPvalues(
  enrichmentScores = enrichment_scores,
  pathwayNames = names(pathways[[1]])
)

df$combined_pval <- combinePvalues(df)
df$combined_padj <- p.adjust(df$combined_pval, method = "BH")

df <- cbind(data.frame(pathway = names(pathways[[1]])), df)
```
Tokens:
Raw