ggpmisc (version 0.4.3)

stat_poly_line: Predicted line from model fit

Description

Predicted values and a confidence band are computed and, by default, plotted. stat_poly_line() behaves like stat_smooth except for supporting the use of y as explanatory variable in the model formula, fits the model with stats::lm() as default for method, irrespective of the number of observations. The fit can alternatively by done by any of the methods supported by stat_smooth, including method = "auto".

Usage

stat_poly_line(
  mapping = NULL,
  data = NULL,
  geom = "smooth",
  position = "identity",
  ...,
  method = "lm",
  formula = NULL,
  se = TRUE,
  n = 80,
  span = 0.75,
  fullrange = FALSE,
  level = 0.95,
  method.args = list(),
  na.rm = FALSE,
  orientation = NA,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

mapping

The aesthetic mapping, usually constructed with aes or 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

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. See layer for more details.

method

function or character If character, "lm", "rlm" and "rq" are accepted. If a function, it must have formal parameters formula and data and return a model fit object for which summary() and coefficients() are consistent with those for lm fits.

formula

a formula object. Using aesthetic names x and y instead of original variable names.

se

Display confidence interval around smooth? (`TRUE` by default, see `level` to control.)

n

Number of points at which to evaluate smoother.

span

Controls the amount of smoothing for the default loess smoother. Smaller numbers produce wigglier lines, larger numbers produce smoother lines. Only used with loess, i.e. when `method = "loess"`, or when `method = NULL` (the default) and there are fewer than 1,000 observations.

fullrange

Should the fit span the full range of the plot, or just the data?

level

Level of confidence interval to use (0.95 by default).

method.args

named list with additional arguments.

na.rm

a logical indicating whether NA values should be stripped before the computation proceeds.

orientation

character Either "x" or "y" controlling the default for formula.

show.legend

logical. Should this layer be included in the legends? NA, the default, includes if any aesthetics are mapped. FALSE never includes, and TRUE 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 value returned by the statistic is a data frame, that will have n rows of predicted values and and their confidence limits.

Computed variables

`stat_poly_line()` provides the following variables, some of which depend on the orientation:

y *or* x

predicted value

ymin *or* xmin

lower pointwise confidence interval around the mean

ymax *or* xmax

upper pointwise confidence interval around the mean

se

standard error

Aesthetics

stat_poly_line understands x and y, to be referenced in the formula and weight passed as argument to parameter weights. All three must be mapped to numeric variables. In addition, the aesthetics understood by the geom ("geom_smooth" is the default) are understood and grouping respected.

Details

This statistic is just stat_smooth with different defaults and updated so that it interprets the argument passed to formula differently, accepting y as explanatory variable and setting orientation automatically. In addition the default for method is "lm", matching the default used in stat_poly_line(), stat_quant_line() and stat_quant_eq(). It calls StatSmooth to build a layer.

geom_smooth, which is used by default, treats each axis differently and can thus have two orientations. The orientation is easy to deduce from the argument passed to formula. Thus, stat_poly_line() will by default guess which orientation the layer should have. If no argument is passed to formula, the orientation is ambiguous. In that case the orientation can be specified directly passing an argument to the orientation parameter, which can be either "x" or "y". The value gives the axis that is taken as the explanatory variable, "x" being the default orientation you would expect for the geom. Package 'ggpmisc' does not define new geometries matching the new statistics as they are not needed and conceptually transformations of data are expressed as statistics.

See Also

Other ggplot statistics for linear and polynomial regression: stat_poly_eq()

Examples

# NOT RUN {
ggplot(mpg, aes(displ, hwy)) +
  geom_point() +
  stat_poly_line()

ggplot(mpg, aes(displ, hwy)) +
  geom_point() +
  stat_poly_line(formula = x ~ y)

ggplot(mpg, aes(displ, hwy)) +
  geom_point() +
  stat_poly_line(formula = y ~ poly(x, 3))

ggplot(mpg, aes(displ, hwy)) +
  geom_point() +
  stat_poly_line(formula = x ~ poly(y, 3))

# The default behavior of geom_smooth()
ggplot(mpg, aes(displ, hwy)) +
  geom_point() +
  stat_poly_line(method = "auto")

# Use span to control the "wiggliness" of the default loess smoother.
# The span is the fraction of points used to fit each local regression:
# small numbers make a wigglier curve, larger numbers make a smoother curve.
ggplot(mpg, aes(displ, hwy)) +
  geom_point() +
  stat_poly_line(method = "loess", span = 0.3)

ggplot(mpg, aes(displ, hwy)) +
  geom_point() +
  stat_poly_line(method = lm, formula = y ~ splines::bs(x, 3), se = FALSE)

ggplot(mpg, aes(displ, hwy)) +
  geom_point() +
  stat_poly_line(method = lm, formula = x ~ splines::bs(y, 3), se = FALSE)

# Smooths are automatically fit to each group (defined by categorical
# aesthetics or the group aesthetic) and for each facet.

ggplot(mpg, aes(displ, hwy, colour = class)) +
  geom_point() +
  stat_poly_line(se = FALSE)

ggplot(mpg, aes(displ, hwy)) +
  geom_point() +
  stat_poly_line(method = "auto", span = 0.8) +
  facet_wrap(~drv)

# }