`stat_fit_residuals`

fits a linear model and returns
residuals ready to be plotted as points.

## Usage

```
stat_fit_residuals(
mapping = NULL,
data = NULL,
geom = "point",
method = "lm",
method.args = list(),
n.min = 2L,
formula = NULL,
resid.type = NULL,
weighted = FALSE,
position = "identity",
na.rm = FALSE,
orientation = NA,
show.legend = FALSE,
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

- method
function or character If character, "lm", "rlm", "rq" and the name of a function to be matched, possibly followed by the fit function's

`method`

argument separated by a colon (e.g.`"rq:br"`

). Functions implementing methods must accept arguments to parameters`formula`

,`data`

,`weights`

and`method`

. A`residuals()`

method must exist for the returned model fit object class.- 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.

- formula
a "formula" object. Using aesthetic names instead of original variable names.

- resid.type
character passed to

`residuals()`

as argument for`type`

(defaults to`"working"`

except if`weighted = TRUE`

when it is forced to`"deviance"`

).- weighted
logical If true weighted residuals will be returned.

- position
The position adjustment to use for overlapping points on this layer

- 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 should not 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. See`layer`

for more details.

## Details

This stat can be used to automatically plot residuals as points in a
plot. At the moment it supports only linear models fitted with function
`lm()`

or `rlm()`

. It applies to the fitted model object methods
`residuals`

or `weighted.residuals`

depending on the argument passed to parameter `weighted`

.

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 the model `formula`

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

How weights are applied to residuals depends on the method used to fit the model. For ordinary least squares (OLS), weights are applied to the squares of the residuals, so the weighted residuals are obtained by multiplying the "deviance" residuals by the square root of the weights. When residuals are penalized differently to fit a model, the weighted residuals need to be computed accordingly. Say if we use the absolute value of the residuals instead of the squared values, weighted residuals are obtained by multiplying the residuals by the weights.

## Computed variables

Data frame with same value of `nrow`

as
`data`

as subset for each group containing five numeric variables.

- x
x coordinates of observations or x residuals from fitted values

, - y
y coordinates of observations or y residuals from fitted values

, - x.resid
residuals from fitted values

,
- y.resid
residuals from fitted values

, - weights
the weights passed as input to lm or those computed by rlm

.

For `orientation = "x"`

, the default, `stat(y.resid)`

is copied
to variable `y`

, while for `orientation = "y"`

`stat(x.resid)`

is copied to variable `x`

.

## See also

Other ggplot statistics for model fits:
`stat_fit_augment()`

,
`stat_fit_deviations()`

,
`stat_fit_glance()`

,
`stat_fit_tb()`

,
`stat_fit_tidy()`

## Examples

```
# generate artificial data
set.seed(4321)
x <- 1:100
y <- (x + x^2 + x^3) + rnorm(length(x), mean = 0, sd = mean(x^3) / 4)
my.data <- data.frame(x, y)
# plot residuals from linear model
ggplot(my.data, aes(x, y)) +
geom_hline(yintercept = 0, linetype = "dashed") +
stat_fit_residuals(formula = y ~ x)
ggplot(my.data, aes(x, y)) +
geom_hline(yintercept = 0, linetype = "dashed") +
stat_fit_residuals(formula = y ~ x, weighted = TRUE)
# plot residuals from linear model with y as explanatory variable
ggplot(my.data, aes(x, y)) +
geom_vline(xintercept = 0, linetype = "dashed") +
stat_fit_residuals(formula = x ~ y) +
coord_flip()
# give a name to a formula
my.formula <- y ~ poly(x, 3, raw = TRUE)
# plot residuals from linear model
ggplot(my.data, aes(x, y)) +
geom_hline(yintercept = 0, linetype = "dashed") +
stat_fit_residuals(formula = my.formula) +
coord_flip()
ggplot(my.data, aes(x, y)) +
geom_hline(yintercept = 0, linetype = "dashed") +
stat_fit_residuals(formula = my.formula, resid.type = "response")
# plot residuals from robust regression
ggplot(my.data, aes(x, y)) +
geom_hline(yintercept = 0, linetype = "dashed") +
stat_fit_residuals(formula = my.formula, method = "rlm")
# plot residuals with weights indicated by colour
my.data.outlier <- my.data
my.data.outlier[6, "y"] <- my.data.outlier[6, "y"] * 10
ggplot(my.data.outlier, aes(x, y)) +
stat_fit_residuals(formula = my.formula, method = "rlm",
mapping = aes(colour = after_stat(weights)),
show.legend = TRUE) +
scale_color_gradient(low = "red", high = "blue", limits = c(0, 1),
guide = "colourbar")
# plot weighted residuals with weights indicated by colour
ggplot(my.data.outlier) +
stat_fit_residuals(formula = my.formula, method = "rlm",
mapping = aes(x = x,
y = stage(start = y, after_stat = y * weights),
colour = after_stat(weights)),
show.legend = TRUE) +
scale_color_gradient(low = "red", high = "blue", limits = c(0, 1),
guide = "colourbar")
# plot residuals from quantile regression (median)
ggplot(my.data, aes(x, y)) +
geom_hline(yintercept = 0, linetype = "dashed") +
stat_fit_residuals(formula = my.formula, method = "rq")
# plot residuals from quantile regression (upper quartile)
ggplot(my.data, aes(x, y)) +
geom_hline(yintercept = 0, linetype = "dashed") +
stat_fit_residuals(formula = my.formula, method = "rq",
method.args = list(tau = 0.75))
# inspecting the returned data
gginnards.installed <- requireNamespace("gginnards", quietly = TRUE)
if (gginnards.installed)
library(gginnards)
if (gginnards.installed)
ggplot(my.data, aes(x, y)) +
stat_fit_residuals(formula = my.formula, resid.type = "working",
geom = "debug")
#> [1] "PANEL 1; group(s) -1; 'draw_function()' input 'data' (head):"
#> x y y.resid x.resid weights PANEL group orientation
#> 1 1 -23513.687 -23513.687 NA 1 1 -1 NA
#> 2 2 -11663.732 -11663.732 NA 1 1 -1 NA
#> 3 3 47289.460 47289.460 NA 1 1 -1 NA
#> 4 4 54175.231 54175.231 NA 1 1 -1 NA
#> 5 5 -8620.676 -8620.676 NA 1 1 -1 NA
#> 6 6 101247.937 101247.937 NA 1 1 -1 NA
if (gginnards.installed)
ggplot(my.data, aes(x, y)) +
stat_fit_residuals(formula = my.formula, method = "rlm",
geom = "debug")
#> [1] "PANEL 1; group(s) -1; 'draw_function()' input 'data' (head):"
#> x y y.resid x.resid weights PANEL group orientation
#> 1 1 -24689.771 -24689.771 NA 1.0000000 1 -1 NA
#> 2 2 -12710.840 -12710.840 NA 1.0000000 1 -1 NA
#> 3 3 46364.845 46364.845 NA 1.0000000 1 -1 NA
#> 4 4 53366.731 53366.731 NA 1.0000000 1 -1 NA
#> 5 5 -9319.337 -9319.337 NA 1.0000000 1 -1 NA
#> 6 6 100652.946 100652.946 NA 0.7800764 1 -1 NA
```