### Example: Reading Data from a File

Source: https://www.rdocumentation.org/packages/ggpicrust2/versions/2.5.10/topics/ko2kegg_abundance

This example shows how to use ko2kegg_abundance by providing the file path to a PICRUSt2 export file. Replace 'path/to/your/picrust2/results/pred_metagenome_unzip.tsv' with the actual file path.

```R
# Example 4: From file
input_file <- "path/to/your/picrust2/results/pred_metagenome_unzip.tsv"
kegg_abundance <- ko2kegg_abundance(file = input_file)
```

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

### ko2kegg_abundance Examples

Source: https://www.rdocumentation.org/packages/ggpicrust2/versions/2.5.10/topics/ko2kegg_abundance

Illustrative examples of how to use the ko2kegg_abundance function with different parameters and data sources.

```APIDOC
## Examples
```R
if (FALSE) {
library(ggpicrust2)
library(readr)

# Example 1: Default - filtered for prokaryotic analysis
data(ko_abundance)
kegg_abundance <- ko2kegg_abundance(data = ko_abundance)

# Example 2: Include all pathways (for eukaryotic analysis)
kegg_abundance_all <- ko2kegg_abundance(data = ko_abundance, filter_for_prokaryotes = FALSE)

# Example 3: Using legacy sum method with filtering
kegg_abundance_sum <- ko2kegg_abundance(data = ko_abundance, method = "sum")

# Example 4: From file
input_file <- "path/to/your/picrust2/results/pred_metagenome_unstrat.tsv"
kegg_abundance <- ko2kegg_abundance(file = input_file)
}
```
```

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

### Example Data Preparation and Analysis

Source: https://www.rdocumentation.org/packages/ggpicrust2/versions/2.5.10/topics/compare_gsea_daa

Loads example abundance and metadata, runs GSEA and DAA analyses, and prepares data for comparison. Ensure 'camera' method is used for GSEA as recommended.

```R
if (FALSE) {
# Load example data
data(ko_abundance)
data(metadata)

# Prepare abundance data
abundance_data <- as.data.frame(ko_abundance)
rownames(abundance_data) <- abundance_data[, "#NAME"]
abundance_data <- abundance_data[, -1]

# Run GSEA analysis (using camera method - recommended)
gsea_results <- pathway_gsea(
  abundance = abundance_data,
  metadata = metadata,
  group = "Environment",
  pathway_type = "KEGG",
  method = "camera"
)

# Run DAA analysis
daa_results <- pathway_daa(
  abundance = abundance_data,
  metadata = metadata,
  group = "Environment"
)

# Compare results
comparison <- compare_gsea_daa(
  gsea_results = gsea_results,
  daa_results = daa_results,
  plot_type = "venn"
)
}
```

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

### Example: Using Legacy Sum Method

Source: https://www.rdocumentation.org/packages/ggpicrust2/versions/2.5.10/topics/ko2kegg_abundance

This example demonstrates using the legacy 'sum' method for calculating pathway abundance, which simply sums all KO abundances. Filtering for prokaryotes is still applied by default.

```R
# Example 3: Using legacy sum method with filtering
kegg_abundance_sum <- ko2kegg_abundance(data = ko_abundance, method = "sum")
```

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

### Run ggpicrust2 with example KO abundance data

Source: https://www.rdocumentation.org/packages/ggpicrust2/versions/2.5.10/topics/ggpicrust2

This snippet demonstrates running ggpicrust2 using the built-in KO abundance and metadata example data. It's useful for testing and learning.

```R
data(ko_abundance)
data(metadata)
results_file_input <- ggpicrust2(data = ko_abundance,
                                 metadata = metadata,
                                 group = "Environment",
                                 pathway = "KO",
                                 daa_method = "LinDA",
                                 ko_to_kegg = TRUE,
                                 order = "pathway_class",
                                 p_values_bar = TRUE,
                                 x_lab = "pathway_name")
```

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

### Example: Create and Customize Volcano Plot

Source: https://www.rdocumentation.org/packages/ggpicrust2/versions/2.5.10/topics/pathway_volcano

Demonstrates loading example data, running differential abundance analysis, annotating pathways, and then creating and customizing a volcano plot. This example requires the tibble and ggpicrust2 libraries.

```R
if (FALSE) {
library(ggpicrust2)
library(tibble)

# Load example data
data("ko_abundance")
data("metadata")

# Convert KO to KEGG abundance
kegg_abundance <- ko2kegg_abundance(data = ko_abundance)

# Run differential abundance analysis
daa_results <- pathway_daa(
  abundance = kegg_abundance,
  metadata = metadata,
  group = "Environment",
  daa_method = "LinDA"
)

# Annotate results
daa_annotated <- pathway_annotation(
  pathway = "KO",
  ko_to_kegg = TRUE,
  daa_results_df = daa_results
)

# Create volcano plot
volcano_plot <- pathway_volcano(daa_annotated)
print(volcano_plot)

# Customize the plot
volcano_plot <- pathway_volcano(
  daa_annotated,
  fc_threshold = 0.5,
  p_threshold = 0.01,
  label_top_n = 15,
  colors = c("Down" = "darkblue", "Not Significant" = "lightgrey", "Up" = "darkred")
)
}
```

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

