### Install and Load ggpicrust2

Source: https://github.com/cafferychen777/ggpicrust2/blob/main/README.md

Installs the ggpicrust2 package from GitHub and loads the library. Assumes the KO abundance table is in 'ko_abundance.tsv'.

```r
# Sample usage of the ko2kegg_abundance function
devtools::install_github('cafferychen777/ggpicrust2')

library(ggpicrust2)

# Assume that the KO abundance table is stored in a file named "ko_abundance.tsv"
ko_abundance_file <- "ko_abundance.tsv"

# Convert KO abundance to KEGG pathway abundance
kegg_abundance <- ko2kegg_abundance(file = ko_abundance_file)

# Alternatively, if the KO abundance data is already loaded as a data frame named "ko_abundance"
data("ko_abundance")
kegg_abundance <- ko2kegg_abundance(data = ko_abundance)

# The resulting kegg_abundance data frame can now be used for further analysis and visualization.
```

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

### Install and Load ggpicrust2 Library

Source: https://github.com/cafferychen777/ggpicrust2/wiki/_Footer

Provides commands for installing the ggpicrust2 package from GitHub and loading it into the R session. Ensure version 2.1.0 or later is installed.

```r
# Installation
# devtools::install_github("cafferychen777/ggpicrust2")

# Load library
library(ggpicrust2)
```

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

### Using Example Data with ggpicrust2

Source: https://github.com/cafferychen777/ggpicrust2/blob/main/README.md

This snippet shows how to use the example KO abundance and metadata included within the ggpicrust2 package for analysis. It's helpful for testing and understanding the function's behavior.

```r
# Use the example data in ggpicrust2 package
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")
```

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

### Install ggpicrust2 Package from CRAN

Source: https://github.com/cafferychen777/ggpicrust2/wiki/_Footer

Install the ggpicrust2 package from CRAN, the recommended installation method for most users.

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

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

### Create a Minimal Reproducible Example for Reporting Issues

Source: https://github.com/cafferychen777/ggpicrust2/blob/main/_autodocs/08-errors-and-troubleshooting.md

Generate a minimal reproducible example using built-in data to help diagnose and report errors effectively on GitHub.

```r
# Use built-in example data
data(ko_abundance, metadata)

# Minimal code to reproduce error
results <- ggpicrust2(
  data = ko_abundance,
  metadata = metadata,
  group = "Environment",
  pathway = "KO",
  daa_method = "ALDEx2"
)
```

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

### Install ggpicrust2 Package

Source: https://github.com/cafferychen777/ggpicrust2/wiki/_Footer

Installs the ggpicrust2 package using BiocManager. Ensure BiocManager is installed first if it's not already present.

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

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

### Install ggpicrust2 Package from GitHub

Source: https://github.com/cafferychen777/ggpicrust2/wiki/_Footer

Install the development version of the ggpicrust2 package directly from GitHub using the devtools package.

```r
devtools::install_github("cafferychen777/ggpicrust2")
```

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

### Install Devtools Package

Source: https://github.com/cafferychen777/ggpicrust2/wiki/_Footer

Install the devtools package, which is required for installing R packages directly from GitHub.

```r
install.packages("devtools")
```

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

### Check and Install Package Dependencies

Source: https://github.com/cafferychen777/ggpicrust2/blob/main/_autodocs/08-errors-and-troubleshooting.md

Verify that all required and optional packages for ggpicrust2 and its DAA methods are installed. Installs missing required packages automatically.

```r
# Verify all required packages
required_pkgs <- c("dplyr", "ggplot2", "tidyr", "patchwork", "ggh4x")

for (pkg in required_pkgs) {
  if (!require(pkg, quietly = TRUE)) {
    cat("Missing package:", pkg, "\n")
    install.packages(pkg)
  }
}

# For DAA methods
daa_packages <- c("ALDEx2", "DESeq2", "edgeR", "limma", "LinDA")

for (pkg in daa_packages) {
  if (!require(pkg, quietly = TRUE)) {
    cat("Optional package missing:", pkg, "\n")
  }
}
```

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

### Install BiocManager Package

Source: https://github.com/cafferychen777/ggpicrust2/wiki/_Footer

Install the BiocManager package, a prerequisite for installing other Bioconductor packages.

