# patchwork — Compose Multiple ggplot2 Plots into Rich Layouts

> patchwork is an R package that makes it simple to combine multiple ggplot2 plots into a single composite figure using arithmetic operators. It handles alignment, shared legends, nested layouts, and annotations across panels.

## Install

Save as a script file and run:

# patchwork — Compose Multiple ggplot2 Plots into Rich Layouts

## Quick Use
```r
install.packages("patchwork")
library(ggplot2); library(patchwork)
p1 <- ggplot(mtcars, aes(mpg, hp)) + geom_point()
p2 <- ggplot(mtcars, aes(factor(cyl))) + geom_bar()
p1 + p2  # side by side
p1 / p2  # stacked vertically
```

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

---
Source: https://tokrepo.com/en/workflows/asset-7cb07166
Author: Script Depot