### Example: Default KO to KEGG Abundance Conversion

Source: https://www.rdocumentation.org/packages/ggpicrust2/versions/2.5.10/topics/ko2kegg_abundance

This example demonstrates the default usage of ko2kegg_abundance, filtering for prokaryotic pathways. Ensure the 'ggpicrust2' and 'readr' libraries are loaded.

```R
library(ggpicrust2)
library(readr)

# Example 1: Default - filtered for prokaryotic analysis
data(ko_abundance)
kegg_abundance <- ko2kegg_abundance(data = ko_abundance)
```

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

### Install ggpicrust2 Package

Source: https://www.rdocumentation.org/packages/ggpicrust2/versions/2.5.10

Use this command to install the ggpicrust2 package from CRAN.

```r
install.packages('ggpicrust2')
```

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

### Example: Include All Pathways for Eukaryotic Analysis

Source: https://www.rdocumentation.org/packages/ggpicrust2/versions/2.5.10/topics/ko2kegg_abundance

This example shows how to include all KEGG pathways, including those not typically relevant to prokaryotes, by setting 'filter_for_prokaryotes' to FALSE. This is useful for eukaryotic analyses.

```R
# Example 2: Include all pathways (for eukaryotic analysis)
kegg_abundance_all <- ko2kegg_abundance(data = ko_abundance, filter_for_prokaryotes = FALSE)
```

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

### Example of Comparing Metagenome Results

Source: https://www.rdocumentation.org/packages/ggpicrust2/versions/2.5.10/topics/compare_metagenome_results

This example demonstrates how to use the `compare_metagenome_results` function. It generates synthetic metagenome data, calls the function with specified parameters, and then prints the correlation matrix and displays the heatmap of the results.

```R
# \donttest{
library(dplyr)
library(ComplexHeatmap)
# Generate example data
set.seed(123)
# First metagenome
metagenome1 <- abs(matrix(rnorm(1000), nrow = 100, ncol = 10))
rownames(metagenome1) <- paste0("KO", 1:100)
colnames(metagenome1) <- paste0("sample", 1:10)
# Second metagenome
metagenome2 <- abs(matrix(rnorm(1000), nrow = 100, ncol = 10))
rownames(metagenome2) <- paste0("KO", 1:100)
colnames(metagenome2) <- paste0("sample", 1:10)
# Put the metagenomes into a list
metagenomes <- list(metagenome1, metagenome2)
# Define names
names <- c("metagenome1", "metagenome2")
# Call the function
results <- compare_metagenome_results(metagenomes, names, daa_method = "LinDA")
# Print the correlation matrix
print(results$correlation$cor_matrix)
# Display the heatmap
print(results$heatmap)
# }
```

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

### Prepare and Run GSEA Analysis

Source: https://www.rdocumentation.org/packages/ggpicrust2/versions/2.5.10/topics/visualize_gsea

This snippet demonstrates how to load example abundance and metadata, prepare the abundance data, and run a GSEA analysis using the 'camera' method. Ensure your data is formatted correctly before running.

```R
if (FALSE) {
# Load example data
data(ko_abundance)
data(metadata)

# Prepare abundance data
abundance_data <- as.data.frame(ko_abundance)
rownames(abundance_data) <- abundance_data[, "#NAME"]
abundance_data <- abundance_data[, -1]

# Run GSEA analysis (using camera method - recommended)
gsea_results <- pathway_gsea(
  abundance = abundance_data,
  metadata = metadata,
  group = "Environment",
  pathway_type = "KEGG",
  method = "camera"
)
}
```

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

### Load ggpicrust2 Metadata

Source: https://www.rdocumentation.org/packages/ggpicrust2/versions/2.5.10/topics/metadata

This code loads the demonstration metadata dataset from the ggpicrust2 package. Ensure the package is installed and loaded before running.

```r
metadata
```

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

### Example Data Loading for ggpicrust2

Source: https://www.rdocumentation.org/packages/ggpicrust2/versions/2.5.10/topics/ggpicrust2

Demonstrates how to load abundance data from a TSV file and metadata from a CSV file before using the ggpicrust2 function. Adjust file paths as necessary.

```R
if (FALSE) {
# Load necessary data: abundance data and metadata
abundance_file <- "path/to/your/abundance_file.tsv"
metadata <- read.csv("path/to/your/metadata.csv")

}
```

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

### Create Example Data and Basic PCA Plot

Source: https://www.rdocumentation.org/packages/ggpicrust2/versions/2.5.10/topics/pathway_pca

Generates sample abundance and metadata, then creates a PCA plot with default colors. Ensure column names in abundance data match sample names in metadata.

```R
abundance_data <- matrix(rnorm(30), nrow = 3, ncol = 10)
colnames(abundance_data) <- paste0("Sample", 1:10)
rownames(abundance_data) <- c("PathwayA", "PathwayB", "PathwayC")

metadata <- data.frame(
  sample_name = paste0("Sample", 1:10),
  group = factor(rep(c("Control", "Treatment"), each = 5))
)

pca_plot <- pathway_pca(abundance_data, metadata, "group")
```

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