```r
install.packages("BiocManager")
```

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

### Install ggpicrust2 Package

Source: https://github.com/cafferychen777/ggpicrust2/wiki/_Footer

Install the ggpicrust2 package from CRAN or the latest version from GitHub using devtools.

```r
# Install ggpicrust2 from CRAN
install.packages("ggpicrust2")

# Or install the latest version from GitHub
# install.packages("devtools")
devtools::install_github("cafferychen777/ggpicrust2")
```

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

### preview_color_theme()

Source: https://github.com/cafferychen777/ggpicrust2/blob/main/_autodocs/03-color-theming.md

Previews a specified color theme, displaying visual examples of its application. Optionally, the preview plot can be saved to a file.

```APIDOC
## preview_color_theme()

### Description
Previews a color theme with visual examples.

### Signature
```r
preview_color_theme(
  theme_name = "default",
  save_plot = FALSE,
  filename = NULL
)
```

### Parameters
#### Query Parameters
- **theme_name** (character) - Optional - Default: "default" - Theme to preview
- **save_plot** (logical) - Optional - Default: FALSE - Save plot to file
- **filename** (character) - Optional - Default: NULL - File path for saved plot

### Return Value
ggplot2 preview plot displaying theme colors with sample applications.

### Usage Example
```r
# Preview a theme
preview_color_theme("nature")

# Preview and save
preview_color_theme(
  theme_name = "lancet",
  save_plot = TRUE,
  filename = "lancet_theme_preview.pdf"
)
```
```

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

### Debugging Workflow Setup

Source: https://github.com/cafferychen777/ggpicrust2/blob/main/README.md

This snippet provides the necessary library loading for a debugging workflow when encountering issues with the main ggpicrust2 function. It includes common R packages used in the analysis pipeline.

```r
library(readr)
library(ggpicrust2)
library(tibble)
library(tidyverse)
library(ggprism)
library(patchwork)

# If you want to analyze KEGG pathway abundance instead of KO within the pathway, turn ko_to_kegg to TRUE.
# KEGG pathways typically have more explainable descriptions.

```

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

### Install Optional Bioconductor Packages

Source: https://github.com/cafferychen777/ggpicrust2/blob/main/README.md

Installs essential Bioconductor packages for advanced workflows in ggpicrust2. Ensure BiocManager is installed first.

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

pkgs <- c("phyloseq", "ALDEx2", "SummarizedExperiment", "Biobase", "devtools",
          "ComplexHeatmap", "BiocGenerics", "BiocManager", "metagenomeSeq",
          "Maaslin2", "edgeR", "lefser", "limma", "KEGGREST", "DESeq2")

for (pkg in pkgs) {
  if (!requireNamespace(pkg, quietly = TRUE))
    BiocManager::install(pkg)
}
```

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

### Access Built-in Reference Data in R

Source: https://github.com/cafferychen777/ggpicrust2/blob/main/_autodocs/06-configuration-reference.md

Demonstrates how to load example datasets provided with the ggpicrust2 package using the data() function. These include abundance data and mapping references.

```r
data(ko_abundance)           # Example KO abundance
data(metadata)               # Example metadata
data(ec_abundance)           # Example EC abundance
data(metacyc_abundance)      # Example MetaCyc abundance
data(ko_to_kegg_reference)   # KO to KEGG mapping reference
```

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

### Install Required Packages for DAA Methods

Source: https://github.com/cafferychen777/ggpicrust2/blob/main/_autodocs/08-errors-and-troubleshooting.md

Ensure all necessary R packages for the chosen differential abundance analysis (DAA) method are installed. Use BiocManager::install() for Bioconductor packages and install.packages() for CRAN packages.

```r
# Install missing package
# For Bioconductor packages:
if (!require("BiocManager", quietly = TRUE))
  install.packages("BiocManager")

BiocManager::install("DESeq2")      # For DESeq2
BiocManager::install("edgeR")       # For edgeR
BiocManager::install("limma")       # For limma voom
BiocManager::install("metagenomeSeq")

# For CRAN packages:
install.packages("ALDEx2")          # Wrong - it's Bioconductor
install.packages("LinDA")
install.packages("Maaslin2")        # May need Bioconductor

