addSmooth: addSmooth Add a smoother to a plot, with pointwise confidence...

In ecostats: Code and Data Accompanying the Eco-Stats Text (Warton 2022)

addSmooth Add a smoother to a plot, with pointwise confidence band

Description

Adds a smoother to a plot of y against x, and a confidence band around the smoother with pointwise coverage (not global, unlike plotenvelope). The smoother is constructed using gam and confidence bands use Wald intervals, extracting the standard error from predict.gam.

Usage

addSmooth(
  x,
  y,
  conf.level = 0.05,
  line.col = "slateblue4",
  envelope.col = adjustcolor(line.col, alpha.f = 0.1),
  ...
)

Arguments

x	is the x co-ordinates for the plot, e.g. the fitted values in a plot of residuals vs fitted values.
y	is the y co-ordinates for the plot
conf.level	the confidence level to use in constructing the confidence band around the smoother.
line.col	color of smoother. Defaults to "slateblue4".
envelope.col	color of the global envelope around the expected trend. All data points should always stay within this envelope (and will for a proportion conf.level of datasets satisfying model assumptions). If a smoother has been used on the residual vs fits or scale-location plot, the envelope is constructed around the smoother, that is, the smoother should always stay within the envelope.
...	further arguments sent through to lines and polygon.

Details

A challenge when interpreting diagnostic plots is understanding the extent to which deviations from the expected pattern could be due to random noise (sampling variation) rather than actual assumption violations. This function is intended to assess this, by simulating multiple realizations of residuals (and fitted values) in situations where assumptions are satisfied, and plotting a global simulation envelope around these at level conf.level.

This function adds a smoother to a plot of y against x using gam, and a confidence band around the smoother with pointwise coverage (not global, unlike plotenvelope) using Wald intervals that take the standard error of predicted values from predict.gam.

When constructing a plot to diagnose model fit, plotenvelope is preferred, because this constructs simulation envelopes globally, simplifying interpretation, and tends to give more accurate envelopes, via simulation. This function is intended to fit trends to data for descriptive purposes, but it could be used (with caution) to diagnose model fit in residual plots in situations where plotenvelope is unavailable.

Value

A smoother is added to the existing plot, with confidence band. In addition, a data frame is invisibly returned with the following components:

X

The values of x at which the smoother is evaluated.

Yhat

Values of the smoother used to predict y, for each value of x.

Yhi

The upper bound on the confidence band, for each value of x.

Ylo

The lower bound on the global envelope, for each value of x.

Author(s)

David Warton <[e-mail]>

References

Warton DI (2022) Eco-Stats - Data Analysis in Ecology, from t-tests to multivariate abundances. Springer, ISBN 978-3-030-88442-0

See Also

plotenvelope

Examples

data(globalPlants)
plot(log(height)~lat,data=globalPlants)
with(globalPlants, addSmooth(lat,log(height)) )

ecostats documentation built on Aug. 24, 2022, 9:07 a.m.