### Compare DAA Results with Sample Data

Source: https://www.rdocumentation.org/packages/ggpicrust2/versions/2.5.10/topics/compare_daa_results

This example demonstrates how to use compare_daa_results with minimal DAA-like results from three methods (DESeq2, edgeR, Maaslin2). No external dependencies are required. Ensure your input data frames have 'feature', 'group1', 'group2', and 'p_adjust' columns.

```R
deseq2_df <- data.frame(
  feature = c("ko00010", "ko00020", "ko00564"),
  group1 = c("A", "A", "A"),
  group2 = c("B", "B", "B"),
  p_adjust = c(0.01, 0.20, 0.03),
  stringsAsFactors = FALSE
)

edgeR_df <- data.frame(
  feature = c("ko00010", "ko00680", "ko00564"),
  group1 = c("A", "A", "A"),
  group2 = c("B", "B", "B"),
  p_adjust = c(0.02, 0.04, 0.01),
  stringsAsFactors = FALSE
)

maaslin2_df <- data.frame(
  feature = c("ko00010", "ko03030", "ko00564"),
  group1 = c("A", "A", "A"),
  group2 = c("B", "B", "B"),
  p_adjust = c(0.03, 0.02, 0.04),
  stringsAsFactors = FALSE
)

daa_results_list <- list(DESeq2 = deseq2_df, edgeR = edgeR_df, Maaslin2 = maaslin2_df)
comparison_results <- compare_daa_results(
  daa_results_list = daa_results_list,
  method_names = c("DESeq2", "edgeR", "Maaslin2"),
  p_values_threshold = 0.05
)
comparison_results

```

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

### Run Pathway GSEA Analysis

Source: https://www.rdocumentation.org/packages/ggpicrust2/versions/2.5.10/topics/pathway_gsea

Demonstrates loading data, preparing abundance data, and running pathway_gsea with different methods (camera, fry, fgsea). Includes an example of covariate adjustment and visualization.

```R
if (FALSE) {
# Load example data
data(ko_abundance)
data(metadata)

# Prepare abundance data
abundance_data <- as.data.frame(ko_abundance)
rownames(abundance_data) <- abundance_data[, "#NAME"]
abundance_data <- abundance_data[, -1]

# Method 1: Using camera (recommended) - accounts for inter-gene correlations
gsea_results <- pathway_gsea(
  abundance = abundance_data,
  metadata = metadata,
  group = "Environment",
  pathway_type = "KEGG",
  method = "camera"
)

# Method 2: Using camera with covariate adjustment
gsea_results_adj <- pathway_gsea(
  abundance = abundance_data,
  metadata = metadata,
  group = "Disease",
  covariates = c("age", "sex"),
  pathway_type = "KEGG",
  method = "camera"
)

# Method 3: Using fry for fast self-contained testing
gsea_results_fry <- pathway_gsea(
  abundance = abundance_data,
  metadata = metadata,
  group = "Environment",
  pathway_type = "KEGG",
  method = "fry"
)

# Method 4: Using fgsea (preranked, less reliable p-values)
gsea_results_fgsea <- pathway_gsea(
  abundance = abundance_data,
  metadata = metadata,
  group = "Environment",
  pathway_type = "KEGG",
  method = "fgsea"
)

# Visualize results
visualize_gsea(gsea_results, plot_type = "enrichment_plot", n_pathways = 10)
}
```

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

### PCA Plot with Real Data and Custom Colors

Source: https://www.rdocumentation.org/packages/ggpicrust2/versions/2.5.10/topics/pathway_pca

Generates a PCA plot using loaded example pathway abundance and metadata. Ensure the abundance data is correctly formatted with pathways as row names.

```R
# Example with real data
data("metacyc_abundance")  # Load example pathway abundance data
data("metadata")          # Load example metadata

# Prepare abundance data
abundance_data <- as.data.frame(metacyc_abundance)
rownames(abundance_data) <- abundance_data$pathway
abundance_data <- abundance_data[, -which(names(abundance_data) == "pathway")]

# Create PCA plot
pathway_pca(
  abundance_data,
  metadata,
  "Environment",
  colors = c("green", "purple")
)
```

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

### Create Pathway Heatmap with ggpicrust2

Source: https://www.rdocumentation.org/packages/ggpicrust2/versions/2.5.10/topics/pathway_heatmap

This snippet demonstrates the basic usage of the pathway_heatmap function, including setting up example abundance data and metadata, and applying custom colors for facet strips.

```R
# \donttest{
library(ggpicrust2)
library(ggh4x)
library(dplyr)
library(tidyr)
library(tibble)
library(magrittr)

# Create example functional pathway abundance data
kegg_abundance_example <- matrix(rnorm(30), nrow = 3, ncol = 10)
colnames(kegg_abundance_example) <- paste0("Sample", 1:10)
rownames(kegg_abundance_example) <- c("PathwayA", "PathwayB", "PathwayC")

# Create example metadata
metadata_example <- data.frame(
  sample_name = colnames(kegg_abundance_example),
  group = factor(rep(c("Control", "Treatment"), each = 5)),
  batch = factor(rep(c("Batch1", "Batch2"), times = 5))
)

# Custom colors for facet strips
custom_colors <- c("skyblue", "salmon")

# Example 1: Basic heatmap
pathway_heatmap(kegg_abundance_example, metadata_example, "group", colors = custom_colors)

# Example 2: Heatmap with row clustering
pathway_heatmap(
  abundance = kegg_abundance_example,
  metadata = metadata_example,
  group = "group",
  cluster_rows = TRUE,
  clustering_method = "complete",
  clustering_distance = "euclidean",
  dendro_line_size = 0.8
)

```

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

