DOCSEARCHbyAlgolia
Submit Docs

ggpicrust2 R Package

repository·main·Indexed 41 days ago

https://github.com/cafferychen777/ggpicrust2

An R package for the analysis, annotation, and visualization of PICRUSt2 functional prediction results. It provides tools for converting KO abundance to KEGG pathway abundance, performing differential abundance analysis (DAA) using methods like ALDEx2, DESeq2, and LinDA, and generating publication-quality visualizations including volcano plots, ridge plots, heatmaps, and PCA.

Tokens
11.2K
Snippets
30
Records
36
Agent score
3%

What's inside ggpicrust2

  1. Overview of ggpicrust2 functionality

    main

    ggpicrust2 is an R package designed for analyzing and interpreting PICRUSt2 functional prediction results.

    Key capabilities include:

    • Pathway Annotation: Adding names and descriptions to pathways.
    • Differential Abundance (DA): Advanced methods to identify significantly different functional profiles.
    • GSEA: Gene Set Enrichment Analysis for PICRUSt2 data.
    • Consistency Assessment: Comparing different DA methods on the same dataset to evaluate robustness.
    • Taxa Contribution: Parsing per-sequence outputs to identify which taxa drive pathway shifts.
    • Visualization: Publication-quality plots including volcano plots, ridge plots, heatmaps, and PCA.

  2. Understanding why no statistically significant biomarkers are found

    main

    If your analysis yields no statistically significant biomarkers, consider these potential causes:

    1. Small effect size: The biological difference between groups may be minimal.
    2. Low statistical power: Your sample size may be too small to detect existing differences.
    3. High intra-group variation: Large variation within groups can mask differences between groups.

    Suggestions:

    • Increase sample size.
    • Decrease intra-group variation (e.g., by cleaning data or stratifying analysis).
    • Adjust statistical methods (e.g., switching between parametric and non-parametric tests).

  3. Install optional Bioconductor dependencies for ggpicrust2

    main

    While ggpicrust2 works with a minimal CRAN installation, many advanced workflows (like specific differential abundance methods or complex heatmaps) require Bioconductor packages. You can install the necessary suite using BiocManager.

    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)
}

  4. Reduce clutter in visualizations with many significant features

    main

    When a visualization becomes cluttered due to having more than 30 statistically significant features, use one of the following strategies:

    Solution 1: Use the select parameter

    Specify exactly which features (e.g., KO IDs) you want to visualize using the select argument in pathway_errorbar.

    Solution 2: Limit to the Top 20 features

    Filter your results to only include the top 20 features with the smallest adjusted p-values.

    # Solution 1: Explicit selection
ggpicrust2::pathway_errorbar(
  abundance = kegg_abundance,
  daa_results_df = daa_results_df_annotated,
  Group = metadata$Day,
  p_values_threshold = 0.05,
  order = "pathway_class",
  select = c("ko05340", "ko00564", "ko00680"), # Add specific IDs here
  ko_to_kegg = TRUE,
  p_value_bar = FALSE,
  colors = NULL,
  x_lab = "pathway_name"
)

# Solution 2: Top 20 by p-value
daa_results_df_annotated <- daa_results_df_annotated[!is.na(daa_results_df_annotated$pathway_name),]
daa_results_df_annotated$p_adjust <- round(daa_results_df_annotated$p_adjust, 5)
low_p_feature <- daa_results_df_annotated[order(daa_results_df_annotated$p_adjust), ]$feature[1:20]

p <- ggpicrust2::pathway_errorbar(
  abundance = kegg_abundance,
  daa_results_df = daa_results_df_annotated,
  Group = metadata$Day,
  p_values_threshold = 0.05,
  order = "pathway_class",
  select = low_p_feature,
  ko_to_kegg = TRUE,
  p_value_bar = FALSE,
  colors = NULL,
  x_lab = "pathway_name"
)

  5. Install ggpicrust2 from GitHub

    main

    To install the development version of ggpicrust2, you need the devtools package. Use devtools::install_github() to pull the package directly from the repository.

    # install.packages("devtools")
devtools::install_github("cafferychen777/ggpicrust2")

  6. Debug ggpicrust2 by running individual functions

    main

    If the high-level ggpicrust2() function fails, you can execute the pipeline steps manually using individual functions. This approach is faster for debugging and allows for fine-grained control over each stage of the analysis.

    The manual workflow typically follows this sequence:

    1. Convert KO to KEGG: Use ko2kegg_abundance().
    2. Differential Abundance Analysis (DAA): Use pathway_daa().
    3. Annotation: Use pathway_annotation().
    4. Visualization: Use pathway_errorbar(), pathway_heatmap(), or pathway_pca().

  7. Taxa contribution workflow

    main

    This workflow connects PICRUSt2 contribution outputs with downstream pathway interpretation.

    1. Parse PICRUSt2 files:

      • Use read_contrib_file() for pred_metagenome_contrib.tsv.
      • Use read_pathway_contrib_file() for pathway-level path_abun_contrib.tsv (supports gzipped files).
      • Use read_strat_file() for pred_metagenome_strat.tsv.

    2. Aggregate contributions: Use aggregate_taxa_contributions() to aggregate to a specific taxonomic level (e.g., tax_level = "Genus"). You can optionally filter by significant pathways using daa_results_df from pathway_daa().

    3. Visualize:

      • taxa_contribution_bar(): Visualize per-sample contributions.
      • taxa_contribution_heatmap(): Summarize mean contribution patterns across taxa and functions.

    Example Workflow:

    library(ggpicrust2)

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

# Parse pathway-level contribution output
path_contrib_data <- read_pathway_contrib_file("path_abun_contrib.tsv.gz")

# Aggregate contributions to genus level and keep top taxa
taxa_contrib <- aggregate_taxa_contributions(
  contrib_data = contrib_data,
  taxonomy = your_taxonomy_table,
  tax_level = "Genus",
  top_n = 10
)

# Visualize per-sample contributions
taxa_contribution_bar(
  contrib_agg = taxa_contrib,
  metadata = metadata,
  group = "Environment",
  facet_by = "function"
)

# Summarize mean contribution patterns
taxa_contribution_heatmap(
  contrib_agg = taxa_contrib,
  n_functions = 20
)

  8. Install optional Bioconductor dependencies

    main

    While ggpicrust2 works with a minimal CRAN installation, several advanced workflows (like specific differential abundance methods or complex heatmaps) require Bioconductor packages. Use the following script to install the necessary dependencies via BiocManager.

    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)
}

  9. Fix `guide_train.prism_offset_minor` error

    main

    If you encounter errors related to guide_train.prism_offset_minor (e.g., No minor breaks exist... or guide_prism_offset_minor' of mode'function' was not found), ensure that the ggprism package is loaded in your R session.

    library(ggprism)

  10. Troubleshoot SSL certificate and HTTP 400 errors

    main

    SSL Certificate Problem

    If you see SSL peer certificate or SSH remote key was not OK: [rest.kegg.jp] SSL certificate problem: certificate has expired, ensure your network can bypass firewalls (specifically relevant for users in China).

    Bad Request (HTTP 400)

    If you encounter Error in .getUrl(url, .flatFileParser) : Bad Request (HTTP 400), restart your R session.

  12. Fix `grid.Call` text bounds error

    main
    If you encounter Error in grid.Call(C_textBounds, as.graphicsAnnot(xlabel),x$x, x$y, :, you likely need to install the fonts required by your selected plotting theme. After installing the fonts, restart the R graphics device and rerun the plot.