patchwork — Compose Multiple ggplot2 Plots into Rich Layouts

Introduction

patchwork is an R package by Thomas Lin Pedersen that extends ggplot2 with a simple operator-based syntax for combining multiple plots into composite figures. Before patchwork, arranging ggplot2 plots required grid manipulation or packages like gridExtra with verbose code. patchwork replaces all of that with intuitive +, /, and | operators.

What patchwork Does

• Combines ggplot2 plots side by side with + or | and stacks them vertically with /
• Aligns axes and plot areas automatically across panels for clean multi-plot figures
• Collects duplicate legends into a single shared legend with plot_layout(guides = "collect")
• Supports nested layouts using parentheses: (p1 | p2) / p3 puts two plots on top and one below
• Adds overall titles, subtitles, and captions to the composite figure with plot_annotation()

Architecture Overview

patchwork wraps ggplot2 objects in a custom patchwork class that overloads arithmetic operators. When printed or saved, it calculates a layout grid, aligns the panels by matching axis positions, and renders each plot into its assigned cell using ggplot2's gtable system. The layout can be specified explicitly with plot_layout(design = ...) for arbitrary grid arrangements. Insets (small plots overlaid on larger ones) are supported via inset_element().

Self-Hosting & Configuration

• Install from CRAN: install.packages("patchwork")
• Requires ggplot2 3.0+ and R 3.6+
• Control relative widths and heights with plot_layout(widths = c(2, 1), heights = c(1, 1))
• Collect shared legends with plot_layout(guides = "collect") and theme(legend.position = "bottom")
• Tag panels with letters or numbers via plot_annotation(tag_levels = "A")

Key Features

• Operator-based syntax (+, /, |) makes multi-plot composition intuitive and concise
• Automatic axis alignment ensures visual consistency across panels
• Nested layouts with parentheses allow complex grid arrangements without explicit grid specs
• Panel tagging adds publication-style labels (A, B, C) automatically
• Works with any ggplot2 object, including those from extension packages

Comparison with Similar Tools

• gridExtra (R) — grid.arrange() places plots on a grid but does not align axes or share legends; patchwork does both
• cowplot (R) — plot_grid() offers similar features but patchwork's operator syntax is more concise and handles nesting naturally
• egg (R) — focuses on axis alignment; patchwork provides alignment plus layout composition in one package
• matplotlib subplots (Python) — imperative subplot API; patchwork's declarative operators are simpler for common layouts
• facet_wrap / facet_grid (ggplot2) — splits one dataset across panels; patchwork combines independent plots with potentially different data

FAQ

Q: Can I combine plots with different data sources? A: Yes. Each plot in a patchwork composition is an independent ggplot2 object with its own data, aesthetics, and geoms.

Q: How do I control relative panel sizes? A: Use plot_layout(widths = c(2, 1)) for column widths or heights = c(1, 3) for row heights. Values are relative proportions.

Q: Can I add a shared title across all panels? A: Yes. Use plot_annotation(title = "Overall Title", subtitle = "Subtitle").

Q: Does patchwork work with non-ggplot2 graphics? A: patchwork is designed for ggplot2 objects. Use wrap_elements() to include base R plots or grid grobs in a patchwork layout.

Sources

• https://github.com/thomasp85/patchwork
• https://patchwork.data-imaginist.com/