### Get Available Color Themes

Source: https://www.rdocumentation.org/packages/ggpicrust2/versions/2.5.10/topics/get_available_themes

Retrieves a character vector containing the names of all available color themes that can be used with ggpicrust2.

```APIDOC
## get_available_themes()

### Description
Get Available Color Themes

### Usage
```R
get_available_themes()
```

### Arguments
This function does not take any arguments.

### Value
A character vector of available theme names.
```

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

### Smart Color Selection Function

Source: https://www.rdocumentation.org/packages/ggpicrust2/versions/2.5.10/topics/smart_color_selection

Use this function to get suggested color themes and palettes based on your data's characteristics. It takes the number of groups, pathway class availability, data type, and accessibility mode as input.

```r
smart_color_selection(
  n_groups,
  has_pathway_class = FALSE,
  data_type = "abundance",
  accessibility_mode = FALSE
)
```

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

### Detect ggplot2 Scale Object

Source: https://www.rdocumentation.org/packages/ggpicrust2/versions/2.5.10/topics/.is_ggplot_scale

Use this internal function to check if an R object is a ggplot2 scale. No specific setup is required beyond having ggplot2 installed.

```r
.is_ggplot_scale(x)
```

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

### Load and Explore ko_to_go_reference Dataset

Source: https://www.rdocumentation.org/packages/ggpicrust2/versions/2.5.10/topics/ko_to_go_reference

Demonstrates how to load the `ko_to_go_reference` dataset and explore its structure and contents using base R functions.

```r
# Load the dataset
data("ko_to_go_reference")

# Explore the dataset structure
head(ko_to_go_reference)
str(ko_to_go_reference)

# Check the distribution of GO categories
table(ko_to_go_reference$category)
```

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

### Run ggpicrust2 with file path

Source: https://www.rdocumentation.org/packages/ggpicrust2/versions/2.5.10/topics/ggpicrust2

Use this snippet when your abundance data is stored in a file. Ensure metadata and desired parameters are correctly specified.

```R
results_file_input <- ggpicrust2(file = abundance_file,
                                 metadata = metadata,
                                 group = "your_group_column",
                                 pathway = "KO",
                                 daa_method = "LinDA",
                                 ko_to_kegg = "TRUE",
                                 order = "pathway_class",
                                 p_values_bar = TRUE,
                                 x_lab = "pathway_name")
```

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

### Get Unique Pathways from Reference Data

Source: https://www.rdocumentation.org/packages/ggpicrust2/versions/2.5.10/topics/ko_to_kegg_reference

Extracts and counts the number of unique KEGG pathway IDs present in the `ko_to_kegg_reference` dataset.

```r
# Get unique pathways
unique_pathways <- unique(ko_to_kegg_reference$pathway_id)
length(unique_pathways)
```

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

### Get Significance Stars Function

Source: https://www.rdocumentation.org/packages/ggpicrust2/versions/2.5.10/topics/get_significance_stars

Use this function to convert p-values into significance star symbols. Customize thresholds and symbols as needed.

```R
get_significance_stars(
  p_values,
  thresholds = c(0.001, 0.01, 0.05),
  symbols = c("***", "**", "*")
)
```

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

### Get Available Color Themes

Source: https://www.rdocumentation.org/packages/ggpicrust2/versions/2.5.10/topics/get_available_themes

Call this function to retrieve a character vector containing the names of all color themes that can be applied to ggpicrust2 plots.

```r
get_available_themes()
```

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

### Run DAA with limma voom

Source: https://www.rdocumentation.org/packages/ggpicrust2/versions/2.5.10/topics/pathway_daa

Performs differential abundance analysis using the limma voom method. This is an alternative to DESeq2 for the provided example data.

```R
# Using a different method (limma voom instead of DESeq2 for this small example)
limma_results <- pathway_daa(abundance, metadata, "group",
                            daa_method = "limma voom")
```

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

### Get Color Theme Function

Source: https://www.rdocumentation.org/packages/ggpicrust2/versions/2.5.10/topics/get_color_theme

Retrieves a specified color theme and number of colors. Use this function to access predefined color palettes for plots.

```r
get_color_theme(theme_name = "default", n_colors = 8)
```

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

### Safely Extract Elements from an R List

Source: https://www.rdocumentation.org/packages/ggpicrust2/versions/2.5.10/topics/safe_extract

Use safe_extract to get elements from a list. It returns NA if the field or index does not exist, preventing script crashes.

```r
# Create a sample list
my_list <- list(
  a = list(x = 1:3),
  b = list(y = 4:6)
)

# Extract existing element
safe_extract(my_list, "a", 1)

# Extract non-existing element (returns NA)
safe_extract(my_list, "c", 1)

```

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

