[QUESTION] Access PCA/heatmap outputs from ggpicrust2() workflow function

[irc47]

❓ Question / Help Request

📋 What do you need help with?

• [X ] Understanding how to use a specific function
• Choosing the right analysis method
• Interpreting results
• Data preparation and formatting
• Installation or setup issues
• Best practices for my research question
• Troubleshooting unexpected results
• Other: ___________

🔬 Research Context

I'm just beginning to use ggpicrust2 and am testing it out with the example data and a small amount of my own data. Based on the workflow diagram, it looks like the ggpicrust2() function should include pathway_pca() and pathway_heatmap() outputs, but the only plot I can find is the pathway_errorbars(). Am I wrong about my expectation here?

Study type:

• Case-control study
• Time series / longitudinal
• Cross-sectional
• Experimental design
• Other: ___________

📊 Your Data

Data source:

• [ X] PICRUSt2 output (pred_metagenome_unstrat.tsv)
• Processed abundance data
• Example data from package
• Other: ___________

Data characteristics:

• Number of samples:
• Number of groups/conditions:
• Sample size per group:
• Type of microbiome data: [e.g., 16S, shotgun metagenomics]

💻 What you've tried

Current approach:

## my data
ggpicrust2_default <- ggpicrust2(data = abundance_dup, #use file if loading directly from a file and not an R object
                                 metadata = metadata,
                                 group = "test1", # 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")

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

results_file_input[[1]]$plot

Current results or issues:
I was expecting all three pathway plots, or at least an object that could be passed to those plots. I can reformat the ggpicrust2() output results and then use the pathway_heatmap() on that, but it seems inefficient given that it looks like the main workflow function should be able to do this.

🎯 Specific Questions

📚 Background Research

• [X ] I've read the package documentation
• [ X] I've reviewed the vignettes
• [ X] I've searched existing issues
• I've consulted relevant literature

Helpful resources you've already checked:

🖥️ Environment (if relevant)

• Operating System:
• R Version:
• ggpicrust2 Version:

🔄 Analysis Goals

What do you ultimately want to achieve?

• Identify differentially abundant pathways
• Create publication-quality figures
• Compare different methods
• Perform statistical analysis
• Data exploration and visualization
• Other: ___________

⏰ Timeline

• This is urgent for a deadline
• I have some flexibility with timing
• This is for future planning

📖 Additional Context

Any other information that might be helpful for understanding your question or providing better guidance.

[cafferychen777]

Hi @zhaohq-stu,

Thank you for this excellent feature request! We've implemented the changes to make ggpicrust2() output seamlessly compatible with pathway_pca() and pathway_heatmap().

What's New

The ggpicrust2() function now returns additional fields alongside the existing plot/results structure:

• $abundance - The processed abundance data (KEGG pathway or original)
• $metadata - The metadata data frame
• $group - The group variable name used in the analysis
• $daa_results_df - The complete annotated DAA results data frame
• $ko_to_kegg - Logical indicating whether KO to KEGG conversion was performed

Usage Example

# Run ggpicrust2 analysis
result <- ggpicrust2(
  data = ko_abundance,
  metadata = metadata,
  group = "Environment",
  pathway = "KO",
  daa_method = "LinDA",
  ko_to_kegg = TRUE
)

# Access the error bar plot (backward compatible)
print(result[[1]]$plot)

# Use returned data for PCA analysis (no re-preparation needed)
pca_plot <- pathway_pca(
  abundance = result$abundance,
  metadata = result$metadata,
  group = result$group
)

# Use returned data for heatmap (filter significant pathways first)
sig_features <- result$daa_results_df %>%
  dplyr::filter(p_adjust < 0.05) %>%
  dplyr::pull(feature)

if (length(sig_features) > 0) {
  heatmap_plot <- pathway_heatmap(
    abundance = result$abundance[sig_features, , drop = FALSE],
    metadata = result$metadata,
    group = result$group
  )
}

Backward Compatibility

All existing code will continue to work - result[[1]]$plot and result[[1]]$results are still available.

This change is available in the development version. Please let us know if you have any questions!

Best regards