# Verify installation
library(DESeq2)  # Should load without error
```

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

### Applying Color Themes to ggpicrust2 Plots

Source: https://github.com/cafferychen777/ggpicrust2/blob/main/_autodocs/03-color-theming.md

Demonstrates how to use the `color_theme` parameter with `pathway_errorbar`, `pathway_heatmap`, and `pathway_pca` functions. The `pathway_pca` example shows how to retrieve a theme using `get_color_theme` for custom color application.

```r
pathway_errorbar(
  abundance = kegg_abundance,
  daa_results_df = daa_results,
  Group = metadata$Environment,
  color_theme = "nature"
)

pathway_heatmap(
  abundance = kegg_abundance,
  metadata = metadata,
  group = "Environment",
  color_theme = "science"
)

pathway_pca(
  abundance = kegg_abundance,
  metadata = metadata,
  group = "Environment",
  colors = get_color_theme("lancet", n_colors = 3)
)
```

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

### Metadata Format Example

Source: https://github.com/cafferychen777/ggpicrust2/blob/main/_autodocs/04-types-and-data-structures.md

Sample metadata should be a data frame or tibble with sample identifiers matching abundance data columns. It must include a user-specified grouping variable for analyses.

```plaintext
sample_name  Environment  Treatment  Age
Sample1      Soil         Control    Day1
Sample2      Water        Control    Day2
Sample3      Soil         Treatment  Day1
Sample4      Water        Treatment  Day2
```

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

### Get Help for ggpicrust2 Package in R

Source: https://github.com/cafferychen777/ggpicrust2/blob/main/_autodocs/00-README.md

Access the main help page for the ggpicrust2 package using the '?' operator. This provides an entry point to the package's documentation.

```r
# Package help
?ggpicrust2
```

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

### Browse Vignettes for ggpicrust2 Package in R

Source: https://github.com/cafferychen777/ggpicrust2/blob/main/_autodocs/00-README.md

Open the vignettes for the ggpicrust2 package in your web browser. Vignettes provide detailed examples and tutorials on how to use the package.

```r
# Vignettes
browseVignettes("ggpicrust2")
```

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

### Initial pathway_errorbar usage

Source: https://github.com/cafferychen777/ggpicrust2/blob/main/README.md

Example of calling the pathway_errorbar function with common parameters. Ensure necessary data frames and metadata are correctly formatted.

```r
pathway_errorbar(abundance = abundance,
                 daa_results_df = daa_results_df,
                 Group = metadata$Environment,
                 ko_to_kegg = TRUE,
                 p_values_threshold = 0.05,
                 order = "pathway_class",
                 select = NULL,
                 p_value_bar = TRUE,
                 colors = NULL,
                 x_lab = "pathway_name")
```

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

### DESeq2 Method Usage

Source: https://github.com/cafferychen777/ggpicrust2/blob/main/_autodocs/05-daa-methods.md

Example of how to call the pathway_daa function using the DESeq2 method, specifying a reference group.

```r
daa_results <- pathway_daa(
  abundance = ko_abundance,
  metadata = metadata,
  group = "Environment",
  daa_method = "DESeq2",
  reference = "Control"
)
```

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

### KO to KEGG Reference Data Structure

Source: https://github.com/cafferychen777/ggpicrust2/blob/main/_autodocs/04-types-and-data-structures.md

This is an example of the internal reference mapping from KO IDs to KEGG pathways. It includes pathway information, KO details, and hierarchical classifications.

```text
  pathway_id pathway_number pathway_name ko_id ko_description ec_number level1 level2 level3
1     ko00010             10   Glycolysis K00001 hexokinase [EC:2.7.1.1] 2.7.1.1 Metabolism Carbohydrate metabolism Glycolysis
2     ko00010             10   Glycolysis K00002 glucose-6-phosphate isomerase [EC:5.3.1.9] 5.3.1.9 Metabolism Carbohydrate metabolism Glycolysis
```

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

### Get Help for ggpicrust2 Functions in R

Source: https://github.com/cafferychen777/ggpicrust2/blob/main/_autodocs/00-README.md

Use the '?' operator in R to access help pages for specific functions like 'pathway_daa' or 'pathway_errorbar'. This is useful for understanding function arguments and expected outputs.

```r
# Function help
?pathway_daa
?pathway_errorbar
```

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

### Abundance Data Format Example

Source: https://github.com/cafferychen777/ggpicrust2/blob/main/_autodocs/04-types-and-data-structures.md

Abundance data should be provided as a data frame or matrix with features as rows and samples as columns. Row names are feature identifiers, and column names are sample identifiers. Values represent abundance counts or normalized values.

```plaintext
       Sample1  Sample2  Sample3  Sample4