### Annotate Pathways from PICRUSt2 Output

Source: https://www.rdocumentation.org/packages/ggpicrust2/versions/2.5.10/topics/pathway_annotation

Use this snippet to annotate pathways directly from a PICRUSt2 output file. Specify the file path and the desired pathway type (e.g., 'KO').

```R
if (FALSE) {
# Example 1: Annotate pathways from PICRUSt2 output file
pathway_annotation(file = "path/to/picrust2_output.tsv",
                              pathway = "KO")
}
```

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

### Get Significance Colors in R

Source: https://www.rdocumentation.org/packages/ggpicrust2/versions/2.5.10/topics/get_significance_colors

Use this function to map p-values to colors based on significance levels. Ensure p_values are numeric and thresholds/colors are provided as vectors.

```r
get_significance_colors(
  p_values,
  thresholds = c(0.001, 0.01, 0.05),
  colors = c("#d73027", "#fc8d59", "#fee08b"),
  default_color = "#999999"
)
```

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

### preview_color_theme

Source: https://www.rdocumentation.org/packages/ggpicrust2/versions/2.5.10/topics/preview_color_theme

Creates a visual preview of a color theme. Returns a ggplot object showing the color preview.

```APIDOC
## preview_color_theme

### Description
Creates a visual preview of a color theme.

### Usage
```R
preview_color_theme(theme_name = "default", save_plot = FALSE, filename = NULL)
```

### Value
A ggplot object showing the color preview.

### Arguments
#### theme_name
Character string specifying the theme name.

#### save_plot
Whether to save the preview plot.

#### filename
Filename for saved plot.
```

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

### Load and Inspect ko_reference Dataset

Source: https://www.rdocumentation.org/packages/ggpicrust2/versions/2.5.10/topics/ko_reference

Loads the ko_reference dataset into the R environment and displays the first few rows. It also shows a frequency table of the top-level pathway categories.

```r
data("ko_reference")
head(ko_reference)

# Check pathway hierarchy
table(ko_reference$PathwayL1)
```

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

### get_color_theme

Source: https://www.rdocumentation.org/packages/ggpicrust2/versions/2.5.10/topics/get_color_theme

Retrieves color themes and their associated settings.

```APIDOC
## get_color_theme: Get Color Theme

### Description
Get Color Theme

### Usage
```R
get_color_theme(theme_name = "default", n_colors = 8)
```

### Value
A list containing theme colors and settings

### Arguments
#### theme_name
Character string specifying the theme name

#### n_colors
Integer specifying the number of colors needed
```

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

### Perform GO Pathway GSEA Analysis with ggpicrust2

Source: https://www.rdocumentation.org/packages/ggpicrust2/versions/2.5.10/topics/ko_to_go_reference

Demonstrates how to perform Gene Set Enrichment Analysis (GSEA) for Gene Ontology (GO) terms using the `pathway_gsea` function from the `ggpicrust2` package. Requires `ko_abundance` and `metadata` datasets.

```r
library(ggpicrust2)
library(tibble)

# Load example data
data("ko_abundance")
data("metadata")

# Perform GO pathway GSEA analysis
gsea_results <- pathway_gsea(
  abundance = ko_abundance %>% column_to_rownames("#NAME"),
  metadata = metadata %>% column_to_rownames("sample_name"),
  group = "Environment",
  method = "fgsea",
  pathway_type = "GO",
  go_category = "MF",
  rank_method = "signal2noise"
)

# View results
head(gsea_results)
```

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

### Get KO Members for a Specific GO Term

Source: https://www.rdocumentation.org/packages/ggpicrust2/versions/2.5.10/topics/ko_to_go_reference

Retrieves and displays the KEGG Orthology (KO) identifiers associated with a specific Gene Ontology (GO) term, 'RNA polymerase activity' (GO:0003899).

```r
# Get KO members for a specific GO term (RNA polymerase activity)
rna_pol <- ko_to_go_reference[ko_to_go_reference$go_id == "GO:0003899", ]
if (nrow(rna_pol) > 0) {
  ko_list <- strsplit(rna_pol$ko_members, ";")[[1]]
  cat("KO identifiers for RNA polymerase activity:", paste(ko_list, collapse = ", "))
}
```

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

### Load and Inspect ko_to_kegg_reference Data

Source: https://www.rdocumentation.org/packages/ggpicrust2/versions/2.5.10/topics/ko_to_kegg_reference

Loads the reference data into your R session and displays its structure. This is a common first step when working with the dataset.

```r
# Load the reference data
data(ko_to_kegg_reference)

# View structure
str(ko_to_kegg_reference)
```

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

### View First Few Rows of EC Reference Dataset

Source: https://www.rdocumentation.org/packages/ggpicrust2/versions/2.5.10/topics/ec_reference

Displays the first few rows of the `ec_reference` dataset to show its structure and content. This includes EC numbers and their descriptions.

```r
data("ec_reference")
head(ec_reference)
```

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

### Load metacyc_abundance Dataset

Source: https://www.rdocumentation.org/packages/ggpicrust2/versions/2.5.10/topics/metacyc_abundance

