Predicted values and a confidence band are computed and, by default, plotted.

## Usage

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

## 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

- 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" or the name of a model fit function are accepted, possibly followed by the fit function's

`method`

argument separated by a colon (e.g.`"rlm:M"`

). If a function different to`lm()`

, it must accept arguments named`formula`

,`data`

,`weights`

, and`method`

and return a model fit object of class`lm`

.- 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.)

- fm.values
logical Add R2, adjusted R2, p-value and n as columns to returned data? (`FALSE` by default.)

- n
Number of points at which to evaluate smoother.

- 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.

- n.min
integer Minimum number of distinct values in the explanatory variable (on the rhs of formula) for fitting to the attempted.

- 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, with `n`

rows of predicted values and their confidence limits. Optionally it will also include additional values related to the model fit.

## Details

This statistic is similar to `stat_smooth`

but has
different defaults. It interprets the argument passed to `formula`

differently, accepting `y`

as explanatory variable and setting
`orientation`

automatically. The default for `method`

is
`"lm"`

and spline-based smoothers like `loess`

are not supported.
Other defaults are consistent with those in `stat_poly_eq()`

,
`stat_quant_line()`

, `stat_quant_eq()`

, `stat_ma_line()`

,
`stat_ma_eq()`

.

`geom_poly_line()`

treats the x and y aesthetics differently and can
thus have two orientations. The orientation can be deduced 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 formula defaults to `y ~ x`

. For consistency with
`stat_smooth`

orientation can be also specified directly
passing an argument to the `orientation`

parameter, which can be either
`"x"`

or `"y"`

. The value of `orientation`

gives the axis that
is taken as the explanatory variable or `x`

in the model formula.
Package 'ggpmisc' does not define new geometries matching the new statistics
as they are not needed and conceptually transformations of `data`

are
statistics in the grammar of graphics.

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. `stat_poly_eq()`

mimics how `stat_smooth()`

works, except that only polynomials can be fitted. Similarly to these
statistics the model fits respect grouping, so the scales used for `x`

and `y`

should both be continuous scales rather than discrete.

With method `"lm"`

, singularity results in terms being dropped with a
message if more numerous than can be fitted with a singular (exact) fit.
In this case and if the model results in a perfect fit due to low
number of observation, estimates for various parameters are `NaN`

or
`NA`

.

With methods other than `"lm"`

, the model fit functions simply fail
in case of singularity, e.g., singular fits are not implemented in
`"rlm"`

.

In both cases the minimum number of observations with distinct values in
the explanatory variable can be set through parameter `n.min`

. The
default `n.min = 2L`

is the smallest suitable for method `"lm"`

but too small for method `"rlm"`

for which `n.min = 3L`

is
needed. Anyway, model fits with very few observations are of little
interest and using larger values of `n.min`

than the default is
wise.

## 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

If `fm.values = TRUE`

is passed then columns based on the summary of
the model fit are added, with the same value in each row within a group.
This is wasteful and disabled by default, but provides a simple and robust
approach to achieve effects like colouring or hiding of the model fit line
based on P-values, r-squared, adjusted r-squared or the number of
observations.

## 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.

## See also

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

## Examples

```
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))
# 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() +
facet_wrap(~drv)
# Inspecting the returned data using geom_debug()
gginnards.installed <- requireNamespace("gginnards", quietly = TRUE)
if (gginnards.installed)
library(gginnards)
if (gginnards.installed)
ggplot(mpg, aes(displ, hwy)) +
stat_poly_line(geom = "debug")
#> [1] "PANEL 1; group(s) -1; 'draw_function()' input 'data' (head):"
#> x y ymin ymax flipped_aes PANEL group orientation
#> 1 1.600000 30.04871 29.17768 30.91974 FALSE 1 -1 x
#> 2 1.668354 29.80738 28.95779 30.65696 FALSE 1 -1 x
#> 3 1.736709 29.56605 28.73763 30.39446 FALSE 1 -1 x
#> 4 1.805063 29.32471 28.51718 30.13225 FALSE 1 -1 x
#> 5 1.873418 29.08338 28.29640 29.87036 FALSE 1 -1 x
#> 6 1.941772 28.84205 28.07529 29.60882 FALSE 1 -1 x
if (gginnards.installed)
ggplot(mpg, aes(displ, hwy)) +
stat_poly_line(geom = "debug", fm.values = TRUE)
#> [1] "PANEL 1; group(s) -1; 'draw_function()' input 'data' (head):"
#> x y ymin ymax p.value r.squared adj.r.squared n
#> 1 1.600000 30.04871 29.17768 30.91974 2.038974e-46 0.5867867 0.5850056 234
#> 2 1.668354 29.80738 28.95779 30.65696 2.038974e-46 0.5867867 0.5850056 234
#> 3 1.736709 29.56605 28.73763 30.39446 2.038974e-46 0.5867867 0.5850056 234
#> 4 1.805063 29.32471 28.51718 30.13225 2.038974e-46 0.5867867 0.5850056 234
#> 5 1.873418 29.08338 28.29640 29.87036 2.038974e-46 0.5867867 0.5850056 234
#> 6 1.941772 28.84205 28.07529 29.60882 2.038974e-46 0.5867867 0.5850056 234
#> fm.class fm.method fm.formula fm.formula.chr flipped_aes PANEL group
#> 1 lm lm:qr y ~ x y ~ x FALSE 1 -1
#> 2 lm lm:qr y ~ x y ~ x FALSE 1 -1
#> 3 lm lm:qr y ~ x y ~ x FALSE 1 -1
#> 4 lm lm:qr y ~ x y ~ x FALSE 1 -1
#> 5 lm lm:qr y ~ x y ~ x FALSE 1 -1
#> 6 lm lm:qr y ~ x y ~ x FALSE 1 -1
#> orientation
#> 1 x
#> 2 x
#> 3 x
#> 4 x
#> 5 x
#> 6 x
if (gginnards.installed)
ggplot(mpg, aes(displ, hwy)) +
stat_poly_line(geom = "debug", method = lm, fm.values = TRUE)
#> [1] "PANEL 1; group(s) -1; 'draw_function()' input 'data' (head):"
#> x y ymin ymax p.value r.squared adj.r.squared n
#> 1 1.600000 30.04871 29.17768 30.91974 2.038974e-46 0.5867867 0.5850056 234
#> 2 1.668354 29.80738 28.95779 30.65696 2.038974e-46 0.5867867 0.5850056 234
#> 3 1.736709 29.56605 28.73763 30.39446 2.038974e-46 0.5867867 0.5850056 234
#> 4 1.805063 29.32471 28.51718 30.13225 2.038974e-46 0.5867867 0.5850056 234
#> 5 1.873418 29.08338 28.29640 29.87036 2.038974e-46 0.5867867 0.5850056 234
#> 6 1.941772 28.84205 28.07529 29.60882 2.038974e-46 0.5867867 0.5850056 234
#> fm.class fm.method fm.formula fm.formula.chr flipped_aes PANEL group
#> 1 lm method y ~ x y ~ x FALSE 1 -1
#> 2 lm method y ~ x y ~ x FALSE 1 -1
#> 3 lm method y ~ x y ~ x FALSE 1 -1
#> 4 lm method y ~ x y ~ x FALSE 1 -1
#> 5 lm method y ~ x y ~ x FALSE 1 -1
#> 6 lm method y ~ x y ~ x FALSE 1 -1
#> orientation
#> 1 x
#> 2 x
#> 3 x
#> 4 x
#> 5 x
#> 6 x
```