mosaicresid vs base R mosaicplot() vs ggmosaic2

Why this document exists

This package set out to fill a real, verifiable gap: at the time this project started, no actively-maintained, CRAN-available package offered ggplot2-native mosaic plots with statistical (residual-based) shading. The original ggmosaic package had no shading support at all and was archived in late 2025. Base R’s mosaicplot(shade = TRUE) and the vcd/vcdExtra packages have shading, but are base-graphics, not grammar-of-graphics layers.

Partway through this project, a new package – ggmosaic2 (Michael Friendly, with the original ggmosaic authors credited as co-authors), published to CRAN on 2026-09-16 – closed much of that gap directly, including full n-way support. As a production recommendation today, ggmosaic2 is the more complete package. This document exists to be honest about that, and to state exactly what is and isn’t different about this package.

Feature-by-feature comparison

Base R mosaicplot() ggmosaic2 (CRAN) mosaicresid
Input pre-built table() only raw data + aes(x = product(...)) raw or pre-aggregated data, plain aes(x =, y =)
API idiom base graphics function call product()-wrapped ggplot2 aes plain ggplot2 aes, no wrapper
n-way support margin (loglinear model choice) full, via glm(poisson) + formula/shortcut expected = none – explicit 2-way scope cut (see below)
Residual types pearson / deviance / FT pearson only pearson / deviance / FT (matches base R exactly)
Split direction dir override divider (vspine/hspine/vbar/hbar – 4 options) dir override (v/h – 2 options, a subset of their 4)
Default color scale discrete HSV bins continuous scale_fill_gradient2() continuous scale_fill_gradient2() – same design choice, arrived at independently
Labels axis-side, fixed position ggrepel-based collision handling in-tile, size-threshold suppression
Composability none (base graphics) full ggplot2 (facets, themes, +) full ggplot2 (facets, themes, +)
Codebase 1 function, base R ~3,500 lines, 21 files, 9 imported packages ~800 lines, 13 files, 5 imported packages
Extras – facet_mosaic(), plotly export, Shiny app tidy intermediate output (compute_mosaic_residuals() returns an inspectable data frame)

Is aes(x =, y =) vs product() a real differentiator?

Yes, but as a trade-off, not an unqualified win.

ggplot2 only exposes two position-aesthetic slots. ggmosaic2’s product() exists specifically to pack an arbitrary-length variable list into the single x slot, so one interface scales from 1 variable up to n (plus conds for conditioning variables). mosaicresid’s plain aes(x =, y =) is more idiomatic – it reads like every other ggplot2 geom, with no wrapper function to learn – but that simplicity is purchased by being two-variable-only. It would not generalize past two variables without introducing something product()-shaped of its own.

Defending the one deliberate gap: n-way support

This is the only gap left unclosed by design, rather than by oversight. Past two variables, “expected count” stops having a single unambiguous definition – complete independence, joint independence, conditional independence, and all-two-way-associations are different, non-equivalent loglinear models, and the caller has to choose one. mosaicresid ships a narrow, well-defined two-way implementation, verified to floating-point precision against base R’s own residual formulas (see the package’s test suite, tests/testthat/test-residuals.R), with an explicit error that fails loudly rather than silently computing a plausible-looking but wrong number for an ambiguous n-way case – naming stats::loglin() and glm(family = poisson) as the path forward. ggmosaic2 ended up shipping exactly that glm(family = poisson) approach for its n-way support, which is a reasonable outside confirmation that the scoping judgment here was architecturally correct, even though this package doesn’t implement it.

Everything else: closed

Every other mechanical gap identified during development has been closed and verified:

Bottom line

ggmosaic2 is the more feature-complete package, and is the right choice for someone who needs n-way support, ggrepel-based label collision handling, or a Shiny app, in production, today. mosaicresid matches or exceeds it on the specific two-way, residual-shaded surface – all three residual types where ggmosaic2 has one, verified to base R’s own formulas to the last bit – with a simpler API and a fraction of the code, and remains a legitimate, from-scratch statement of what true mosaic-plot geometry and independence-residual shading look like as a ggplot2 layer.