Feature1   100      150      200      180
Feature2   250      300      320      310
Feature3    50       75       85       90
Feature4   400      350      420      380
```

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

### DAA with Complex Designs (Maaslin2/LinDA)

Source: https://github.com/cafferychen777/ggpicrust2/blob/main/_autodocs/05-daa-methods.md

Configure pathway_daa for complex experimental designs involving covariates. This example shows how to use Maaslin2 or LinDA with a custom reference group and includes abundance statistics.

```r
# Using Maaslin2 or LinDA with custom reference
daa_results <- pathway_daa(
  abundance = abundance,
  metadata = metadata,
  group = "group_var",
  daa_method = "Maaslin2",  # or "LinDA"
  reference = "Control_group",
  include_abundance_stats = TRUE,
  p_adjust_method = "BH"
)
```

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

### Perform and Visualize Differential Abundance Analysis

Source: https://github.com/cafferychen777/ggpicrust2/wiki/_Footer

Demonstrates a basic workflow for performing differential abundance analysis (DAA) using example data and visualizing the results. Ensure your input data and metadata are correctly formatted.

```r
# Load necessary libraries
library(ggpicrust2)

# Example data (replace with your actual data)
data("example")
metadata <- example$metadata
pathway_abundance <- example$KO_pathway

# Perform DAA
daa_result <- perform_daa(
  input.data = pathway_abundance,
  sample.metadata = metadata,
  group = "Group"
)

# Visualize DAA results
visualize_daa(daa_result)
```

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

### List All Functions in ggpicrust2 Package in R

Source: https://github.com/cafferychen777/ggpicrust2/blob/main/_autodocs/00-README.md

Use the 'help()' function with the 'package' argument to list all available functions within the ggpicrust2 package. This is helpful for exploring the package's capabilities.

```r
# List all functions
help(package = "ggpicrust2")
```

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

### Access Help Pages for GSEA Functions

Source: https://github.com/cafferychen777/ggpicrust2/wiki/_Footer

Demonstrates how to access the help documentation for the GSEA-related functions within the ggpicrust2 package.

```r
# Help pages
?pathway_gsea
?visualize_gsea
?compare_gsea_daa
?gsea_pathway_annotation
```

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

### Get ggpicrust2 Citation

Source: https://github.com/cafferychen777/ggpicrust2/blob/main/README.md

Retrieve the citation for the ggpicrust2 package directly within an R session.

```r
citation("ggpicrust2")
```

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

### Create Pathway Heatmap with Fake Data

Source: https://github.com/cafferychen777/ggpicrust2/blob/main/README.md

Demonstrates creating a pathway heatmap using fake abundance and metadata. Ensure your metadata has a 'sample_name' column.

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

# Create example metadata
# Please change your sample id's column name to sample_name
metadata_example <- data.frame(sample_name = colnames(abundance_example),
                               group = factor(rep(c("Control", "Treatment"), each = 5)))

# Create a heatmap
pathway_heatmap(abundance_example, metadata_example, "group")
```

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

### metagenomeSeq Method Usage

Source: https://github.com/cafferychen777/ggpicrust2/blob/main/_autodocs/05-daa-methods.md

Example of how to call the pathway_daa function using the metagenomeSeq method for differential abundance analysis.

```r
daa_results <- pathway_daa(
  abundance = ko_abundance,
  metadata = metadata,
  group = "Environment",
  daa_method = "metagenomeSeq"
)
```

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

### edgeR Method Usage

Source: https://github.com/cafferychen777/ggpicrust2/blob/main/_autodocs/05-daa-methods.md

Example of how to call the pathway_daa function using the edgeR method for differential abundance analysis.

```r
daa_results <- pathway_daa(
  abundance = ko_abundance,
  metadata = metadata,
  group = "Environment",
  daa_method = "edgeR"
)
```

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

### ALDEx2 Method Usage