This code snippet loads the metacyc_abundance dataset. This dataset represents MetaCyc pathway abundances for various samples, as generated by PICRUSt2.

```R
metacyc_abundance
```

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

### Run limma-based gene set analysis (camera/fry)

Source: https://www.rdocumentation.org/packages/ggpicrust2/versions/2.5.10/topics/run_limma_gsea

This function implements limma's camera and fry methods for gene set enrichment analysis. It requires abundance data, metadata, a grouping variable, and gene sets. Optional arguments include covariates, contrast specifications, and parameters for method-specific tuning and p-value adjustment.

```R
run_limma_gsea(
  abundance_mat,
  metadata,
  group,
  covariates = NULL,
  contrast = NULL,
  gene_sets,
  method = "camera",
  inter.gene.cor = 0.01,
  min_size = 5,
  max_size = 500,
  p.adjust.method = "BH"
)
```

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

### Run DAA with ALDEx2 (Simplified Data)

Source: https://www.rdocumentation.org/packages/ggpicrust2/versions/2.5.10/topics/pathway_daa

Performs differential abundance analysis using ALDEx2 with simplified data structures. Ensure 'abundance' and 'metadata' are correctly formatted.

```R
# Create example data with more samples
abundance <- data.frame(
  sample1 = c(10, 20, 30),
  sample2 = c(20, 30, 40),
  sample3 = c(30, 40, 50),
  sample4 = c(40, 50, 60),
  sample5 = c(50, 60, 70),
  row.names = c("pathway1", "pathway2", "pathway3")
)

metadata <- data.frame(
  sample = c("sample1", "sample2", "sample3", "sample4", "sample5"),
  group = c("control", "control", "treatment", "treatment", "treatment")
)

# Run differential abundance analysis using ALDEx2
results <- pathway_daa(abundance, metadata, "group")
```

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

### Load ko_abundance Dataset

Source: https://www.rdocumentation.org/packages/ggpicrust2/versions/2.5.10/topics/ko_abundance

This code snippet loads the ko_abundance dataset. This dataset is a data frame containing KO group abundances for various samples, useful for understanding PICRUSt2 output.

```R
ko_abundance
```

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

### Run ggpicrust2 with imported data.frame

Source: https://www.rdocumentation.org/packages/ggpicrust2/versions/2.5.10/topics/ggpicrust2

Use this snippet when your abundance data is already loaded into an R data frame. This method avoids file reading within the function.

```R
abundance_data <- read_delim(abundance_file, delim="\t", col_names=TRUE, trim_ws=TRUE)

results_data_input <- ggpicrust2(data = abundance_data,
                                 metadata = metadata,
                                 group = "your_group_column",
                                 pathway = "KO",
                                 daa_method = "LinDA",
                                 ko_to_kegg = "TRUE",
                                 order = "pathway_class",
                                 p_values_bar = TRUE,
                                 x_lab = "pathway_name")
```

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

### Create Heatmap Visualization

Source: https://www.rdocumentation.org/packages/ggpicrust2/versions/2.5.10/topics/visualize_gsea

Generates a heatmap visualization of GSEA results, requiring abundance data, metadata, and a grouping variable. Adjust 'n_pathways' to control the number of pathways displayed.

```R
# Create heatmap
visualize_gsea(
  annotated_results,
  plot_type = "heatmap",
  n_pathways = 15,
  abundance = abundance_data,
  metadata = metadata,
  group = "Environment"
)
```

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

### Real Data Processing for Heatmap

Source: https://www.rdocumentation.org/packages/ggpicrust2/versions/2.5.10/topics/pathway_heatmap

Prepares real 'MetaCyc' abundance data and metadata for heatmap visualization by performing differential abundance analysis and annotation. Filters features with adjusted p-values less than 0.05.

```r
data("metacyc_abundance")
data("metadata")
metacyc_daa_results_df <- pathway_daa(
  abundance = metacyc_abundance %>%
    column_to_rownames("pathway"),
  metadata = metadata,
  group = "Environment",
  daa_method = "LinDA"
)
annotated_metacyc_daa_results_df <- pathway_annotation(
  pathway = "MetaCyc",
  daa_results_df = metacyc_daa_results_df,
  ko_to_kegg = FALSE
)
feature_with_p_0.05 <- metacyc_daa_results_df %>%
  filter(p_adjust < 0.05)
```

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

### Analyze MetaCyc pathways with ggpicrust2

Source: https://www.rdocumentation.org/packages/ggpicrust2/versions/2.5.10/topics/ggpicrust2

This snippet shows how to analyze MetaCyc pathways using ggpicrust2. Note that 'ko_to_kegg' is set to FALSE for MetaCyc.

```R
data(metacyc_abundance)
results_file_input <- ggpicrust2(data = metacyc_abundance,
                                 metadata = metadata,
                                 group = "Environment",
                                 pathway = "MetaCyc",
                                 daa_method = "LinDA",
                                 ko_to_kegg = FALSE,
                                 order = "group",
                                 p_values_bar = TRUE,
                                 x_lab = "description")
```

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

### Create Pathway Class Annotation Theme

Source: https://www.rdocumentation.org/packages/ggpicrust2/versions/2.5.10/topics/create_pathway_class_theme

