socviz

name	socviz
description	Data visualization with ggplot2 based on Kieran Healy's "Data Visualization: A Practical Introduction" (2nd ed., 2026). Use when creating, reviewing, or improving ggplot2 visualizations, choosing appropriate chart types, applying perceptual principles, faceting and grouping data, labeling and annotating plots, visualizing model results, drawing maps, or polishing figures for publication. Covers the grammar of graphics workflow, visual perception, color palettes, layered plot construction, and theme customization.
license	CC-BY-NC-ND
metadata	{"source":"https://socviz.co","author":"Kieran Healy","edition":"2nd (2026)","publisher":"Princeton University Press"}
allowed-tools	Read, Edit, Write, Grep, Glob, mcp__r-btw__*

Data Visualization with ggplot2

Based on: Data Visualization: A Practical Introduction (2nd ed.) Author: Kieran Healy (2026). Princeton University Press. Free online: https://socviz.co

Core philosophy

Visualization is a tool for understanding data, not decoration. Every graph encodes data through visual channels (position, length, color, shape) that the human perceptual system decodes with varying accuracy. Good visualization requires understanding both the grammar of graphics and the perceptual system that interprets the output.

The ggplot2 workflow

Every visualization follows the same five steps:

1. Tidy data -- Long format: every variable a column, every observation a row
2. Mapping -- aes() connects data variables to visual properties (x, y, color, fill, size, shape)
3. Geom -- Geometric objects render the mapping (points, lines, bars, etc.)
4. Scales and coordinates -- Transform axes, set breaks, choose projections
5. Labels and guides -- Titles, legends, annotations, themes

p <- ggplot(data = df,
            mapping = aes(x = var1, y = var2, color = group))
p + geom_point() +
  scale_x_log10(labels = scales::label_comma()) +
  labs(x = "X Label", y = "Y Label", title = "Title")

When to use this skill

• User wants to create or improve a ggplot2 visualization
• User asks which chart type to use for their data
• User needs help with faceting, grouping, labeling, or annotating plots
• User wants to visualize model results (coefficients, predictions, residuals)
• User asks about color palettes, themes, or publication-quality figures
• User wants to draw maps with sf or statebins
• User asks about perceptual principles for data visualization

Instructions

1. Classify the request:

   • Perceptual/design: Which chart type? What color palette? How to avoid misleading? --> Use references/perception-principles.md
   • Building a plot: How to facet, group, layer, label? --> Use the relevant reference file
   • Model visualization: Coefficients, predictions, residuals? --> Use references/model-visualization.md
   • Maps: Choropleth, cartogram, spatial data? --> Use references/maps-spatial.md
   • Polishing: Themes, color, layout, patchwork? --> Use references/themes-polish.md

2. Read the relevant reference files before answering

3. Apply these principles in every response:

   • Match visual encoding to data type (position for quantitative, color hue for categorical)
   • Prefer position on common scale over length, angle, or area
   • Use tidy (long-format) data; reshape before plotting if needed
   • Build plots layer by layer; inspect at each step
   • Distinguish mapping (inside aes()) from setting (inside geom_*())
   • Calculate summaries with dplyr before graphing when geom_bar()/stat_count() gets confusing
   • Use facet_wrap() or facet_grid() instead of cramming too much into one panel

4. Follow write-r conventions for all R code (native pipe |>, .by, join_by(), etc.)

Available resources

Reference files (references/)

File	Topic	Covers
perception-principles.md	Visual perception and chart choice	Preattentive features, gestalt rules, Cleveland-McGill ranking, color models, honesty/judgment tradeoffs
ggplot-fundamentals.md	Core ggplot2 patterns	Tidy data, aes() mapping vs setting, layering geoms, scales, saving plots
grouping-faceting.md	Grouped data and faceting	group aesthetic, facet_wrap/facet_grid, stat transformations, histograms, density plots
labels-annotations.md	Text, labels, and annotations	Pipes for summarization, text/label geoms, ggrepel, annotate(), scales/guides/themes framework
model-visualization.md	Visualizing model results	broom (tidy/augment/glance), coefficient plots, residuals, nested models, survey data, marginal effects
maps-spatial.md	Maps and spatial data	sf objects, geom_sf, choropleths, cartograms, statebins, viridis palettes, MAUP
themes-polish.md	Polishing and customization	Color palettes, layer-highlight-repeat, theme(), patchwork layouts, workhorses vs show ponies