Source: https://github.com/cafferychen777/ggpicrust2/blob/main/_autodocs/05-daa-methods.md

Example of how to call the pathway_daa function using the ALDEx2 method for differential abundance analysis.

```r
daa_results <- pathway_daa(
  abundance = ko_abundance,
  metadata = metadata,
  group = "Environment",
  daa_method = "ALDEx2",
  include_effect_size = TRUE
)
```

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

### Load ggprism package for guide_train error

Source: https://github.com/cafferychen777/ggpicrust2/blob/main/README.md

Ensure the 'ggprism' package is loaded to resolve 'guide_train.prism_offset_minor' errors.

```r
library(ggprism)
```

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

### limma voom Method Usage

Source: https://github.com/cafferychen777/ggpicrust2/blob/main/_autodocs/05-daa-methods.md

Example of how to call the pathway_daa function using the limma voom method for differential abundance analysis.

```r
daa_results <- pathway_daa(
  abundance = ko_abundance,
  metadata = metadata,
  group = "Environment",
  daa_method = "limma voom"
)
```

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

### Load ggpicrust2 and Data

Source: https://github.com/cafferychen777/ggpicrust2/wiki/_Footer

Loads the ggpicrust2 library and prepares data for analysis. Ensure pathway_abundance and metadata data frames are loaded before use.

```r
# Install ggpicrust2 (if not already installed)
# install.packages("ggpicrust2")

# Load the ggpicrust2 library
library(ggpicrust2)

# Load your data
# pathway_abundance_df <- read.table("pathway_abundance.txt", header = TRUE, sep = "\t")
# metadata_df <- read.table("metadata.txt", header = TRUE, sep = "\t")
```

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

### Get Available Color Themes

Source: https://github.com/cafferychen777/ggpicrust2/blob/main/_autodocs/03-color-theming.md

Retrieves a character vector of all available color theme names in the ggpicrust2 package. Use this to see which themes can be applied.

```r
# Get all available themes
themes <- get_available_themes()
print(themes)
```

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

### Maaslin2 Usage Example

Source: https://github.com/cafferychen777/ggpicrust2/blob/main/_autodocs/05-daa-methods.md

Performs differential abundance analysis using the Maaslin2 method. This is useful for microbiome association studies with covariates and automatic feature selection.

```r
daa_results <- pathway_daa(
  abundance = ko_abundance,
  metadata = metadata,
  group = "Environment",
  daa_method = "Maaslin2"
)
```

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

### Read Abundance File (R)

Source: https://github.com/cafferychen777/ggpicrust2/blob/main/_autodocs/01-core-api.md

Reads PICRUSt2 abundance files in standard TSV format. Requires the file path as input.

```r
read_abundance_file(file_path)
```

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

### Verify File Existence and Path for ggpicrust2

Source: https://github.com/cafferychen777/ggpicrust2/blob/main/_autodocs/08-errors-and-troubleshooting.md

Check if the specified file exists using file.exists() and ensure the path is correct. Consider using absolute paths if relative paths cause issues.

```r
# Check file existence
file.exists("path/to/abundance.tsv")  # Should return TRUE

# List files in directory
list.files("path/to/directory/", pattern = "\\.tsv$")

# Use absolute path
results <- ggpicrust2(
  file = "/full/path/to/abundance.tsv",  # Use full path
  metadata = metadata,
  group = "Environment",
  pathway = "KO"
)
```

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

### Get Specific Color Palette

Source: https://github.com/cafferychen777/ggpicrust2/blob/main/_autodocs/03-color-theming.md

Retrieves a specified number of hex color codes for a given theme. This is useful for applying custom colors to plots, such as in pathway_errorbar.

```r
# Get 6 colors from the nature theme
colors <- get_color_theme("nature", n_colors = 6)

# Use in pathway_errorbar
pathway_errorbar(
  abundance = ko_abundance,
  daa_results_df = daa_results,
  Group = metadata$Environment,
  colors = colors
)
```

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

### Load Required R Packages

Source: https://github.com/cafferychen777/ggpicrust2/blob/main/_autodocs/06-configuration-reference.md

Installs and loads the core dependencies for ggpicrust2, including dplyr, ggplot2, tidyr, and magrittr. These packages are essential for data manipulation and plotting.

