# Ggplot2 Pie Chart Rendering

> 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.

- Skill: `holobiomicslab/ggplot2-pie-chart-rendering` (Agent Skill)
- Install (CLI): `npx skillmds@latest add holobiomicslab/ggplot2-pie-chart-rendering`
- Raw SKILL.md: https://api.skillmd.com/api/skills/holobiomicslab/ggplot2-pie-chart-rendering/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: CC-BY-4.0
- Author: HolobiomicsLab (https://skillmd.com/u/holobiomicslab)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/holobiomicslab/ggplot2-pie-chart-rendering

---


# 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"