+
+
+[](https://github.com/saundersg/Applr/actions/workflows/R-CMD-check.yaml)
+[](https://cran.r-project.org/package=Applr)
+
+
+## Overview
A small R package for visualizing linear models. Plots anything from
simple lines to high-dimensional squiggles all with the same functions.
@@ -45,7 +58,7 @@ library(Applr)
## Quick start
-```{r quickstart-autoplot, results = "hide", fig.keep = "first", fig.show = "hold", fig.alt = "autoplot() of an lm: scatter plot with the fitted slice line"}
+```{r quickstart-autoplot, results = "hide", fig.keep = "first", fig.show = "hold", fig.alt = "autoplot() of lm(mpg ~ qsec + am): mpg against qsec, one slice line with a confidence ribbon per am value"}
library(Applr)
# One call: scatter + fitted line + label from any lm()
@@ -76,7 +89,7 @@ other statistics (override with `summary = FALSE`).
The result is a regular ggplot you can extend with `mapping` and `+` as usual.
-```{r autoplot, fig.alt = "autoplot() with a confidence interval and a custom title"}
+```{r autoplot, fig.alt = "autoplot() of an iris model: Petal.Length against Sepal.Length with a curved slice and confidence ribbon per Species, and the model equation as subtitle"}
autoplot(lm(Petal.Length ~ Sepal.Length + I(Sepal.Length^2):Species, iris))
```
@@ -89,7 +102,7 @@ aesthetics such as `color`. Everything else in `...` is passed on to
`geom_slice()` or `geom_slice_subtitle()`. Pass `interval = "prediction"`
for the wider ribbon, or `interval = "none"` for a bare line.
-```{r autoplot-mapping, results = "hide", fig.alt = "autoplot() with an x-axis override and a color mapping"}
+```{r autoplot-mapping, results = "hide", fig.alt = c("autoplot() of hwy against displ, colored by cyl and faceted by drv", "The same model with cyl on the x-axis, colored by drv, as bare lines without ribbons")}
model <- lm(hwy ~ displ + drv + cyl, data = mpg)
# Change the defaults like a normal ggplot; it will still infer the rest
@@ -143,7 +156,7 @@ In this example, the fitted model with 4 predictors can't be plotted as a
line without making multiple assumptions. The console messages clarify the
decisions it HAD to make in order to plot the 2d slice.
-```{r minimal, message = TRUE, fig.show = "hold", out.width = "49%", fig.width = 4, fig.height = 3.2, fig.alt = "geom_slice() base functionality with few assumptions made"}
+```{r minimal, message = TRUE, fig.show = "hold", out.width = "49%", fig.width = 4, fig.height = 3.2, fig.alt = c("A single slice of a four-predictor model through scattered points, with the other predictors imputed", "The same model plotted against its full linear predictor, with every point on the line")}
set.seed(123)
n <- 80
x <- runif(n, 0.1, 10)
@@ -172,7 +185,7 @@ Those assumptions had to be made, but you can make better ones.
This plot shows the same model far clearer by utilizing several features
`geom_slice()` offers.
-```{r geom-slice, fig.alt = "geom_slice() drawing the model's line using color, facet, band, and predict_vars"}
+```{r geom-slice, fig.alt = "The four-predictor model as projection bands over x2 from 0 to 10, one color per x3 value, faceted by x4, with every point inside its band"}
ggplot(dat, aes(x, y, color = factor(x3))) +
geom_point() +
geom_slice(model, band = "x2", predict_vars = list(x2 = c(0, 10))) +
@@ -186,7 +199,7 @@ ggplot(dat, aes(x, y, color = factor(x3))) +
Give a variable several values to draw one line per value; several
multi-value variables are crossed:
-```{r predict-vars, fig.alt = "Three slice lines of the same model, one per hp value"}
+```{r predict-vars, fig.alt = "Three labeled slice lines of Sepal.Length against Petal.Length, one per Sepal.Width value of 2, 3, and 4, with confidence ribbons"}
model <- lm(Sepal.Length ~ Sepal.Width + Petal.Length, iris)
ggplot(iris, aes(Petal.Length, Sepal.Length)) +
@@ -204,7 +217,7 @@ ggplot(iris, aes(Petal.Length, Sepal.Length)) +
`interval = "confidence"` or `"prediction"` adds the corresponding
`predict.lm()` ribbon around the line:
-```{r interval, fig.show = "hold", out.width = "49%", fig.width = 4, fig.height = 3.2, fig.alt = "Slice line with a prediction-interval ribbon"}
+```{r interval, fig.show = "hold", out.width = "49%", fig.width = 4, fig.height = 3.2, fig.alt = c("Quadratic slice of hwy against displ with a confidence ribbon", "The same slice with a wider prediction ribbon")}
model <- lm(hwy ~ displ + I(displ^2) + displ, data = mpg)
ggplot(mpg, aes(displ, hwy)) +
@@ -226,7 +239,7 @@ make a decision about what the band should project over. `band = "variable"`
spans that predictor between the values you gave in `predict_vars`, or its
observed data range when `predict_vars` leaves it out:
-```{r band, fig.alt = "Projection band spanning hp from 66 to 335"}
+```{r band, fig.alt = c("One projection band per drv spanning cyl from 4 to 8, labeled at each edge", "One projection band per drv spanning cyl from 5 to 7, labeled at each edge")}
model <- lm(hwy ~ displ * drv + cyl, data = mpg)
# Projection band infered using the min and max of an unused variable
@@ -254,7 +267,7 @@ shows raw `y`, predictions are back-transformed automatically to match the
y-axis (a message says so). Use `back_transform = FALSE` to turn this off, or
pass a function/name (`exp`, `"log10"`, ...) to override the auto-detection.
-```{r back-transform, fig.show = "hold", out.width = "33%", fig.width = 2.5, fig.height = 3.2, fig.alt = "Back-transformed slice of a log-response model on the raw mpg axis"}
+```{r back-transform, fig.show = "hold", out.width = "33%", fig.width = 2.5, fig.height = 3.2, fig.alt = c("A log(mpg) model back-transformed onto a raw mpg axis", "The same model on a log(mpg) axis", "The same model on a scale_y_log10() axis")}
model <- lm(log(mpg) ~ disp + hp, data = mtcars)
ggplot(mtcars, aes(disp, mpg)) +
@@ -280,7 +293,7 @@ Each group's line normally stops at its own data range. `full_range = TRUE`
extends every line to the edge of the panel instead (like `fullrange` in
`geom_smooth()`):
-```{r grouping, fig.show = "hold", out.width = "49%", fig.width = 4, fig.height = 3.2, fig.alt = "One slice line per drv group, colored to match the points"}
+```{r grouping, fig.show = "hold", out.width = "49%", fig.width = 4, fig.height = 3.2, fig.alt = c("One curved slice per drv group, each ending at its group's data range", "The same slices extended across the full panel with full_range = TRUE")}
model <- lm(hwy ~ displ + I(displ^2) + displ:drv, data = mpg)
# One slice per drv group, capped at the end of each group
@@ -305,7 +318,7 @@ no model or `predict_vars` — everything is borrowed from the plot's existing
Writes a label at the end of each slice line; especially useful when `band`
or multiple `predict_vars` are specified.
-```{r slice-text-band, fig.alt = ""}
+```{r slice-text-band, fig.alt = "Projection band over Sepal.Width with each edge labeled by its value"}
model <- lm(Sepal.Length ~ Sepal.Width + Petal.Length, iris)
ggplot(iris, aes(Petal.Length, Sepal.Length)) +
@@ -314,7 +327,7 @@ ggplot(iris, aes(Petal.Length, Sepal.Length)) +
geom_slice_text()
```
-```{r slice-text-color, fig.width = 7.5, fig.alt = "Slice lines labeled at their right ends"}
+```{r slice-text-color, fig.width = 7.5, fig.alt = "Three slice lines per group g, labeled at their right ends with their x2 value in the group's color"}
set.seed(123)
n <- 80
@@ -332,7 +345,7 @@ ggplot(dat, aes(x, y, color = g)) +
geom_slice_text()
```
-```{r slice-text-multiple, fig.width = 7.5, fig.alt = "geom_slice_text plots labels with multiple predictors"}
+```{r slice-text-multiple, fig.width = 7.5, fig.alt = "Six slice lines, one per combination of x2 and g, each labeled with both values at its right end"}
# Multiple predictors represent one line
ggplot(dat, aes(x, y)) +
geom_point(alpha = 0.5) +
@@ -340,7 +353,7 @@ ggplot(dat, aes(x, y)) +
geom_slice_text()
```
-```{r slice-text-legend, fig.width = 7.5, fig.alt = "geom_slice_text labels multiple predictors with the 'legend' style"}
+```{r slice-text-legend, fig.width = 7.5, fig.alt = "The same six slice lines with bare-value labels and a corner key naming x2 and g"}
# Identical, with `style = "legend"`
ggplot(dat, aes(x, y)) +
geom_point(alpha = 0.5) +
@@ -358,7 +371,7 @@ Fill the plot subtitle (or caption) with the model equation and the held
values the plot does not otherwise show — values already labeled by the
legend, facets, or `geom_slice_text()` are skipped:
-```{r slice-subtitle, fig.alt = "Plot whose subtitle shows the model equation and the held hp value"}
+```{r slice-subtitle, fig.alt = "Curved slices per iris Species with confidence ribbons; the subtitle shows the model equation and the held Sepal.Width value"}
model <- lm(Petal.Length ~ Sepal.Length + I(Sepal.Length^2):Species + Sepal.Width, iris)
ggplot(iris, aes(Sepal.Length, Petal.Length, color = Species)) +
@@ -386,7 +399,7 @@ Create a new base-R plot showing a 2-D slice of a linear model. Unspecified
values are held at sensible defaults (numeric → mean, factor → first level)
and reported in the caption.
-```{r slice-2d, fig.keep = "first", fig.show = "hold", fig.alt = "Base-R slice plot with held values reported in the caption"}
+```{r slice-2d, fig.keep = "first", fig.show = "hold", fig.alt = "Base-R plot of mpg against disp with the back-transformed slice line and the held hp value in the caption"}
model <- lm(log(mpg) ~ disp + hp, data = mtcars)
slice_2d(model)
#--or--
@@ -398,7 +411,7 @@ slice_2d(model, x_axis = "hp", disp = 250, n = 150, col = "blue", lwd = 2)
Add a 2-D slice line to an *existing* base-R plot. X and Y axis variables
must match the plot it is being added to.
-```{r add-slice-2d, fig.keep = "last", fig.alt = "Two slice lines added to an existing base-R plot"}
+```{r add-slice-2d, fig.keep = "last", fig.alt = "Base-R scatter of mpg against disp with added slices at the lowest hp (blue) and highest hp (red, dashed)"}
model <- lm(log(mpg) ~ disp + hp, data = mtcars)
plot(mpg ~ disp, data = mtcars)
add_slice_2d(model)
@@ -492,9 +505,9 @@ Enjoy clearer model visualizations with **Applr**!
## Attributions
-Thanks to **Cameron McClellan** for his vision and initiation, **James Beeson** for seeing it through, **Anthropic's Claude** for solving the problems we couldn't, and **Brother Saunders** - our teacher and inspiration to do great things.
+Thanks to **Cameron McClellan** for his vision and initiation, **James Beeson** for seeing it through, **Anthropic's Claude** for solving the coding problems we couldn't, and **Brother Garrett Saunders** - our teacher and inspiration to do great things.
And of course, Brigham Young University Idaho - our alma mater; the school we love and cherish. And the God of Heaven and Earth, who gives us all.
-33 For God is not the author of *confusion*, but of *peace*, as in all churches of the saints.
-- 1 Corinthians 14:33
+> "For God is not the author of *confusion*, but of *peace*, as in all churches of the saints."
+> - 1 Corinthians 14:33
diff --git a/README.md b/README.md
index 59b59b8..4b996b7 100644
--- a/README.md
+++ b/README.md
@@ -2,7 +2,15 @@
-# Applr
+# Applr 
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Applr Test Suite
-2026-08-19 16:47
+2026-10-13 16:04
@@ -2813,7 +2813,7 @@Show
gs_38_multi_value_cross_colored
geom_point() + geom_slice(model)Output (this run):
-
Reference (ground truth):
lm_equation
le_01_single_predictor
Expect: “y =
+3 significant figures (the exact fit’s floating-point intercept is +zapped to 0).+ 1*x” with coefficients to -3 significant figures (intercept ~0 in scientific notation is fine).
Status: OK
# CASE: le_01_single_predictor
# TYPE: console
# FUNC: lm_equation
# EXPECT: "y = <intercept> + 1*x" with coefficients to 3 significant figures
-# (intercept ~0 in scientific notation is fine).
+# (the exact fit's floating-point intercept is zapped to 0).
source("tests/_setup.R")
set.seed(123)
@@ -7165,7 +7166,7 @@ le_01_single_predictor
try_show(lm_equation(model))No plot produced by this run (expected for error cases).
Console output (this run):
-[1] "y = 6.28e-17 + 1*x"[1] "y = 0 + 1*x"le_02_additive
@@ -7191,7 +7192,7 @@le_02_additive
try_show(lm_equation(model))No plot produced by this run (expected for error cases).
Console output (this run):
-[1] "y = -3.39e-15 + 1*x + 1*x_pos"[1] "y = 0 + 1*x + 1*x_pos"le_03_multiplicative
@@ -7217,7 +7218,7 @@le_03_multiplicative
try_show(lm_equation(model))No plot produced by this run (expected for error cases).
Console output (this run):
-[1] "y = -1.51e-15 + 1*I(x * x_pos)"[1] "y = 0 + 1*I(x * x_pos)"le_04_interaction
@@ -7243,7 +7244,7 @@le_04_interaction
try_show(lm_equation(model))No plot produced by this run (expected for error cases).
Console output (this run):
-[1] "y = -2.51e-16 + 1*x:x_switch"[1] "y = 0 + 1*x:x_switch"le_05_quadratic
@@ -7268,7 +7269,7 @@le_05_quadratic
try_show(lm_equation(model))No plot produced by this run (expected for error cases).
Console output (this run):
-[1] "y = 8.29e-15 + 1*x + 1*I(x^2)"[1] "y = 0 + 1*x + 1*I(x^2)"le_06_ytransform_inverse
@@ -7293,7 +7294,7 @@le_06_ytransform_inverse
try_show(lm_equation(model))No plot produced by this run (expected for error cases).
Console output (this run):
-[1] "1/y = 6.28e-17 + 1*x"[1] "1/y = 0 + 1*x"le_07_ytransform_sqrt
@@ -7319,7 +7320,7 @@le_07_ytransform_sqrt
try_show(lm_equation(model))No plot produced by this run (expected for error cases).
Console output (this run):
-[1] "sqrt(y) = 2.01e-15 + 1*x_pos"[1] "sqrt(y) = 0 + 1*x_pos"le_08_ytransform_log
@@ -7345,7 +7346,7 @@le_08_ytransform_log
try_show(lm_equation(model))No plot produced by this run (expected for error cases).
Console output (this run):
-[1] "log(y) = 2.01e-15 + 1*x_pos"[1] "log(y) = 0 + 1*x_pos"le_09_ytransform_exp
@@ -7371,7 +7372,7 @@le_09_ytransform_exp
try_show(lm_equation(model))No plot produced by this run (expected for error cases).
Console output (this run):
-[1] "exp(y) = 2.01e-15 + 1*x_pos"[1] "exp(y) = 0 + 1*x_pos"le_10_ytransform_square
@@ -7397,7 +7398,7 @@le_10_ytransform_square
try_show(lm_equation(model))No plot produced by this run (expected for error cases).
Console output (this run):
-[1] "y^2 = 2.01e-15 + 1*x_pos"[1] "y^2 = 0 + 1*x_pos"le_11_mtcars_log
@@ -7671,8 +7672,8 @@ap_01_single_predictor
Expect: Complete plot built by autoplot(model) alone: mtcars scatter (disp on x, mpg on y), one straight downward-sloping slice line through the point cloud with its default -confidence ribbon (a narrow shaded band hugging the line), theme_lc -styling. No errors, warnings, or imputation messages.
+confidence ribbon (a narrow shaded band hugging the line). No errors, +warnings, or imputation messages.Status: OK
# CASE: ap_01_single_predictor
@@ -7681,7 +7682,7 @@ ap_01_single_predictor
# EXPECT: Complete plot built by autoplot(model) alone: mtcars scatter
# (disp on x, mpg on y), one straight downward-sloping slice line
# through the point cloud with its default confidence ribbon (a
-# narrow shaded band hugging the line), theme_lc styling.
+# narrow shaded band hugging the line).
# No errors, warnings, or imputation messages.
source("tests/_setup.R")
diff --git a/tests/testthat/test-deprecated.R b/tests/testthat/test-deprecated.R
new file mode 100644
index 0000000..4f8c43f
--- /dev/null
+++ b/tests/testthat/test-deprecated.R
@@ -0,0 +1,10 @@
+test_that("geom_fit() is removed and points to geom_slice()", {
+ expect_error(geom_fit(), "geom_slice")
+})
+
+test_that("drawit() warns and still draws", {
+ grDevices::pdf(NULL)
+ on.exit(grDevices::dev.off(), add = TRUE)
+ m <- lm(mpg ~ disp, data = mtcars)
+ expect_warning(drawit(m, xaxis = "disp"))
+})
diff --git a/tests/testthat/test-geom_slice.R b/tests/testthat/test-geom_slice.R
new file mode 100644
index 0000000..d51731a
--- /dev/null
+++ b/tests/testthat/test-geom_slice.R
@@ -0,0 +1,42 @@
+build_layer <- function(p, i = 1) ggplot2::ggplot_build(p)$data[[i]]
+
+m_simple <- lm(mpg ~ disp, data = mtcars)
+m_two <- lm(mpg ~ disp + hp, data = mtcars)
+base <- ggplot2::ggplot(mtcars, ggplot2::aes(disp, mpg))
+
+test_that("geom_slice() returns a ggplot2 layer", {
+ expect_s3_class(geom_slice(m_simple), "Layer")
+})
+
+test_that("the slice matches predict() across the data range", {
+ d <- build_layer(base + geom_slice(m_simple))
+ expect_equal(nrow(d), 100)
+ expect_equal(range(d$x), range(mtcars$disp))
+ expect_equal(d$y, unname(predict(m_simple, data.frame(disp = d$x))))
+})
+
+test_that("predict_vars holds other predictors at the given value", {
+ d <- build_layer(base + geom_slice(m_two, predict_vars = list(hp = 150)))
+ expect_equal(d$y, unname(predict(m_two, data.frame(disp = d$x, hp = 150))))
+})
+
+test_that("multiple predict_vars values draw one line each", {
+ d <- build_layer(base + geom_slice(m_two, predict_vars = list(hp = c(100, 200))))
+ expect_length(unique(d$group), 2)
+})
+
+test_that("interval = 'confidence' adds a band around the line", {
+ d <- build_layer(base + geom_slice(m_simple, interval = "confidence"))
+ expect_true(all(c("ymin", "ymax") %in% names(d)))
+ expect_true(all(d$ymin < d$y & d$y < d$ymax))
+})
+
+test_that("a log response is back-transformed to the plotted scale", {
+ m_log <- lm(log(mpg) ~ disp, data = mtcars)
+ expect_message(d <- build_layer(base + geom_slice(m_log)), "back-transformed")
+ expect_equal(d$y, unname(exp(predict(m_log, data.frame(disp = d$x)))))
+})
+
+test_that("geom_slice() rejects non-lm input", {
+ expect_error(ggplot2::ggplot_build(base + geom_slice("x")), "fitted by `lm\\(\\)`")
+})
diff --git a/tests/testthat/test-lm_equation.R b/tests/testthat/test-lm_equation.R
new file mode 100644
index 0000000..e582a5e
--- /dev/null
+++ b/tests/testthat/test-lm_equation.R
@@ -0,0 +1,27 @@
+m_simple <- lm(mpg ~ disp, data = mtcars)
+
+test_that("lm_equation() writes a plain-text equation", {
+ expect_identical(lm_equation(m_simple), "mpg = 29.6 - 0.0412*disp")
+ expect_identical(lm_equation(m_simple, style = "raw"), "mpg = 29.6 - 0.0412*disp")
+})
+
+test_that("lm_equation() keeps a transformed response on the left side", {
+ m_log <- lm(log(mpg) ~ disp, data = mtcars)
+ expect_identical(lm_equation(m_log), "log(mpg) = 3.45 - 0.00212*disp")
+})
+
+test_that("lm_equation() spells out factor levels", {
+ m_factor <- lm(mpg ~ disp + factor(cyl), data = mtcars)
+ eq <- lm_equation(m_factor)
+ expect_match(eq, "factor(cyl)=\"6\"", fixed = TRUE)
+ expect_match(eq, "factor(cyl)=\"8\"", fixed = TRUE)
+})
+
+test_that("lm_latex() returns display-math LaTeX", {
+ tex <- NULL
+ invisible(capture.output(tex <- lm_latex(m_simple)))
+ expect_type(tex, "character")
+ expect_match(tex, "^\\$\\$.*\\$\\$$")
+ expect_match(tex, "\\hat{Y_i}", fixed = TRUE)
+ expect_match(tex, "0.0412", fixed = TRUE)
+})
diff --git a/tests/testthat/test-plots.R b/tests/testthat/test-plots.R
new file mode 100644
index 0000000..dc86e5d
--- /dev/null
+++ b/tests/testthat/test-plots.R
@@ -0,0 +1,31 @@
+m_simple <- lm(mpg ~ disp, data = mtcars)
+m_two <- lm(mpg ~ disp + hp, data = mtcars)
+
+test_that("autoplot() builds a ggplot and summary = FALSE keeps it quiet", {
+ expect_silent(p <- ggplot2::autoplot(m_simple, summary = FALSE))
+ expect_s3_class(p, "ggplot")
+ expect_no_error(ggplot2::ggplot_build(p))
+})
+
+test_that("autoplot() prints the model summary by default", {
+ expect_output(ggplot2::autoplot(m_simple), "Residual standard error")
+})
+
+test_that("slice_2d() and add_slice_2d() draw in base graphics", {
+ grDevices::pdf(NULL)
+ on.exit(grDevices::dev.off(), add = TRUE)
+ expect_no_error(slice_2d(m_simple, x_axis = "disp"))
+ expect_no_error(slice_2d(m_simple, x_axis = "disp", interval = "confidence"))
+ plot(mpg ~ disp, data = mtcars)
+ expect_no_error(add_slice_2d(m_two, x_axis = "disp", hp = 100))
+})
+
+test_that("slice_2d() errors on an x_axis not in the model", {
+ grDevices::pdf(NULL)
+ on.exit(grDevices::dev.off(), add = TRUE)
+ expect_error(slice_2d(m_simple, x_axis = "nope"), "not found in the model")
+})
+
+test_that("scatter_3d() returns a plotly widget", {
+ expect_s3_class(scatter_3d(m_two), "plotly")
+})
diff --git a/vignettes/Applr.Rmd b/vignettes/Applr.Rmd
index 6c78dcb..f273fa8 100644
--- a/vignettes/Applr.Rmd
+++ b/vignettes/Applr.Rmd
@@ -17,120 +17,274 @@ knitr::opts_chunk$set(
```
A fitted linear model with more than one predictor lives in more dimensions
-than a scatterplot can show. The usual workaround — `geom_smooth(method =
-"lm")` — quietly fits a *different*, single-predictor model to the plotted
-variables, so the line on the screen is not the model you summarized.
+than a scatterplot can show. The usual workaround, `geom_smooth(method =
+"lm")`, quietly fits a *different*, simpler model to the plotted variables, so
+the line on the screen is not the model you summarized.
Applr draws the model you actually fit. Its core idea is the **slice**: hold
every predictor except one at a fixed value, and draw the model's predictions
-as that one predictor varies. This vignette walks through the workflow on a
-single dataset, `mtcars`.
+as that one predictor varies. Start by fitting an `lm()`, then hand it to
+Applr. Explore it with `autoplot()`, or present it with polish and
+fine-grained control using `geom_slice()`.
```{r setup, message = FALSE}
library(Applr)
library(ggplot2)
```
-## Fit a model, then autoplot() it
+## Explore with autoplot()
-Start with a model where `mpg` depends on two predictors:
+`autoplot()` on an `lm` builds the whole plot in one call: the model's own data
+as a scatter, a fitted slice line with its confidence ribbon, and a subtitle
+saying what the model is. It also prints `summary()` to the console, so you
+can refit, re-plot, and read the coefficients and R² in one step (turn this off
+with `summary = FALSE`).
```{r}
-model <- lm(mpg ~ disp + hp, data = mtcars)
-lm_equation(model)
+autoplot(lm(Petal.Length ~ Sepal.Length + I(Sepal.Length^2):Species, iris))
```
-`autoplot()` is the quickest way to see it. It rebuilds the scatterplot from
-the model's own data, picks the first numeric predictor for the x-axis, and
-adds a slice line with its confidence ribbon — plus a subtitle recording
-which values the other predictors were held at:
+`autoplot()` makes a few decisions for you. The model's first numeric
+predictor goes on the x-axis, and predictors that group into a few discrete
+values become `color`, then facets. Every decision can be overridden. Pass a
+`mapping` to change the defaults, just as you would with `ggplot()`; whatever
+you leave out is still inferred. Choose a different x-axis with
+`aes(x = ...)`. Arguments in `...` pass through to `geom_slice()`, so
+`interval = "prediction"` gives the wider ribbon and `interval = "none"` a
+bare line.
-```{r}
-autoplot(model)
-```
+```{r, results = "hide"}
+model <- lm(hwy ~ displ + drv + cyl, data = mpg)
-The message tells you what happened: `hp` was not on an axis, so the line
-holds it at its mean. Use `mapping = aes(x = ...)` to slice along a different
-predictor, and pass any `geom_slice()` argument through `...`:
+autoplot(model, aes(color = factor(cyl))) + facet_wrap(~drv)
-```{r}
-autoplot(model, mapping = aes(x = hp), interval = "prediction")
+autoplot(model,
+ aes(x = cyl, color = factor(drv)),
+ interval = "none") +
+ labs(title = "The Same Model From a Different Angle")
```
-## Build the plot yourself with geom_slice()
+The result is an ordinary ggplot, so `+` works as usual.
+
+## Present with geom_slice()
+
+`geom_slice()` is the layer underneath `autoplot()`. It looks like
+`geom_smooth()`, but where `geom_smooth()` fits its own model to the plotted
+data, `geom_slice()` draws the model *you* fitted, reading the plot's `aes()`
+to learn which predictor is on the x-axis. Unlike `autoplot()`, it makes as
+few decisions as it can.
+
+Once a model has more than one predictor, each line is a 2-D slice through it.
+Every predictor not on the x-axis has to be held at some value, and
+`geom_slice()` fills those values in this order:
+
+- Variables named in `predict_vars` are held at your chosen values.
+- Variables mapped to a grouping aesthetic (`aes(color = g)`) are held at each
+ group's value, giving one line per group.
+- Facet variables are held at each panel's value.
+- Anything left over is imputed (mean for numeric, most common value for
+ factors), with a console message naming the value used.
+
+The model below has four predictors and was fitted exactly, with no noise. A
+bare `geom_slice()` has to impute three of them, and the console messages
+report each choice:
+
+```{r, message = TRUE, fig.show = "hold", out.width = "49%", fig.width = 4, fig.height = 3.2}
+set.seed(123)
+n <- 80
+x <- runif(n, 0.1, 10)
+x2 <- runif(n, 0.1, 10)
+x3 <- sample(c(1, 20, 40), n, replace = TRUE)
+x4 <- sample(c(1, 2), n, replace = TRUE)
+y <- log(5 + x + x2 + x3 + 1/5 * x * x3 + 80 * x4) # no random noise
+dat <- data.frame(x, x2, x3, x4, y)
+
+model <- lm(exp(y) ~ x*x3 + x2 + x4, data = dat) # exact model fit
+
+ggplot(dat, aes(x, y)) +
+ geom_point() +
+ geom_slice(model) +
+ labs(title = "A Perfectly Fit Model 'Slice'")
+
+# The same model against its full linear predictor: an exact fit
+ggplot(dat, aes(x = log(5 + x + x2 + x3 + 1/5 * x * x3 + 80 * x4), y)) +
+ geom_point() +
+ geom_slice(model) +
+ labs(title = "Same Model, Different X-Axis")
+```
-For full control, add `geom_slice()` to an ordinary ggplot. The layer reads
-the plot's `aes()` to learn which predictor is on x, and predicts from your
-model — no separate model is fit:
+Notice that the response `exp(y)` was back-transformed onto the plotted `y`
+axis without being asked. Those imputations were forced, but you can do better.
+Map `x3` to color, facet by `x4`, and show the reach of `x2` as a band, and
+every line lands on its points:
```{r}
-ggplot(mtcars, aes(x = disp, y = mpg)) +
+ggplot(dat, aes(x, y, color = factor(x3))) +
geom_point() +
- geom_slice(model)
+ geom_slice(model, band = "x2", predict_vars = list(x2 = c(0, 10))) +
+ facet_wrap(~x4) +
+ geom_slice_text() +
+ geom_slice_subtitle()
```
-### Choosing the slice
+The rest of this vignette goes through those features one at a time.
-`predict_vars` pins the off-axis predictors to values you choose instead of
-their means. Give a predictor several values and you get one line per value —
-a small multiple of slices through the same model:
+### Choosing slices with predict_vars
+
+Give a variable several values in `predict_vars` to draw one line per value.
+Several multi-value variables are crossed.
```{r}
-ggplot(mtcars, aes(x = disp, y = mpg)) +
+model <- lm(Sepal.Length ~ Sepal.Width + Petal.Length, iris)
+
+ggplot(iris, aes(Petal.Length, Sepal.Length)) +
geom_point() +
- geom_slice(model, predict_vars = list(hp = c(66, 150, 335)))
+ geom_slice(
+ model,
+ predict_vars = list(Sepal.Width = c(2, 3, 4)),
+ interval = "confidence"
+ ) +
+ geom_slice_text()
```
-### Intervals
+### Confidence and prediction intervals
`interval = "confidence"` or `"prediction"` shades the corresponding
`predict.lm()` interval around each line:
+```{r, fig.show = "hold", out.width = "49%", fig.width = 4, fig.height = 3.2}
+model <- lm(hwy ~ displ + I(displ^2), data = mpg)
+
+ggplot(mpg, aes(displ, hwy)) +
+ geom_point() +
+ geom_slice(model, interval = "confidence") +
+ labs(title = "Confidence Interval")
+
+ggplot(mpg, aes(displ, hwy)) +
+ geom_point() +
+ geom_slice(model, interval = "prediction") +
+ labs(title = "Prediction Interval")
+```
+
+### Projection bands
+
+An interval shows uncertainty. A `band` shows the *reach of a predictor*: two
+edge slices with a translucent ribbon between them. `band = "variable"` spans
+that predictor between the values given in `predict_vars`, or across its
+observed range if `predict_vars` doesn't mention it. `band = TRUE` infers the
+variable when there is only one sensible choice.
+
```{r}
-ggplot(mtcars, aes(x = disp, y = mpg)) +
+model <- lm(hwy ~ displ * drv + cyl, data = mpg)
+
+# Inferred: cyl is the only predictor not shown, so it spans 4 to 8
+ggplot(mpg, aes(displ, hwy, color = drv)) +
+ geom_point() +
+ geom_slice(model, band = TRUE) +
+ geom_slice_text()
+
+# Specified: cyl from 5 to 7
+ggplot(mpg, aes(displ, hwy, color = drv)) +
geom_point() +
- geom_slice(model, predict_vars = list(hp = 150), interval = "prediction")
+ geom_slice(model, band = "cyl", predict_vars = list(cyl = c(5, 7))) +
+ geom_slice_text()
```
-## Labeling the slices
+`band` cannot be combined with `interval`.
-Three companion helpers describe the slices on the plot itself, so a reader
-can tell which line is which and what was held constant.
+### Transformed responses
-`geom_slice_text()` labels the end of each line with its held value;
-`geom_slice_caption()` writes the slice description under the plot:
+If the model's response is transformed but the plot shows something else,
+predictions are back-transformed to match the y-axis, and a console message
+says so. Turn this off with `back_transform = FALSE`, or pass a function or
+name (`exp`, `"log10"`, ...) to override the auto-detection.
-```{r}
-ggplot(mtcars, aes(x = disp, y = mpg)) +
+```{r, fig.show = "hold", out.width = "33%", fig.width = 2.5, fig.height = 3.2}
+model <- lm(log(mpg) ~ disp + hp, data = mtcars)
+
+ggplot(mtcars, aes(disp, mpg)) +
geom_point() +
- geom_slice(model, predict_vars = list(hp = c(66, 150, 335))) +
- geom_slice_text() +
- geom_slice_caption()
+ geom_slice(model) +
+ labs(title = "normal y axis")
+
+ggplot(mtcars, aes(disp, log(mpg))) +
+ geom_point() +
+ geom_slice(model) +
+ labs(title = "log() y axis")
+
+ggplot(mtcars, aes(disp, mpg)) +
+ geom_point() +
+ geom_slice(model) +
+ scale_y_log10() +
+ labs(title = "scale_y_log10() axis")
+```
+
+### Grouping: one line per group
+
+With a grouping aesthetic, each group gets its own slice, and each line stops
+at the end of its group's data. `full_range = TRUE` extends every line across
+the whole panel instead, like `fullrange` in `geom_smooth()`:
+
+```{r, fig.show = "hold", out.width = "49%", fig.width = 4, fig.height = 3.2}
+model <- lm(hwy ~ displ + I(displ^2) + displ:drv, data = mpg)
+
+ggplot(mpg, aes(displ, hwy, color = drv)) +
+ geom_point() +
+ geom_slice(model)
+
+ggplot(mpg, aes(displ, hwy, color = drv)) +
+ geom_point() +
+ geom_slice(model, full_range = TRUE)
```
-(`geom_slice_subtitle()` is the third helper — it puts the model equation and
-held values in the subtitle, and is what `autoplot()` uses by default.)
+## Labeling the slices
+
+Three companion layers describe the slices on the plot itself, so a reader can
+tell which line is which and what was held constant. They take no model; they
+read everything from the plot's `geom_slice()` layers, so add them *after*
+those layers.
-## Grouping and faceting
+`geom_slice_text()` labels the end of each line with the values that define
+it. It is most useful with bands and multi-value `predict_vars`:
+
+```{r, fig.width = 7.5}
+set.seed(123)
+n <- 80
+x <- runif(n, -10, 10)
+x2 <- runif(n, 0, 4)
+g <- factor(sample(c("A", "B"), n, replace = TRUE))
+y <- x * ifelse(g == "A", 0.5, 2) + ifelse(g == "A", 5, -5) + 4 * x2 + rnorm(n)
+dat <- data.frame(x, x2, g, y)
+model <- lm(y ~ x * g + x2, data = dat)
+
+ggplot(dat, aes(x, y)) +
+ geom_point(alpha = 0.5) +
+ geom_slice(model, predict_vars = list(x2 = c(0, 2, 4), g = c("A", "B"))) +
+ geom_slice_text(style = "legend")
+```
-Slices respect the plot's grouping and faceting. With a model that includes
-the grouping variable, each group gets its own correctly-sliced line:
+`geom_slice_subtitle()` (or `geom_slice_caption()`) writes the model equation
+and any held values that aren't already shown by the legend, facets, or
+`geom_slice_text()`. It indents the equation when there's room and compresses
+it when space is tight.
```{r}
-model_cyl <- lm(mpg ~ disp * cyl, data = mtcars)
+model <- lm(Petal.Length ~ Sepal.Length + I(Sepal.Length^2):Species + Sepal.Width, iris)
-ggplot(mtcars, aes(x = disp, y = mpg, color = factor(cyl))) +
+ggplot(iris, aes(Sepal.Length, Petal.Length, color = Species)) +
geom_point() +
- geom_slice(model_cyl)
+ geom_slice(model, interval = "confidence") +
+ geom_slice_subtitle()
```
## Where to go next
-- `?geom_slice` covers the remaining options: projection bands (`band`),
- extending lines across the panel (`full_range`), transformed responses and
- `back_transform`, and the `n` resolution of the line.
-- `?slice_2d` is the base-graphics equivalent of this whole workflow.
-- `?scatter_3d` (or `autoplot(model, type = "3d")`) shows a two-predictor
- model as an interactive 3-D surface instead of a slice.
+- `?geom_slice` documents every option, including `n`, the number of points
+ that make up each line.
+- `?geom_slice_text` and `?geom_slice_subtitle` cover label styles,
+ placement, and `prepend`/`append` text.
+- `?slice_2d` and `?add_slice_2d` draw the same slices in base graphics.
+- `?scatter_3d` (or `autoplot(model, type = "3d")`) shows a model with two
+ numeric predictors as an interactive 3-D surface.
- `?lm_equation` and `?lm_latex` turn the fitted model into text or LaTeX for
- reports.
+ reports, and `?diagnose` draws the standard residual plots.