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. Get started quickly, go to the Quick Start Guide (or type RShowDoc("Quick_Start",package="MARSS") at the command line). 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+1} = \mathbf{B} \mathbf{x}_t + \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; "_t" is left off the parameters to remove clutter. Note, by default $V0$ is a matrix of all zeros and thus $x_1$ or $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 $log(a)$ are not allowed as those would not be linear.

The MARSS model parameters, hidden state processes (x), and observations (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 Z parameters 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 a variety of output including 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 in tibble format,

Arguments

Details

Main MARSS functions:

MARSS: Top-level function for specifying and fitting MARSS models.
fitted.marssMLE: Fitted Y and X estimates output as a tibble. Output can be conditioned on all the data (T), data up to t-1, or data up to t.
coef.marssMLE: Returns the estimated parameters in a variety of formats.
tidy.marssMLE: Parameter estimates and fitted Y and X estimates output as a tibble. With confidence intervals if requested
augment.marssMLE: Model residuals as a tibble.
plot.marssMLE: A series of plots of fits and residuals diagnostics.
autoplot.marssMLE: A series of plots using ggplot2 of fits and residuals diagnostics.
glance.marssMLE: Brief summary of fit.
logLik.marssMLE: Log-likelihood.
print.marssMLE: Prints a wide variety of output from a marssMLE object.
print.marssMODEL: Prints description of the MARSS model (marssMODEL object).
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.