stat_fit_augment
fits a model and returns a "tidy"
version of the model's data with prediction added, using 'augmnent()
methods from packages 'broom', 'broom.mixed', or other sources. The
prediction can be added to the plot as a curve.
Arguments
- mapping
The aesthetic mapping, usually constructed with
aes
. Only needs to be set at the layer level if you are overriding the plot defaults.- data
A layer specific dataset - only needed if you want to override the plot defaults.
- geom
The geometric object to use display the data
- method
character or function.
- method.args, augment.args
list of arguments to pass to
method
and to tobroom::augment
.- n.min
integer Minimum number of distinct values in the explanatory variable (on the rhs of formula) for fitting to the attempted.
- level
numeric Level of confidence interval to use (0.95 by default)
- y.out
character (or numeric) index to column to return as
y
.- position
The position adjustment to use for overlapping points on this layer
- na.rm
logical indicating whether NA values should be stripped before the computation proceeds.
- show.legend
logical. Should this layer be included in the legends?
NA
, the default, includes if any aesthetics are mapped.FALSE
never includes, andTRUE
always includes.- inherit.aes
If
FALSE
, overrides the default aesthetics, rather than combining with them. This is most useful for helper functions that define both data and aesthetics and shouldn't inherit behaviour from the default plot specification, e.g.borders
.- ...
other arguments passed on to
layer
. This can include aesthetics whose values you want to set, not map. Seelayer
for more details.
Details
stat_fit_augment
together with stat_fit_glance
and stat_fit_tidy
, based on package 'broom' can be used
with a broad range of model fitting functions as supported at any given
time by 'broom'. In contrast to stat_poly_eq
which can
generate text or expression labels automatically, for these functions the
mapping of aesthetic label
needs to be explicitly supplied in the
call, and labels built on the fly.
A ggplot statistic receives as data a data frame that is not the one passed
as argument by the user, but instead a data frame with the variables mapped
to aesthetics. In other words, it respects the grammar of graphics and
consequently within arguments passed through method.args
names of
aesthetics like $x$ and $y$ should be used instead of the original variable
names, while data is automatically passed the data frame. This helps ensure
that the model is fitted to the same data as plotted in other layers.
Note
The statistic stat_fit_augment
can be used only with
methods
that accept formulas under any formal parameter name and a
data
argument. Use ggplot2::stat_smooth()
instead of
stat_fit_augment
in production code if the additional features are
not needed.
Although arguments passed to parameter augment.args
will be
passed to [generics::augment()] whether they are silently ignored or obeyed
depends on each specialization of [augment()], so do carefully read the
documentation for the version of [augment()] corresponding to the `method`
used to fit the model.
Warning!
Not all `glance()` methods are defined in package 'broom'. `glance()` specializations for mixed models fits of classes `lme`, `nlme`, `lme4`, and many others are defined in package 'broom.mixed'.
Handling of grouping
stat_fit_augment
applies the function
given by method
separately to each group of observations; in ggplot2
factors mapped to aesthetics generate a separate group for each level.
Because of this, stat_fit_augment
is not useful for annotating plots
with results from t.test()
or ANOVA or ANCOVA. In such cases use
instead stat_fit_tb()
which applies the model fitting per panel.
Computed variables
The output of augment()
is
returned as is, except for y
which is set based on y.out
and
y.observed
which preserves the y
returned by the
generics::augment
methods. This renaming is needed so that the geom
works as expected.
To explore the values returned by this statistic, which vary depending
on the model fitting function and model formula we suggest the use of
geom_debug
. An example is shown below.
See also
broom
and broom.mixed
for details on how
the tidying of the result of model fits is done.
Other ggplot statistics for model fits:
stat_fit_deviations()
,
stat_fit_glance()
,
stat_fit_residuals()
,
stat_fit_tb()
,
stat_fit_tidy()
Examples
# Package 'broom' needs to be installed to run these examples.
# We check availability before running them to avoid errors.
broom.installed <- requireNamespace("broom", quietly = TRUE)
gginnards.installed <- requireNamespace("gginnards", quietly = TRUE)
if (broom.installed) {
library(broom)
library(quantreg)
}
#> Loading required package: SparseM
# Inspecting the returned data using geom_debug()
if (gginnards.installed) {
library(gginnards)
}
# Regression by panel, inspecting data
if (broom.installed & gginnards.installed) {
ggplot(mtcars, aes(x = disp, y = mpg)) +
geom_point(aes(colour = factor(cyl))) +
stat_fit_augment(method = "lm",
method.args = list(formula = y ~ x),
geom = "debug",
summary.fun = colnames)
}
#> Warning: Ignoring unknown parameters: `summary.fun`
#> [1] "PANEL 1; group(s) -1; 'draw_function()' input 'data' (head):"
#> ymax ymin y x .fitted .resid .hat .sigma .cooksd
#> 1 NA NA 23.00544 160 23.00544 -2.005436 0.04175345 3.285085 0.008649080
#> 2 NA NA 23.00544 160 23.00544 -2.005436 0.04175345 3.285085 0.008649080
#> 3 NA NA 25.14862 108 25.14862 -2.348622 0.06287776 3.276208 0.018678646
#> 4 NA NA 18.96635 258 18.96635 2.433646 0.03281262 3.274958 0.009825376
#> 5 NA NA 14.76241 360 14.76241 3.937588 0.06634737 3.219297 0.055812097
#> 6 NA NA 20.32645 225 20.32645 -2.226453 0.03131875 3.280251 0.007824999
#> .std.resid y.observed t.value .se.fit fm.class fm.method fm.formula
#> 1 -0.6300752 21.0 2.042272 NA lm lm y ~ x
#> 2 -0.6300752 21.0 2.042272 NA lm lm y ~ x
#> 3 -0.7461691 22.8 2.042272 NA lm lm y ~ x
#> 4 0.7610697 21.4 2.042272 NA lm lm y ~ x
#> 5 1.2533143 18.7 2.042272 NA lm lm y ~ x
#> 6 -0.6957374 18.1 2.042272 NA lm lm y ~ x
#> fm.formula.chr PANEL group
#> 1 y ~ x 1 -1
#> 2 y ~ x 1 -1
#> 3 y ~ x 1 -1
#> 4 y ~ x 1 -1
#> 5 y ~ x 1 -1
#> 6 y ~ x 1 -1
# Regression by panel example
if (broom.installed)
ggplot(mtcars, aes(x = disp, y = mpg)) +
geom_point(aes(colour = factor(cyl))) +
stat_fit_augment(method = "lm",
method.args = list(formula = y ~ x))
# Residuals from regression by panel example
if (broom.installed)
ggplot(mtcars, aes(x = disp, y = mpg)) +
geom_hline(yintercept = 0, linetype = "dotted") +
stat_fit_augment(geom = "point",
method = "lm",
method.args = list(formula = y ~ x),
y.out = ".resid")
# Regression by group example
if (broom.installed)
ggplot(mtcars, aes(x = disp, y = mpg, colour = factor(cyl))) +
geom_point() +
stat_fit_augment(method = "lm",
method.args = list(formula = y ~ x))
# Residuals from regression by group example
if (broom.installed)
ggplot(mtcars, aes(x = disp, y = mpg, colour = factor(cyl))) +
geom_hline(yintercept = 0, linetype = "dotted") +
stat_fit_augment(geom = "point",
method.args = list(formula = y ~ x),
y.out = ".resid")
# Weighted regression example
if (broom.installed)
ggplot(mtcars, aes(x = disp, y = mpg, weight = cyl)) +
geom_point(aes(colour = factor(cyl))) +
stat_fit_augment(method = "lm",
method.args = list(formula = y ~ x,
weights = quote(weight)))
# Residuals from weighted regression example
if (broom.installed)
ggplot(mtcars, aes(x = disp, y = mpg, weight = cyl)) +
geom_hline(yintercept = 0, linetype = "dotted") +
stat_fit_augment(geom = "point",
method.args = list(formula = y ~ x,
weights = quote(weight)),
y.out = ".resid")
# Quantile regression
if (broom.installed)
ggplot(mtcars, aes(x = disp, y = mpg)) +
geom_point() +
stat_fit_augment(method = "rq")