stat_fit_glance
fits a model and returns a "tidy" version
of the model's fit, using 'glance()
methods from packages 'broom',
'broom.mixed', or other sources.
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 data set - only needed if you want to override the plot defaults.
- geom
The geometric object to use display the data
- position
The position adjustment to use for overlapping points on this layer
- ...
other arguments passed on to
layer
. This can include aesthetics whose values you want to set, not map. Seelayer
for more details.- method
character or function.
- method.args, glance.args
list of arguments to pass to
method
and to [generics::glance()], respectively.- n.min
integer Minimum number of distinct values in the explanatory variable (on the rhs of formula) for fitting to the attempted.
- label.x, label.y
numeric
with range 0..1 "normalized parent coordinates" (npc units) or character if usinggeom_text_npc()
orgeom_label_npc()
. If usinggeom_text()
orgeom_label()
numeric in native data units. If too short they will be recycled.- hstep, vstep
numeric in npc units, the horizontal and vertical step used between labels for different groups.
- na.rm
a 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
.
Value
The output of the glance()
methods is returned almost as is in
the data
object, as a data frame. The names of the columns in the
returned data are consistent with those returned by method glance()
from package 'broom', that will frequently differ from the name of values
returned by the print methods corresponding to the fit or test function
used. To explore the values returned by this statistic including the name
of variables/columns, which vary depending on the model fitting function
and model formula we suggest the use of
geom_debug
. An example is shown below.
Details
stat_fit_glance
together with stat_fit_tidy
and
stat_fit_augment
, based on package 'broom' can be used with a
broad range of model fitting functions as supported at any given time by
package '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
Although arguments passed to parameter glance.args
will be
passed to [generics::glance()] whether they are silently ignored or obeyed
depends on each specialization of [glance()], so do carefully read the
documentation for the version of [glance()] 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_glance
applies the function
given by method
separately to each group of observations, and
factors mapped to aesthetics, including x
and y
, create a
separate group for each factor level. Because of this,
stat_fit_glance
is not useful for annotating plots with results from
t.test()
, ANOVA or ANCOVA. In such cases use the
stat_fit_tb()
statistic which applies the model fitting per panel.
Model formula required
The current implementation works only with
methods that accept a formula as argument and which have a data
parameter through which a data frame can be passed. For example,
lm()
should be used with the formula interface, as the evaluation of
x
and y
needs to be delayed until the internal data
object of the ggplot is available. With some methods like
stats::cor.test()
the data embedded in the "ggplot"
object
cannot be automatically passed as argument for the data
parameter of
the test or model fit function. Please, for annotations based on
stats::cor.test()
use stat_correlation()
.
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_augment()
,
stat_fit_deviations()
,
stat_fit_residuals()
,
stat_fit_tb()
,
stat_fit_tidy()
Examples
# package 'broom' needs to be installed to run these examples
broom.installed <- requireNamespace("broom", quietly = TRUE)
gginnards.installed <- requireNamespace("gginnards", quietly = TRUE)
if (broom.installed) {
library(broom)
library(quantreg)
}
if (gginnards.installed) {
library(gginnards)
}
# Inspecting the returned data using geom_debug()
if (broom.installed && gginnards.installed) {
ggplot(mtcars, aes(x = disp, y = mpg)) +
stat_smooth(method = "lm") +
geom_point(aes(colour = factor(cyl))) +
stat_fit_glance(method = "lm",
method.args = list(formula = y ~ x),
geom = "debug")
}
#> `geom_smooth()` using formula = 'y ~ x'
#> [1] "PANEL 1; group(s) -1; 'draw_function()' input 'data' (head):"
#> npcx npcy r.squared adj.r.squared sigma statistic p.value df
#> 1 NA NA 0.7183433 0.7089548 3.251454 76.51266 9.380327e-10 1
#> logLik AIC BIC deviance df.residual nobs fm.class fm.method
#> 1 -82.10469 170.2094 174.6066 317.1587 30 32 lm lm
#> fm.formula fm.formula.chr x y PANEL group
#> 1 y ~ x y ~ x 91.145 32.725 1 -1
if (broom.installed)
# Regression by panel example
ggplot(mtcars, aes(x = disp, y = mpg)) +
stat_smooth(method = "lm", formula = y ~ x) +
geom_point(aes(colour = factor(cyl))) +
stat_fit_glance(method = "lm",
label.y = "bottom",
method.args = list(formula = y ~ x),
mapping = aes(label = sprintf('italic(r)^2~"="~%.3f~~italic(P)~"="~%.2g',
after_stat(r.squared), after_stat(p.value))),
parse = TRUE)
# Regression by group example
if (broom.installed)
ggplot(mtcars, aes(x = disp, y = mpg, colour = factor(cyl))) +
stat_smooth(method = "lm") +
geom_point() +
stat_fit_glance(method = "lm",
label.y = "bottom",
method.args = list(formula = y ~ x),
mapping = aes(label = sprintf('r^2~"="~%.3f~~italic(P)~"="~%.2g',
after_stat(r.squared), after_stat(p.value))),
parse = TRUE)
#> `geom_smooth()` using formula = 'y ~ x'
# Weighted regression example
if (broom.installed)
ggplot(mtcars, aes(x = disp, y = mpg, weight = cyl)) +
stat_smooth(method = "lm") +
geom_point(aes(colour = factor(cyl))) +
stat_fit_glance(method = "lm",
label.y = "bottom",
method.args = list(formula = y ~ x, weights = quote(weight)),
mapping = aes(label = sprintf('r^2~"="~%.3f~~italic(P)~"="~%.2g',
after_stat(r.squared), after_stat(p.value))),
parse = TRUE)
#> `geom_smooth()` using formula = 'y ~ x'
# correlation test
if (broom.installed)
ggplot(mtcars, aes(x = disp, y = mpg)) +
geom_point() +
stat_fit_glance(method = "cor.test",
label.y = "bottom",
method.args = list(formula = ~ x + y),
mapping = aes(label = sprintf('r[Pearson]~"="~%.3f~~italic(P)~"="~%.2g',
after_stat(estimate), after_stat(p.value))),
parse = TRUE)
#> 'formula' extracted from arguments
if (broom.installed)
ggplot(mtcars, aes(x = disp, y = mpg)) +
geom_point() +
stat_fit_glance(method = "cor.test",
label.y = "bottom",
method.args = list(formula = ~ x + y, method = "spearman", exact = FALSE),
mapping = aes(label = sprintf('r[Spearman]~"="~%.3f~~italic(P)~"="~%.2g',
after_stat(estimate), after_stat(p.value))),
parse = TRUE)
#> 'formula' extracted from arguments
# Quantile regression by group example
if (broom.installed)
ggplot(mtcars, aes(x = disp, y = mpg)) +
stat_smooth(method = "lm") +
geom_point() +
stat_fit_glance(method = "rq",
label.y = "bottom",
method.args = list(formula = y ~ x),
mapping = aes(label = sprintf('AIC = %.3g, BIC = %.3g',
after_stat(AIC), after_stat(BIC))))
#> `geom_smooth()` using formula = 'y ~ x'
#> Warning: Solution may be nonunique