Use this function to define the styling parameters for pathway class annotations. It allows customization of text size, color, face, family, angle, justification, and background color/alpha, as well as annotation position.

```R
create_pathway_class_theme(
  text_size = "auto",
  text_color = "black",
  text_face = "bold",
  text_family = "sans",
  text_angle = 0,
  text_hjust = 0.5,
  text_vjust = 0.5,
  bg_color = NULL,
  bg_alpha = 0.2,
  position = "left"
)
```

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

### Prepare Gene Sets - ggpicrust2

Source: https://www.rdocumentation.org/packages/ggpicrust2/versions/2.5.10/topics/prepare_gene_sets

Use this function to prepare gene sets for GSEA. Specify the pathway type, organism, and GO category as needed. The function returns a list of pathway gene sets.

```r
prepare_gene_sets(pathway_type = "KEGG", organism = "ko", go_category = "all")
```

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

### Real Data Heatmap with Multiple Grouping Variables

Source: https://www.rdocumentation.org/packages/ggpicrust2/versions/2.5.10/topics/pathway_heatmap

Generates a heatmap using 'MetaCyc' data with primary and secondary grouping variables. Row clustering is enabled, and specific distance/method are applied.

```r
pathway_heatmap(
  abundance = metacyc_abundance %>%
    right_join(
      annotated_metacyc_daa_results_df %>%
      select(all_of(c("feature","description"))),
      by = c("pathway" = "feature")
    ) %>%
    filter(pathway %in% feature_with_p_0.05$feature) %>%
    select(-"pathway") %>%
    filter(!is.na(description)) %>%
    distinct(description, .keep_all = TRUE) %>%
    column_to_rownames("description"),
  metadata = metadata,
  group = "Environment",              # Primary: Pro-survival vs others
  secondary_groups = "Group",         # Secondary: Broad Institute vs Jackson Labs
  cluster_rows = TRUE,
  clustering_method = "ward.D2",
  clustering_distance = "correlation"
)
```

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

### Import MicrobiomeAnalyst DAA Results

Source: https://www.rdocumentation.org/packages/ggpicrust2/versions/2.5.10/topics/import_MicrobiomeAnalyst_daa_results

Use this function to import Differential Abundance Analysis (DAA) results from MicrobiomeAnalyst. Ensure the file path points to a valid CSV file containing the DAA results. Default method and group levels are 'MicrobiomeAnalyst' and c('control', 'treatment') respectively.

```R
if (FALSE) {
# Assuming you have a CSV file named "DAA_results.csv" in your current directory
daa_results <- import_MicrobiomeAnalyst_daa_results(file_path = "DAA_results.csv")
}
```

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

### ko2kegg_abundance Function Signature

Source: https://www.rdocumentation.org/packages/ggpicrust2/versions/2.5.10/topics/ko2kegg_abundance

This function takes a file containing KO (KEGG Orthology) abundance data in picrust2 export format and converts it to KEGG pathway abundance data. The input file should be in .tsv, .txt, or .csv format.

```APIDOC
## ko2kegg_abundance

### Description
This function takes a file containing KO (KEGG Orthology) abundance data in picrust2 export format and converts it to KEGG pathway abundance data. The input file should be in .tsv, .txt, or .csv format.

### Usage
```R
ko2kegg_abundance(
  file = NULL,
  data = NULL,
  method = c("abundance", "sum"),
  filter_for_prokaryotes = TRUE
)
```

### Arguments
* **file** (character string): Path to the input file containing KO abundance data. The file should have KO identifiers in the first column and sample identifiers in the first row. The remaining cells should contain abundance values.
* **data** (data.frame, optional): An alternative to `file`, providing KO abundance data directly as a data frame.
* **method** (character): Method for calculating pathway abundance. Options are "abundance" (default, PICRUSt2-style mean of upper-half sorted KO abundances) or "sum" (legacy simple summation).
* **filter_for_prokaryotes** (logical): If TRUE (default), filters out KEGG pathways not relevant to prokaryotic analysis. Set to FALSE to include all KEGG pathways.
```

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

### create_pathway_class_theme

Source: https://www.rdocumentation.org/packages/ggpicrust2/versions/2.5.10/topics/create_pathway_class_theme

Creates a theme for pathway class annotations, allowing customization of text and background styles, as well as position.

```APIDOC
## create_pathway_class_theme: Create Pathway Class Annotation Theme

### Description
Create Pathway Class Annotation Theme

### Usage
```R
create_pathway_class_theme(
  text_size = "auto",
  text_color = "black",
  text_face = "bold",
  text_family = "sans",
  text_angle = 0,
  text_hjust = 0.5,
  text_vjust = 0.5,
  bg_color = NULL,
  bg_alpha = 0.2,
  position = "left"
)
```

### Arguments
- **text_size** (character or numeric) - Text size. Defaults to "auto".
- **text_color** (character) - Text color. Defaults to "black".
- **text_face** (character) - Text face. Options: "plain", "bold", "italic". Defaults to "bold".
- **text_family** (character) - Text family. Defaults to "sans".
- **text_angle** (numeric) - Text angle in degrees. Defaults to 0.
- **text_hjust** (numeric) - Horizontal justification (0-1). Defaults to 0.5.
- **text_vjust** (numeric) - Vertical justification (0-1). Defaults to 0.5.
- **bg_color** (character or NULL) - Background color. Defaults to NULL.
- **bg_alpha** (numeric) - Background alpha. Defaults to 0.2.
- **position** (character) - Annotation position. Options: "left", "right", "none". Defaults to "left".

### Value
List of annotation styling parameters.
```

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

