MARSS (version 3.10.12)

augment.marssMLE: Return the model and state fitted values, residuals, and residual sigma

Description

augment.marssMLE returns a data.frame with fitted values, residuals, and upper and lower confidence intervals (if requested) for the fitted observations or states. augment is concerned with predictions of the states or observations at time t, i.e. the right part of a MARSS model equation with the error terms left off. The error terms are the residuals (the \(v_t\) or \(w_t\)). tidy.marssMLE is concerned with estimates of values (parameters, states or observations) conditioned on all the data.

Usage

augment.marssMLE(x, type = c("ytT", "xtT"),
                              interval = c("none", "confidence", "prediction"), 
                              conf.level = 0.95, 
                              form=attr(x[["model"]], "form")[1])

Arguments

x

a marssMLE object

type

What types of fitted values and residuals to return. ytT (observations) and xtT (states) are the values conditioned on all the data. Read the details below for xtT. tidy would be the more common function for returning xtT (smoothed state) estimates.

interval

Type of interval: none, confidence or prediction interval. If the confidence, approximate intervals from the standard errors of the fitted values is given.

conf.level

Confidence level.

form

If you want the augment function to use a different augment function than augment_form. This might be useful if you manually specified a DFA model and want to use augment.dfa for rotating.

Value

If interval = "none", the data frame has the following columns:

.fitted

Fitted values of observations or states. See details.

.resids

Model or states residuals. See details.

.sigma

The standard error of the model or state residuals. Intervals for the residuals can be constructed from .sigma using qnorm(alpha/2)*.sigma + .fitted.

.std.resid

Standardized residuals. Used for outlier detection. See residuals.marssMLE.

If interval = "confidence", the following are added to the data frame:

.se.fit

Standard errors of fitted values

.conf.low

Lower confidence level at alpha = 1-conf.level. The interval is approximated using qnorm(alpha/2)*.se.fit + .fitted.

.conf.up

Upper confidence level. The interval is approximated using qnorm(1-alpha/2)*.se.fit + .fitted.

If interval = "prediction", the following are added to the data frame:

.sd.x or .sd.y

Standard deviation of new x or y iid values.

.lwr

Lower range at alpha = 1-conf.level. The interval is approximated using qnorm(alpha/2)*.sd + .fitted.

.upr

Upper range at level. The interval is approximated using qnorm(1-alpha/2)*.sd + .fitted.

The standard deviation is for new x or y, not estimated x nor y used in the model. Do not plot the observed data nor the states estimates on the confidence or prediction intervals. For that you need to use .sigma and construct intervals as noted above. autoplot() will show the residuals intervals on the observation plot.

Details

See residuals.marssMLE for a discussion of the residuals calculations for MARSS models. The reported CIs are the approximate CIs computed using the standard deviations: qnorm(alpha/2)*se.fit + fitted.

observations (type="ytT")

This returns a model predicted value of the response (\(\mathbf{y}\)) and the difference between the model prediction and the observed data is the residual. If there is no data point, then the residual is NA. The standard errors help visualize how well the model fits to the data. See fitted.marssMLE for a discussion of the calculation of the fitted values for the observations (the modeled values). The standardized residuals can be used for outlier detection. See residuals.marssMLE and the chapter on shock detection in the MARSS User Guide.

In the literature on state-space models, it is very common to use the one-step ahead predicted values of the data. The fitted values returned by type=ytT are NOT the one-step ahead values and the residuals are NOT the one-step ahead residuals (called Innovations in the state-space literature). If you want the one-step ahead fitted values, you can use fitted(x, conditioning="t-1"). The innovations are also returned by MARSSkf in Innov.

states (type="xtT")

If you want the expected value of the states and an estimate of their standard errors (for confidence intervals), then augment is not what you want to use. You want to use tidy.marssMLE to return the smoothed estimate of the state. augment(MLEobj, type="xtT") returns a model prediction of \(\mathbf{x}(t)\) given \(\mathbf{x}_{t-1}\). The residuals returned are for \(\mathbf{w}_t\), the difference between the two. These types of residuals are used for outlier detection or shock detection in the state process. They are also used for model diagnostics. See residuals.marssMLE and read the references cited.

Examples

# NOT RUN {
dat <- t(harborSeal)
dat <- dat[c(2, 11, 12), ]
MLEobj <- MARSS(dat, model = list(Z = factor(c("WA", "OR", "OR"))))

library(broom)
library(ggplot2)
theme_set(theme_bw())

# Make a plot of the observations and model fits
d <- augment(MLEobj, interval = "confidence")
ggplot(data = d) +
  geom_line(aes(t, .fitted)) +
  geom_point(aes(t, y)) +
  geom_ribbon(aes(x = t, ymin = .conf.low, ymax = .conf.up), linetype = 2, alpha = 0.1) +
  facet_grid(~.rownames) +
  xlab("Time Step") + ylab("Count")

# Make a plot of xtT versus prediction of xt from xtT[t-1]
# This is NOT the estimate of the states with CIs. Use tidy() for that.
d <- augment(MLEobj, type = "xtT")
ggplot(data = d) +
  geom_point(aes(t, xtT)) +
  geom_line(aes(x = t, .fitted)) +
  facet_grid(~.rownames) +
  xlab("Time Step") + ylab("Count") +
  ggtitle("xtT (points) and predition (line)")

# }