Augment accepts a fitted model object and a data set and adds
information about each observation in the data set. New columns always
begin with a .
prefix to avoid overwriting columns in the original
data set.
Augment behaves differently depending on whether the original data or new data
requires augmenting. Typically, when augmenting the original data, only the fitted
model object is specified, and when augmenting new data, the fitted model object
and newdata
are specified. When augmenting the original data, diagnostic
statistics are augmented to each row in the data set. When augmenting new data,
predictions and optional intervals (confidence or prediction) or standard errors are augmented to each
row in the new data set.
Usage
# S3 method for ssn_lm
augment(
x,
drop = TRUE,
newdata = NULL,
se_fit = FALSE,
interval = c("none", "confidence", "prediction"),
level = 0.95,
...
)
# S3 method for ssn_glm
augment(
x,
drop = TRUE,
newdata = NULL,
type = c("link", "response"),
se_fit = FALSE,
interval = c("none", "confidence", "prediction"),
newdata_size,
level = 0.95,
var_correct = TRUE,
...
)
Arguments
- x
- drop
A logical indicating whether to drop extra variables in the fitted model object
x
when augmenting. The default fordrop
isTRUE
.drop
is ignored if augmentingnewdata
.- newdata
A vector that contains the names of the prediction
sf
objects from the originalssn.object
requiring prediction. All of the original explanatory variables used to create the fitted model objectx
must be present in each predictionsf
object represented bynewdata
. Defaults toNULL
, which indicates that nothing has been passed tonewdata
and augmenting occurs for the original data. The value"ssn"
is shorthand for specifying all predictionsf
objects.- se_fit
Logical indicating whether or not a
.se.fit
column should be added to augmented output. Passed topredict()
and defaults toFALSE
.- interval
Character indicating the type of confidence interval columns to add to the augmented
newdata
output. Passed topredict()
and defaults to"none"
.- level
Tolerance/confidence level. The default is
0.95
.- ...
Additional arguments to
predict()
when augmentingnewdata
.- type
The scale (
response
orlink
) of predictions obtained usingssn_glm
objects.- newdata_size
The
size
value for each observation innewdata
used when predicting for the binomial family.- var_correct
A logical indicating whether to return the corrected prediction variances when predicting via models fit using
ssn_glm
. The default isTRUE
.
Value
When augmenting the original data set, a tibble with additional columns
.fitted
: Fitted value.resid
: Response residual (the difference between observed and fitted values).hat
: Leverage (diagonal of the hat matrix).cooksd
: Cook's distance.std.resid
: Standardized residuals.se.fit
: Standard error of the fitted value.
When augmenting a new data set, a tibble with additional columns
.fitted
: Predicted (or fitted) value.lower
: Lower bound on interval.upper
: Upper bound on interval.se.fit
: Standard error of the predicted (or fitted) value
When predictions for all prediction objects are desired, the output is a list where each element has a name that matches the prediction objects and values that are the predictions.
Details
augment()
returns a tibble as an sf
object.
Missing response values from the original data can be augmented as if
they were a newdata
object by providing ".missing"
to the
newdata
argument.
Examples
# Copy the mf04p .ssn data to a local directory and read it into R
# When modeling with your .ssn object, you will load it using the relevant
# path to the .ssn data on your machine
copy_lsn_to_temp()
temp_path <- paste0(tempdir(), "/MiddleFork04.ssn")
mf04p <- ssn_import(temp_path, predpts = "CapeHorn", overwrite = TRUE)
ssn_mod <- ssn_lm(
formula = Summer_mn ~ ELEV_DEM,
ssn.object = mf04p,
tailup_type = "exponential",
additive = "afvArea"
)
augment(ssn_mod)
#> Simple feature collection with 45 features and 8 fields
#> Geometry type: POINT
#> Dimension: XY
#> Bounding box: xmin: -1530805 ymin: 2527111 xmax: -1503079 ymax: 2537823
#> Projected CRS: USA_Contiguous_Albers_Equal_Area_Conic_USGS_version
#> # A tibble: 45 × 9
#> Summer_mn ELEV_DEM .fitted .resid .hat .cooksd .std.resid pid
#> * <dbl> <int> <dbl> <dbl> <dbl> <dbl> <dbl> <chr>
#> 1 11.4 1977 14.3 -2.96 0.157 0.135 -1.31 1
#> 2 10.7 1984 14.1 -3.42 0.0924 0.0184 -0.631 2
#> 3 10.4 1993 13.9 -3.45 0.0301 0.0103 -0.827 3
#> 4 10.1 2007 13.5 -3.35 0.00798 0.000239 -0.245 4
#> 5 10.1 2009 13.4 -3.30 0.0105 0.00000674 0.0359 5
#> 6 9.81 2012 13.3 -3.52 0.00350 0.00285 -1.28 6
#> 7 9.76 2023 13.0 -3.26 0.0179 0.0000144 0.0401 7
#> 8 9.77 2023 13.0 -3.25 0.0169 0.0000741 0.0935 8
#> 9 9.53 2026 12.9 -3.40 0.00831 0.000891 -0.463 9
#> 10 12.6 1988 14.0 -1.45 0.0561 0.0290 -1.02 10
#> # ℹ 35 more rows
#> # ℹ 1 more variable: geometry <POINT [m]>
augment(ssn_mod, newdata = "CapeHorn")
#> Simple feature collection with 654 features and 20 fields
#> Geometry type: POINT
#> Dimension: XY
#> Bounding box: xmin: -1516634 ymin: 2527816 xmax: -1512722 ymax: 2531418
#> Projected CRS: USA_Contiguous_Albers_Equal_Area_Conic_USGS_version
#> # A tibble: 654 × 21
#> COMID GNIS_NAME CDRAINAG AREAWTMAP SLOPE ELEV_DEM FlowCMS AirMEANc
#> * <int> <chr> <dbl> <dbl> <dbl> <int> <dbl> <dbl>
#> 1 23519461 Cape Horn Creek 69.9 1087. 0.00843 2011 34.8 21.5
#> 2 23519461 Cape Horn Creek 69.9 1087. 0.00843 2011 34.8 21.5
#> 3 23519461 Cape Horn Creek 69.9 1087. 0.00843 2011 34.8 21.5
#> 4 23519461 Cape Horn Creek 69.9 1087. 0.00843 2011 34.8 21.5
#> 5 23519461 Cape Horn Creek 69.9 1087. 0.00843 2011 34.8 21.5
#> 6 23519461 Cape Horn Creek 69.9 1087. 0.00843 2011 34.8 21.5
#> 7 23519461 Cape Horn Creek 69.9 1087. 0.00843 2013 34.8 21.5
#> 8 23519461 Cape Horn Creek 69.9 1087. 0.00843 2013 34.8 21.5
#> 9 23519461 Cape Horn Creek 69.9 1087. 0.00843 2013 34.8 21.5
#> 10 23519461 Cape Horn Creek 69.9 1087. 0.00843 2011 34.8 21.5
#> # ℹ 644 more rows
#> # ℹ 13 more variables: AirMWMTc <dbl>, NEAR_X <dbl>, NEAR_Y <dbl>, rid <int>,
#> # ratio <dbl>, afvArea <chr>, upDist <dbl>, locID <int>, netID <int>,
#> # pid <int>, netgeom <chr>, .fitted <dbl>, geometry <POINT [m]>