--- title: "mosaicresid vs base R mosaicplot() vs ggmosaic2" output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{mosaicresid vs base R mosaicplot() vs ggmosaic2} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ```{r, include = FALSE} knitr::opts_chunk$set(collapse = TRUE, comment = "#>") ``` ## 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: - **`dir`** (split direction override) -- implemented, matches base R's default alternating behavior when unset, and verified to correctly swap split roles when overridden. - **`type`** (pearson / deviance / Freeman-Tukey residuals) -- implemented using base R's own formulas (read directly from `graphics:::mosaicplot.default`), verified to match base R to floating-point precision for all three. - **`sort`** -- turned out not to be a real gap once examined. Base R needs `sort` because `x` is a fixed pre-built table; this package's `aes(x =, y =)` mapping *is* the permutation mechanism base R's `sort` provides after the fact -- swap which variable is `x` and which is `y` to get the same effect, with no separate parameter needed. ## 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.