MARSS-package: Multivariate Autoregressive State-Space Model Estimation

Description

The MARSS package fits time-varying constrained and unconstrained multivariate autoregressive time-series models to multivariate time series data. To get started quickly, go to the Quick Start Guide (or at the command line, you can type RShowDoc("Quick_Start", package="MARSS")). To open the MARSS User Guide with many vignettes and examples, go to User Guide (or type RShowDoc("UserGuide",package="MARSS")).

The default MARSS model form is a MARXSS model: Multivariate Auto-Regressive(1) eXogenous inputs State-Space model. This model has the following form: $$\mathbf{x}_{t} = \mathbf{B} \mathbf{x}_{t-1} + \mathbf{u} + \mathbf{C} \mathbf{c}_{t} + \mathbf{G} \mathbf{w}_t, \textrm{ where } \mathbf{w}_t \sim \textrm{MVN}(0,\mathbf{Q})$$ $$\mathbf{y}_t = \mathbf{Z} \mathbf{x}(t) + \mathbf{a} + \mathbf{D} \mathbf{d}_t + \mathbf{H} \mathbf{v}_t, \textrm{ where } \mathbf{v}_t \sim \textrm{MVN}(0,\mathbf{R})$$ $$\mathbf{X}_1 \sim \textrm{MVN}(\mathbf{x0}, \mathbf{V0}) \textrm{ or } \mathbf{X}_0 \sim \textrm{MVN}(\mathbf{x0}, \mathbf{V0}) $$ All parameters can be time-varying; the $t$ subscript is left off the parameters to remove clutter. Note, by default $\mathbf{V0}$ is a matrix of all zeros and thus $\mathbf{x}_1$ or $\mathbf{x}_0$ is treated as an estimated parameter not a diffuse prior.

The parameter matrices can have fixed values and linear constraints. This is an example of a 3x3 matrix with fixed values and linear constraints. In this example all the matrix elements can be written as a linear function of $a$, $b$, and $c$: $$\left[\begin{array}{c c c} a+2b & 1 & a\\ 1+3a+b & 0 & b \\ 0 & -2 & c\end{array}\right]$$ Values such as $a b$ or $a^2$ or $ln(a)$ are not allowed as those would not be linear.

The MARSS model parameters, hidden state processes ($\mathbf{x}$), and observations ($\mathbf{y}$) are matrices:

$\mathbf{x}_t$, $\mathbf{x0}$, and $\mathbf{u}$ are m x 1
$\mathbf{y}_t$ and $\mathbf{a}$ are n x 1 (m<=n)
$\mathbf{B}$ and $\mathbf{V0}$ are m x m
$\mathbf{Z}$ is n x m
$\mathbf{Q}$ is g x g (default m x m)
$\mathbf{G}$ is m x g (default m x m identity matrix)
$\mathbf{R}$ is h x h (default n x n)
$\mathbf{H}$ is n x h (default n x n identity matrix)
$\mathbf{C}$ is m x q
$\mathbf{D}$ is n x p
$\mathbf{c}_t$ is q x 1
$\mathbf{d}_t$ is p x 1

If a parameter is time-varying then the time dimension is the 3rd dimension. Thus a time-varying $\mathbf{Z}$ would be n x m x T where T is the length of the data time series.

The main fitting function is MARSS() which is used to fit a specified model to data and estimate the model parameters. MARSS() estimates the model parameters using an EM algorithm (primarily but see MARSSoptim()). Functions are provided for parameter confidence intervals and the observed Fisher Information matrix, smoothed state estimates with confidence intervals, all the Kalman filter and smoother outputs, residuals and residual diagnostics, printing and plotting, and summaries.

Arguments

Details

Main MARSS functions:

MARSS: Top-level function for specifying and fitting MARSS models.
coef: Returns the estimated parameters in a variety of formats.
tidy.marssMLE: Parameter estimates with confidence intervals
tsSmooth: $\mathbf{x}$ and $\mathbf{y}$ estimates output as a data frame. Output can be conditioned on all the data ($T$), data up to $t-1$, or data up to $t$. From the Kalman filter and smoother output.
fitted: Model x$\mathbf{x}$ and $\mathbf{y}$ predictions as a data frame or matrices. Another user interface for model predictions is predict.marssMLE.
residuals: Model residuals as a data frame.
MARSSresiduals: Model residuals as a data frame or matrices. Normal user interface to residuals is residuals.marssMLE.
predict: Predictions and forecasts from a marssMLE object.
plot for marssMLE: A series of plots of fits and residuals diagnostics.
autoplot: A series of plots using ggplot2 of fits and residuals diagnostics.
glance: Brief summary of fit.
logLik: Log-likelihood.
print: Prints a wide variety of output from a marssMLE object.
print.marssMODEL: Prints description of the MARSS model (marssMODEL object).
plot.marssPredict: Plot a prediction or forecast.
toLatex.marssMODEL: Outputs a LaTeX version of the model.

Other outputs for a fitted model:

MARSSsimulate: Produces simulated data from a MARSS model.
MARSSkf, MARSSkfas, MARSSkfss: Kalman filters and smoothers with extensive output of all the intermediate filter and smoother variances and expectations.
MARSSaic: Calculates AICc, AICc, and various bootstrap AICs.
MARSSparamCIs: Adds confidence intervals to a marssMLE object.
MARSShessian: Computes an estimate of the variance-covariance matrix for the MLE parameters.
MARSSFisherI: Returns the observed Fisher Information matrix.

Important internal MARSS functions (called by the above functions):

MARSSkem: Estimates MARSS parameters using an EM algorithm.
MARSSoptim: Estimates MARSS parameters using a quasi-Newton algorithm via optim.
MARSShatyt: Calculates the expectations involving Y.
MARSSinnovationsboot: Creates innovations bootstrapped data.
MARSS.marss: Discusses the form in which MARSS models are stored internally.

Use help.search("internal", package="MARSS") to see the documentation of all the internal functions in the MARSS R package.

References

The MARSS User Guide: Holmes, E. E., E. J. Ward, and M. D. Scheuerell (2012) Analysis of multivariate time-series using the MARSS package. NOAA Fisheries, Northwest Fisheries Science Center, 2725 Montlake Blvd E., Seattle, WA 98112 User Guide or type RShowDoc("UserGuide",package="MARSS") to open a copy.

The MARSS Quick Start Guide: Quick Start Guide or type RShowDoc("Quick_Start",package="MARSS") to open a copy.