Ggplot2 Pie Chart Rendering

---
name: ggplot2-pie-chart-rendering
description: Use when you have a frequency table (generated by count_fold_changes
  and converted to relative abundance via ra_table) of metabolite subsets stratified
  by class or direction of change (e.g., increased vs. decreased organic acids at
  padj ≤ 0.
license: CC-BY-4.0
metadata:
  edam_operation: http://edamontology.org/operation_3441
  edam_topics:
  - http://edamontology.org/topic_3172
  - http://edamontology.org/topic_0091
  tools:
  - R
  - ggplot2
  - omu pie_chart function
  - count_fold_changes
  - ra_table
  license_tier: open
  provenance_tier: literature
derived_from:
- doi: 10.1128/mra.00129-19
  title: omu metabolomics count data tool
evidence_spans:
- Omu is an R package that enables rapid analysis of Metabolomics data sets
- The figure is a ggplot2 object, so it is compatible with any ggplot2 themes
- The figure is a ggplot2 object, so it is compatible with any ggplot2 themes you
  wish to use to edit the appearance
claims: []
provenance:
  collection: https://w3id.org/holobiomicslab/asb-skill/collection/metabolomics/v2
  assembled_by: scripts/collect_metabolomics_collection.py
  sources:
  - build: coll_omu_metabolomics_count_data_tool_cq
    doi: 10.1128/mra.00129-19
    title: omu metabolomics count data tool
  dedup_kept_from: coll_omu_metabolomics_count_data_tool_cq
schema_version: 0.2.0
attribution:
  generator: AgenticScienceBuilder
  original_doi: 10.1128/mra.00129-19
  all_source_dois:
  - 10.1128/mra.00129-19
  zenodo_doi: 10.5281/zenodo.20794027
  curators: []
  promoter: Louis-Félix Nothias
  sponsor: CNRS & Université Côte d'Azur
---

# ggplot2-pie-chart-rendering

## Summary

Generate publication-ready pie chart visualizations of metabolite class frequency distributions from omu metabolomics analysis, using ggplot2 to render filtered and normalized count data as proportional segments with customizable styling.

## When to use

You have a frequency table (generated by count_fold_changes and converted to relative abundance via ra_table) of metabolite subsets stratified by class or direction of change (e.g., increased vs. decreased organic acids at padj ≤ 0.05), and you need a visual summary of the proportional distribution of those categories for publication or presentation.

## When NOT to use

- Input is already a rendered graphic or non-tabular format (e.g., PNG, SVG) — re-rendering will degrade quality.
- Data contains more than ~8–10 categories, as pie charts become visually cluttered and difficult to interpret; use bar charts or faceted plots instead.
- The frequency table has not been normalized to relative abundance (percentage), as raw counts may be misleading in pie chart proportions without context.

## Inputs

- omu_summary output dataframe (containing metabolite names, Class metadata, padj values, log2FoldChange)
- Frequency table from count_fold_changes (metabolite counts by class and direction)
- Relative abundance table from ra_table (percentage values by class)

## Outputs

- ggplot2 pie chart object
- PNG or vector graphics file (saved via base R or ggplot2 graphics export)

## How to apply

Load the omu_summary output dataframe filtered by statistical significance (padj ≤ 0.05) and metabolite class. Apply count_fold_changes with column='Class' to generate a frequency table of increased/decreased counts. Transform this frequency table to relative abundance (percentage) using ra_table with variable='Class'. Pass the resulting dataframe to the pie_chart function, specifying the ratio_data argument, variable='Class', column parameter (e.g., 'Decrease'), and optional styling parameters such as color='black'. The function returns a ggplot2 object, which is compatible with ggplot2 themes and can be exported to PNG or other graphics formats using standard R graphics export methods.

## Related tools

- **ggplot2** (Core graphics engine for pie_chart rendering; produces ggplot2 objects compatible with ggplot2 themes and export utilities)
- **omu pie_chart function** (Wrapper function that orchestrates ggplot2 pie chart construction from ratio_data, applying variable and column filters and color styling) — https://github.com/connor-reid-tiffany/Omu
- **count_fold_changes** (Prerequisite function to generate frequency table of metabolite counts stratified by class and fold-change direction (increased/decreased)) — https://github.com/connor-reid-tiffany/Omu
- **ra_table** (Prerequisite function to transform count frequency table into relative abundance (percentage) format required for accurate pie chart proportions) — https://github.com/connor-reid-tiffany/Omu

## Examples

```
pie_chart(ratio_data = ra_result, variable = 'Class', column = 'Decrease', color = 'black'); ggsave('organic_acids_pie.png', width = 6, height = 6)
```

## Evaluation signals

- Output is a valid ggplot2 object (inherits class 'ggplot'); verify with class(pie_obj) in R.
- Pie segments sum to 100% (or 1.0 if normalized 0–1); verify with sum(pie_obj$data$value) or inspect the underlying ratio_data.
- Segments are colored according to specified parameters (e.g., color='black' or palette); visual inspection or extraction of scale_fill values.
- Chart renders without errors when exported to PNG via ggsave or print(pie_obj); file exists and is non-zero bytes.
- Segment labels (if present) correspond to Class categories and direction values used in count_fold_changes (e.g., 'Organic acids – Decrease', 'Organic acids – Increase').

## Limitations

- Pie charts are difficult to interpret when more than 8–10 categories are present; consider faceted bar charts or alternative visualizations for complex datasets.
- The pie_chart function requires input data to be pre-normalized to relative abundance; raw counts will produce misleading proportions.
- No built-in support for nested or hierarchical pie charts; multi-level class structures must be aggregated or flattened prior to visualization.
- Color customization is limited to simple parameters (e.g., color='black'); complex color palettes or per-segment color mapping may require direct ggplot2 manipulation.

## Evidence

- [other] pie_chart-frequency-table-from-ra_table: "First, a frequency data frame (percentage values) must be made from the count data frame using the ```ra_table``` function"
- [other] pie_chart-function-invocation: "This frequency data frame can be used in the ```pie_chart``` function"
- [other] ggplot2-compatibility: "The figure is a ggplot2 object, so it is compatible with any ggplot2 themes"
- [other] task-workflow-pie-chart: "Generate a pie_chart with pie_chart function specifying ratio_data, variable='Class', column='Decrease', and color='black'"
- [other] count-fold-changes-prerequisite: "Apply count_fold_changes with column='Class' and sig_threshold=0.05 to generate a frequency table counting increased vs. decreased metabolites"