```r
# Core dependencies
dplyr              # Data manipulation
ggplot2            # Plotting engine
tidyr              # Data reshaping
magrittr           # Pipe operator (%>%)
```

```r
# Visualization
patchwork          # Composite plots
ggh4x              # Extended ggplot2 features
aplot              # Plot arrangement
ggprism            # Scientific plot themes
ggplotify          # Convert base plots to ggplot2
```

```r
# Statistics
stats              # Base R statistics
tibble             # Modern data frames
```

```r
# Utilities
readr              # File reading
progress           # Progress bars
grid               # Grid graphics
grDevices          # Graphics devices
utils              # Utilities
methods            # S4 class system
tidygraph          # Graph manipulation
ggraph             # Graph visualization
```

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

### Bulk Analysis with File Input and Comparison

Source: https://github.com/cafferychen777/ggpicrust2/blob/main/_autodocs/07-workflow-examples.md

Processes multiple abundance files for bulk analysis and compares results to find shared significant features across studies. Requires a list of file paths and shared metadata. Uses `purrr::map` for iteration.

```r
library(ggpicrust2)
library(purrr)

# Define file paths
abundance_files <- c(
  "study1_abundance.tsv",
  "study2_abundance.tsv",
  "study3_abundance.tsv"
)

# Assuming same metadata structure for all
metadata <- read.csv("shared_metadata.csv")

# Analyze each file
all_results <- map(abundance_files, function(file) {
  cat("Processing", file, "...\n")
  
  ggpicrust2(
    file = file,
    metadata = metadata,
    group = "Environment",
    pathway = "KO",
    daa_method = "ALDEx2",
    ko_to_kegg = TRUE,
    p_values_threshold = 0.05
  )
})

# Extract shared significant features
all_sig <- map(all_results, function(res) {
  res$daa_results_df %>%
    filter(p_adjust < 0.05) %>%
    pull(feature)
})

# Find features significant in all studies
shared_features <- Reduce(intersect, all_sig)
print(paste("Shared significant features:", length(shared_features)))
```

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

### Basic ggpicrust2 Analysis with KO to KEGG Conversion

Source: https://github.com/cafferychen777/ggpicrust2/blob/main/_autodocs/01-core-api.md

Demonstrates a basic usage of the `ggpicrust2` function, including converting KO abundance to KEGG pathways and specifying analysis parameters. The output can be used for downstream visualization like heatmaps.

```r
# Load data
data(ko_abundance, metadata)

# Basic analysis with KO to KEGG conversion
results <- 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"
)

# Access plot and results
example_plot <- results[[1]]$plot
example_results <- results[[1]]$results

# Use output for downstream analysis
sig_features <- results$daa_results_df %>%
  filter(p_adjust < 0.05) %>%
  pull(feature)
heatmap <- pathway_heatmap(
  abundance = results$abundance[sig_features, ],
  metadata = results$metadata,
  group = results$group
)
```

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

### Read PICRUSt2 Contribution Files

Source: https://github.com/cafferychen777/ggpicrust2/blob/main/README.md

Use `read_contrib_file` for per-sequence contributions or `read_pathway_contrib_file` for pathway-level contributions. The latter can handle gzipped files.

```r
library(ggpicrust2)

# Parse PICRUSt2 per-sequence contribution output
contrib_data <- read_contrib_file("pred_metagenome_contrib.tsv")

# Or parse pathway-level contribution output without running DA analysis
# PICRUSt2 pathway contribution files are often gzipped and use MetaCyc IDs.
path_contrib_data <- read_pathway_contrib_file("path_abun_contrib.tsv.gz")
```

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

### LinDA Usage Example

Source: https://github.com/cafferychen777/ggpicrust2/blob/main/_autodocs/05-daa-methods.md

Performs differential abundance analysis using the LinDA method with specified abundance data, metadata, and grouping variable. A reference group can be set for multi-group comparisons.

```r
daa_results <- pathway_daa(
  abundance = ko_abundance,
  metadata = metadata,
  group = "Environment",
  daa_method = "LinDA",
  reference = "Control"  # For >2 groups
)
```

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

### Perform PCA with Fake Data

Source: https://github.com/cafferychen777/ggpicrust2/blob/main/README.md

