HolobiomicsLab 
ggplot2-geom-treemap-rendering
Summary
Render hierarchical ion filtering results as a treemap visualization using ggplot2's geom_treemap() and geom_treemap_text() layers, scaled by ion counts and annotated with filter status labels and percentages. This skill transforms aggregated qc_summary() data into a publication-ready treemap that communicates the distribution and relative abundance of ions across filter outcome categories.
When to use
After running qc_summary() on a filtered mpactr object and aggregating ion counts by filter status category (passed/failed). Use this skill when you need to communicate the proportional breakdown of ions retained vs. removed by filtering, and when a compact, area-encoded visualization is preferred over bar charts for showing multiple hierarchical dimensions (status, count, percentage) simultaneously.
When NOT to use
- Input contains only a single filter status category (treemap loses hierarchical meaning with one rectangle).
- Ion count data is not pre-aggregated by status; raw feature-level data will produce an uninterpretable treemap with too many small tiles.
- Audience requires precise numerical comparison across many status categories; bar charts or tables are more readable than area encoding when exact values matter more than proportional intuition.
Inputs
- mpactr object (filtered)
- data.table from qc_summary() output containing ion status (passed/failed filters)
- aggregated ion counts by filter status category
Outputs
- ggplot2 treemap object
- PNG file of rendered treemap visualization
How to apply
Extract the qc_summary() data.table, aggregate ion counts by filter status using data.table syntax, and calculate the percentage of total ions per status. Initialize a ggplot() call mapping status to fill aesthetic and ion count to the area parameter. Layer geom_treemap() to render rectangles sized by ion count, then geom_treemap_text() to overlay status labels and percentage annotations. Customize with scale_fill_brewer() (e.g., Greens palette) to distinguish status categories, suppress the legend, and apply ggplot2 theme() functions for publication formatting. Save the rendered plot to PNG.
Related tools
- ggplot2 (Core graphics framework for treemap layer specification and customization)
- treemapify (Provides geom_treemap() and geom_treemap_text() layers for rectangular treemap rendering)
- mpactr (Generates qc_summary() data.table containing ion filter status used as input) — https://github.com/mums2/mpactr
- data.table (Efficient aggregation and percentage calculation from qc_summary() output)
- scale_fill_brewer() (Applies categorical color palette (e.g., Greens) to distinguish filter status)
Examples
qc_dt <- qc_summary(filtered_mpactr_obj)[, .(ion_count = .N, pct = 100*.N/nrow(qc_summary(filtered_mpactr_obj))), by=status]; ggplot(qc_dt, aes(area=ion_count, fill=status, label=paste0(status, '\n', ion_count, ' (', round(pct,1), '%)'))) + geom_treemap() + geom_treemap_text(place='centre') + scale_fill_brewer(palette='Greens') + theme(legend.position='none') + ggsave('ion_filter_treemap.png')
Evaluation signals
- Treemap renders with exactly one rectangle per filter status category, sized proportional to ion count.
- geom_treemap_text() labels are legible and correctly display status name, ion count, and percentage (sum to 100%).
- Color palette is applied consistently and legend is suppressed when specified.
- PNG file is written to disk with expected dimensions and no rendering artifacts.
- Ion counts in treemap match aggregated values from qc_summary() data.table (no data loss or duplication).
Limitations
- Treemap readability degrades with more than ~6–8 status categories; extremely granular status hierarchies may require faceting or hierarchical treemaps.
- Text labels may overlap or become unreadable if rectangles are too small; aggregate data or increase figure dimensions as needed.
- Treemapify's geom_treemap() does not natively support interactive tooltips; use plotly::ggplotly() for interactivity or plotly treemaps for hover annotations.
- Color blindness accessibility depends on palette choice; scale_fill_brewer() Greens is red–green colorblind-safe, but confirm with CVD simulators for other palettes.
Evidence
- [other] Ion counts and percentages by status are computed from qc_summary() output using data.table syntax, then rendered as a treemap with geom_treemap() and geom_treemap_text() to display status labels, ion counts, and percentages: "Ion counts and percentages by status are computed from qc_summary() output using data.table syntax, then rendered as a treemap with geom_treemap() and geom_treemap_text() to display status labels,"
- [other] Create a treemap using ggplot2 geom_treemap() and geom_treemap_text() with Greens palette, no legend, sized by ion count and labeled with status and percentage.: "Create a treemap using ggplot2 geom_treemap() and geom_treemap_text() with Greens palette, no legend, sized by ion count and labeled with status and percentage"
- [other] The visualization can be customized with ggplot2 scale_fill_brewer() and theme() functions.: "The visualization can be customized with ggplot2 scale_fill_brewer() and theme() functions"