### calculate_smart_text_size

Source: https://www.rdocumentation.org/packages/ggpicrust2/versions/2.5.10/topics/calculate_smart_text_size

Calculates a smart text size based on the number of items and configurable size parameters.

```APIDOC
## calculate_smart_text_size

### Description
Smart Text Size Calculator

### Usage
```R
calculate_smart_text_size(n_items, base_size = 10, min_size = 8, max_size = 14)
```

### Arguments
- **n_items** (numeric) - Number of items to display
- **base_size** (numeric) - Optional. Base text size. Defaults to 10.
- **min_size** (numeric) - Optional. Minimum text size. Defaults to 8.
- **max_size** (numeric) - Optional. Maximum text size. Defaults to 14.

### Value
Calculated text size
```

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

### Load EC Reference Dataset

Source: https://www.rdocumentation.org/packages/ggpicrust2/versions/2.5.10/topics/ec_reference

Loads the `ec_reference` dataset into the R environment. This dataset contains EC numbers and their corresponding descriptions.

```r
data("ec_reference")
```

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

### Run DAA with DESeq2

Source: https://www.rdocumentation.org/packages/ggpicrust2/versions/2.5.10/topics/pathway_daa

Performs differential abundance analysis using the DESeq2 method. Requires abundance data, metadata, and a grouping column.

```R
# Using a different method (DESeq2)
deseq_results <- pathway_daa(
  abundance = abundance_data,
  metadata = metadata,
  group = "Environment",
  daa_method = "DESeq2"
)
```

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

### create_gradient_colors

Source: https://www.rdocumentation.org/packages/ggpicrust2/versions/2.5.10/topics/create_gradient_colors

Creates gradient colors for fold change visualization.

```APIDOC
## create_gradient_colors

### Description
Creates gradient colors for fold change visualization.

### Usage
```R
create_gradient_colors(theme_name = "default", n_colors = 11, diverging = TRUE)
```

### Arguments
* **theme_name** (string) - Specifies the theme.
* **n_colors** (number) - Number of colors in the gradient.
* **diverging** (boolean) - Whether to create a diverging gradient (for fold changes).

### Value
A vector of colors.
```

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

### run_limma_gsea

Source: https://www.rdocumentation.org/packages/ggpicrust2/versions/2.5.10/topics/run_limma_gsea

This internal function implements limma's camera and fry methods for gene set enrichment analysis with support for covariates.

```APIDOC
## Function: run_limma_gsea

### Description
This internal function implements limma's camera and fry methods for gene set enrichment analysis with support for covariates.

### Usage
```R
run_limma_gsea(
  abundance_mat,
  metadata,
  group,
  covariates = NULL,
  contrast = NULL,
  gene_sets,
  method = "camera",
  inter.gene.cor = 0.01,
  min_size = 5,
  max_size = 500,
  p.adjust.method = "BH"
)
```

### Arguments
* **abundance_mat**: A matrix of abundance data with features as rows and samples as columns.
* **metadata**: A data frame containing sample metadata.
* **group**: A character string specifying the grouping variable column name.
* **covariates**: A character vector of covariate column names (optional).
* **contrast**: Contrast specification for multi-group comparisons (optional).
* **gene_sets**: A named list of gene sets (pathway -> gene IDs).
* **method**: Either "camera" or "fry" (default: "camera").
* **inter.gene.cor**: Inter-gene correlation for camera (default: 0.01).
* **min_size**: Minimum gene set size (default: 5).
* **max_size**: Maximum gene set size (default: 500).
* **p.adjust.method**: P-value adjustment method (default: "BH").

### Value
A data frame containing gene set analysis results.
```

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

### Load and Inspect MetaCyc Reference Data

Source: https://www.rdocumentation.org/packages/ggpicrust2/versions/2.5.10/topics/metacyc_reference

Loads the metacyc_reference dataset into the R environment and displays the first few rows. This is useful for understanding the structure and content of the reference data.

```r
data("metacyc_reference")
head(metacyc_reference)
```

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

### Run DAA with ALDEx2

Source: https://www.rdocumentation.org/packages/ggpicrust2/versions/2.5.10/topics/pathway_daa

Performs differential abundance analysis using the ALDEx2 method. Requires abundance data, metadata, and a grouping column.

```R
# Load example data
data(ko_abundance)
data(metadata)

# Prepare abundance data
abundance_data <- as.data.frame(ko_abundance)
rownames(abundance_data) <- abundance_data[, "#NAME"]
abundance_data <- abundance_data[, -1]

# Run differential abundance analysis using ALDEx2
results <- pathway_daa(
  abundance = abundance_data,
  metadata = metadata,
  group = "Environment"
)
```