Demonstrates performing PCA on fake pathway abundance data and visualizing the results. Requires abundance data and metadata with a grouping variable.

```r
# Create example functional pathway abundance data
abundance_example <- matrix(rnorm(30), nrow = 3, ncol = 10)
colname(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)))
# Perform PCA and create visualizations
pathway_pca(abundance = abundance_example, metadata = metadata_example, "group")
```

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

### Lefser Standalone Usage Example

Source: https://github.com/cafferychen777/ggpicrust2/blob/main/_autodocs/05-daa-methods.md

Performs exploratory differential abundance analysis using the Lefser method. Note that Lefser returns LDA scores, not p-values, and is not recommended for publication-quality statistical testing.

```r
# For exploratory use only - not recommended for publication
daa_results <- pathway_daa(
  abundance = ko_abundance,
  metadata = metadata,
  group = "Environment",
  daa_method = "Lefser"
)
# Results will have 'lda_score' column instead of p-values
```

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

### Provide Input File or Data Frame to ggpicrust2

Source: https://github.com/cafferychen777/ggpicrust2/blob/main/_autodocs/08-errors-and-troubleshooting.md

Ensure either a 'file' path or a 'data' data frame is provided to the ggpicrust2 function. Do not supply both.

```r
results <- ggpicrust2(
  file = "path/to/abundance.tsv",  # Provide one of these
  metadata = metadata,
  group = "Environment",
  pathway = "KO"
)

# OR
results <- ggpicrust2(
  data = abundance_df,              # Not both
  metadata = metadata,
  group = "Environment",
  pathway = "KO"
)
```

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

### ggpicrust2 Main Wrapper Function

Source: https://github.com/cafferychen777/ggpicrust2/blob/main/_autodocs/00-README.md

Use this function as the main entry point for differential abundance analysis and visualization. Specify your data, metadata, grouping variable, pathway type, and optionally, the differential abundance method, KO to KEGG conversion, and p-value threshold.

```r
# Main wrapper function
ggpicrust2(
  data,                     # Abundance data
  metadata,                 # Sample metadata
  group,                    # Group variable
  pathway,                  # "KO", "EC", or "MetaCyc"
  daa_method = "ALDEx2",    # Differential abundance method
  ko_to_kegg = FALSE,       # Convert KO to KEGG pathways
  p_values_threshold = 0.05 # Significance threshold
)
```

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

### Load ggpicrust2 Package

Source: https://github.com/cafferychen777/ggpicrust2/wiki/_Footer

Load the ggpicrust2 package into the R session to make its functions available for use.

```r
library(ggpicrust2)
```

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

### Create Pathway Heatmap with Real Data

Source: https://github.com/cafferychen777/ggpicrust2/blob/main/README.md

Generates a pathway heatmap using real 'metacyc_abundance' and 'metadata'. It includes differential abundance analysis and annotation steps. Features with adjusted p-values less than 0.05 are filtered.

```r
library(tidyverse)
library(ggh4x)
library(ggpicrust2)
# Load the data
data("metacyc_abundance")

# Load the metadata
data("metadata")

# Perform differential abundance analysis
metacyc_daa_results_df <- pathway_daa(
  abundance = metacyc_abundance %>% column_to_rownames("pathway"),
  metadata = metadata,
  group = "Environment",
  daa_method = "LinDA"
)

# Annotate the results
annotated_metacyc_daa_results_df <- pathway_annotation(
  pathway = "MetaCyc",
  daa_results_df = metacyc_daa_results_df,
  ko_to_kegg = FALSE
)

# Filter features with p < 0.05
feature_with_p_0.05 <- metacyc_daa_results_df %>%
  filter(p_adjust < 0.05)

# Create the heatmap
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") %>%
    column_to_rownames("description"),
  metadata = metadata,
  group = "Environment"
)
```

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

### DAA Results Data Frame Example

Source: https://github.com/cafferychen777/ggpicrust2/blob/main/_autodocs/04-types-and-data-structures.md

The output from pathway_daa() is a data frame containing differential abundance analysis results, including feature identifiers, methods, group comparisons, p-values, adjusted p-values, and log2 fold changes.