Function reference (via MCP, not bundled)

• R: Use btw_tool_docs_help_page(package_name="ggplot2", topic="<function>") for live docs
• R: Use Context7 with library ID for ggplot2 code examples
• Key packages: ggplot2, scales, ggrepel, patchwork, sf, statebins, broom, colorspace

Quick reference: choosing a geom

Data situation	Recommended geom	Avoid
Two continuous variables	geom_point()
Continuous + trend	geom_point() + geom_smooth()
One continuous, one categorical	geom_boxplot(), geom_violin(), geom_jitter()
Single continuous distribution	geom_histogram(), geom_density()
Counts of categories	geom_bar()	Pie charts
Pre-computed summary	geom_col() or geom_bar(stat = "identity")
Coefficients with CIs	geom_pointrange()	Bar charts for coefficients
Time series by group	geom_line(aes(group = ...))
Trajectories + trend	Gray geom_line() + colored geom_smooth()
Spatial/geographic	geom_sf()	geom_polygon() with map_data (legacy)
Two categorical cross-tab	facet_grid(row ~ col)	Stacked bars (except bottom category)
Many categories	Horizontal layout (categories on y-axis)	Rotated x-axis labels
Labeled points	ggrepel::geom_text_repel()	geom_text() without repulsion

Key anti-patterns

Avoid	Do instead	Why
Pie charts	Faceted bar charts or dot plots	Angles decoded poorly (Cleveland-McGill)
3D effects	Flat 2D encodings	Perspective distorts values
Stacked bars (comparing middle categories)	Faceted bars or Cleveland dot plots	Only bottom category has stable baseline
Mapping a string inside aes()	Set property in geom_*() directly	aes(color = "purple") creates unwanted legend
geom_bar() for pre-computed data	geom_col()	geom_bar() counts rows by default
Default alphabetical ordering	reorder(category, value)	Meaningful order aids comparison
Too many channels at once	Facet or simplify	Shape + color + size overwhelms preattentive processing
Picking colors ad hoc	Use ColorBrewer, viridis, or colorspace palettes	Perceptually uniform, colorblind-safe
+ geom_point() on next line	geom_point() + at end of line	ggplot + must end the line, not begin one

Example: complete workflow

library(tidyverse)
library(scales)
library(ggrepel)

# 1. Summarize data
by_continent <- gapminder |>
  summarize(
    mean_life = mean(lifeExp),
    mean_gdp = mean(gdpPercap),
    n_countries = n_distinct(country),
    .by = continent
  )

# 2. Build plot layer by layer
p <- ggplot(by_continent,
            aes(x = mean_gdp, y = mean_life))

p +
  geom_point(aes(size = n_countries), alpha = 0.7) +
  geom_text_repel(aes(label = continent)) +
  scale_x_log10(labels = label_currency()) +
  scale_size_continuous(range = c(3, 10)) +
  labs(
    x = "Mean GDP per Capita",
    y = "Mean Life Expectancy (years)",
    size = "Countries",
    title = "Economic Development and Life Expectancy",
    caption = "Source: Gapminder."
  ) +
  theme_minimal() +
  theme(legend.position = "bottom")

Best practices

• Always build plots incrementally and inspect at each layer
• Use ggsave() with explicit dimensions and vector formats (PDF, SVG) for publication
• Organize figures in a figures/ subdirectory; use here::here() for paths
• Use guides(fill = "none") to remove redundant legends
• When debugging bizarre output, check the relationship between data structure and aesthetic mappings first
• Prefer faceting over dodging for grouped comparisons
• Place categories on the y-axis when there are many levels
• Order categories by the value being displayed, not alphabetically
• Use scales::label_*() functions for axis formatting