```plaintext
  feature method group1 group2 p_values    p_adjust adj_method log2_fold_change
1    K00001 ALDEx2   Soil  Water 0.001234 0.00567890        BH            2.345
2    K00002 ALDEx2   Soil  Water 0.034567 0.08765432        BH           -1.234
3    K00003 ALDEx2   Soil  Water 0.456789 0.78901234        BH            0.567
```

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

### read_strat_file()

Source: https://github.com/cafferychen777/ggpicrust2/blob/main/_autodocs/02-visualization-functions.md

Reads stratified abundance data from PICRUSt2 output, providing pathway abundance stratified by taxonomic classification.

```APIDOC
## read_strat_file()

### Description
Reads stratified abundance data from PICRUSt2 output (contributions at different taxonomic levels).

### Signature
```r
read_strat_file(file_path)
```

### Parameters
#### Path Parameters
- **file_path** (character) - Yes - Path to stratified file from PICRUSt2

### Return Value
Data frame with pathway abundance stratified by taxonomic classification.
```

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

### Use 'KO' Pathway with ko_to_kegg = TRUE

Source: https://github.com/cafferychen777/ggpicrust2/blob/main/_autodocs/08-errors-and-troubleshooting.md

The 'ko_to_kegg' option is only valid when the 'pathway' parameter is set to 'KO'. For other pathway types like 'EC' or 'MetaCyc', ensure 'ko_to_kegg' is FALSE.

```r
# Ko_to_kegg only works with KO pathways
results <- ggpicrust2(
  data = ko_abundance,
  metadata = metadata,
  group = "Environment",
  pathway = "KO",           # Must be "KO"
  ko_to_kegg = TRUE,        # Now valid
  p_values_threshold = 0.05
)

# For EC or MetaCyc, don't use ko_to_kegg
results <- ggpicrust2(
  data = ec_abundance,
  metadata = metadata,
  group = "Environment",
  pathway = "EC",           # EC or MetaCyc
  ko_to_kegg = FALSE,       # Must be FALSE
  p_values_threshold = 0.05
)
```

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

### Compare DAA Methods (ALDEx2, DESeq2, LinDA)

Source: https://github.com/cafferychen777/ggpicrust2/blob/main/_autodocs/07-workflow-examples.md

Compares differential abundance analysis results from ALDEx2, DESeq2, and LinDA on the same dataset. Provides consistency and summary statistics, and a comparison plot.

```r
library(ggpicrust2)
library(dplyr)

# Load data
data(ko_abundance, metadata)

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

# Run three methods
methods <- c("ALDEx2", "DESeq2", "LinDA")
results_list <- list()

for (method in methods) {
  cat("Running", method, "...\n")
  
  daa_results <- pathway_daa(
    abundance = abundance,
    metadata = metadata,
    group = "Environment",
    daa_method = method,
    p_adjust_method = "BH",
    reference = "Soil",
    include_abundance_stats = TRUE
  )
  
  results_list[[method]] <- daa_results
}

# Compare results
comparison <- compare_daa_results(
  daa_results_list = results_list,
  method_names = methods,
  p_values_threshold = 0.05
)

# View consistency
print(comparison$consistency)
print(comparison$summary_statistics)

# Plot comparison
plot(comparison$method_comparison_plot)

```

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

### Run ggpicrust2 with File Path

Source: https://github.com/cafferychen777/ggpicrust2/blob/main/README.md

Use this snippet to run the ggpicrust2 analysis when your abundance data is in a TSV file. Ensure your metadata is loaded and correctly formatted.

```r
library(readr)
library(ggpicrust2)
library(tibble)
library(tidyverse)
library(ggprism)
library(patchwork)

# Load necessary data: abundance data and metadata
abundance_file <- "path/to/your/abundance_file.tsv"
metadata <- read_delim(
    "path/to/your/metadata.txt",
    delim = "\t",
    escape_double = FALSE,
    trim_ws = TRUE
)

# Run ggpicrust2 with input file path
results_file_input <- ggpicrust2(file = abundance_file,
                                 metadata = metadata,
                                 group = "your_group_column", # For example dataset, group = "Environment"
                                 pathway = "KO",
                                 daa_method = "LinDA",
                                 ko_to_kegg = TRUE,
                                 order = "pathway_class",
                                 p_values_bar = TRUE,
                                 x_lab = "pathway_name")
```