Skip to contents

Multivariate AR-1 State-space Model with Inputs

MARSS_marxss.Rd

The argument form="marxss" in a MARSS() function call specifies a MAR-1 model with eXogenous variables model. This is a MARSS(1) model of the form: $$\mathbf{x}_{t} = \mathbf{B}_t \mathbf{x}_{t-1} + \mathbf{u}_t + \mathbf{C}_t \mathbf{c}_t + \mathbf{G}_t \mathbf{w}_t, \textrm{ where } \mathbf{W}_t \sim \textrm{MVN}(0,\mathbf{Q}_t)$$ $$\mathbf{y}_t = \mathbf{Z}_t \mathbf{x}_t + \mathbf{a}_t + \mathbf{D}_t \mathbf{d}_t + \mathbf{H}_t \mathbf{v}_t, \textrm{ where } \mathbf{V}_t \sim \textrm{MVN}(0,\mathbf{R}_t)$$ $$\mathbf{X}_1 \sim \textrm{MVN}(\mathbf{x0}, \mathbf{V0}) \textrm{ or } \mathbf{X}_0 \sim \textrm{MVN}(\mathbf{x0}, \mathbf{V0}) $$ 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.

Note, "marxss" is a model form. A model form is defined by a collection of form functions discussed in marssMODEL. These functions are not exported to the user, but are called by MARSS() using the argument form.

Usage

MARSS(y, inits = NULL, model = NULL, miss.value = as.numeric(NA), method = "kem", form = "marxss", fit = TRUE, silent = FALSE, control = NULL, fun.kf = "MARSSkfas", ...)

Details

The allowed arguments when form="marxss" are 1) the arguments common to all forms: "y" (data), "inits", "control", "method", "form", "fit", "silent", "fun.kf" (see MARSS for information on these arguments) and 2) the argument "model" which is a list describing the MARXSS model (the model list is described below). See the Quick Start Guide guide or the User Guide for examples.

The argument model must be a list. The elements in the list specify the structure for the \(\mathbf{B}\), \(\mathbf{u}\), \(\mathbf{C}\), \(\mathbf{c}\), \(\mathbf{Q}\), \(\mathbf{Z}\), \(\mathbf{a}\), \(\mathbf{D}\), \(\mathbf{d}\), \(\mathbf{R}\), \(\mathbf{x}_0\), and \(\mathbf{V}_0\) in the MARXSS model (above). The list elements can have the following values:

Z

Default="identity". A text string, "identity","unconstrained", "diagonal and unequal", "diagonal and equal", "equalvarcov", or "onestate", or a length n vector of factors specifying which of the m hidden state time series correspond to which of the n observation time series. May be specified as a n x m list matrix for general specification of both fixed and shared elements within the matrix. May also be specified as a numeric n x m matrix to use a custom fixed \(\mathbf{Z}\). "onestate" gives a n x 1 matrix of 1s. "identity","unconstrained", "diagonal and unequal", "diagonal and equal", and "equalvarcov" all specify n x n matrices.

B

Default="identity". A text string, "identity", "unconstrained", "diagonal and unequal", "diagonal and equal", "equalvarcov", "zero". Can also be specified as a list matrix for general specification of both fixed and shared elements within the matrix. May also be specified as a numeric m x m matrix to use custom fixed \(\mathbf{B}\), but in this case all the eigenvalues of \(\mathbf{B}\) must fall in the unit circle.

U, x0

Default="unconstrained". A text string, "unconstrained", "equal", "unequal" or "zero". May be specified as a m x 1 list matrix for general specification of both fixed and shared elements within the matrix. May also be specified as a numeric m x 1 matrix to use a custom fixed \(\mathbf{u}\) or \(\mathbf{x}_0\). Notice that U is capitalized in the model argument and output lists.

A

Default="scaling". A text string, "scaling","unconstrained", "equal", "unequal" or "zero". May be specified as a n x 1 list matrix for general specification of both fixed and shared elements within the matrix. May also be specified as a numeric n x 1 matrix to use a custom fixed \(\mathbf{a}\). Care must be taken when specifying A so that the model is not under-constrained and unsolvable model. The default, "scaling", only applies to \(\mathbf{Z}\) matrices that are design matrices (only 1s and 0s and all rows sum to 1). When a column in \(\mathbf{Z}\) has multiple 1s, the first row in the \(\mathbf{a}\) matrix associated with those \(\mathbf{Z}\) rows is 0 and the other associated \(\mathbf{a}\) rows have an estimated value. This is used to treat \(\mathbf{a}\) as an intercept where one intercept for each \(\mathbf{x}\) (hidden state) is fixed at 0 and any other intercepts associated with that \(\mathbf{x}\) have an estimated intercept. This ensures a solvable model when \(\mathbf{Z}\) is a design matrix. Note in the model argument and output, A is capitalized.

Q

Default="diagonal and unequal". A text string, "identity", "unconstrained", "diagonal and unequal", "diagonal and equal", "equalvarcov", "zero". May be specified as a list matrix for general specification of both fixed and shared elements within the matrix. May also be specified as a numeric g x g matrix to use a custom fixed matrix. Default value of g is m, so \(\mathbf{Q}\) is a m x m matrix. g is the number of columns in \(\mathbf{G}\) (below).

R

Default="diagonal and equal". A text string, "identity", "unconstrained", "diagonal and unequal", "diagonal and equal", "equalvarcov", "zero". May be specified as a list matrix for general specification of both fixed and shared elements within the matrix. May also be specified as a numeric h x h matrix to use a custom fixed matrix. Default value of h is n, so \(\mathbf{R}\) is a n x n matrix. h is the num of columns in \(\mathbf{H}\) (below).

V0

Default="zero". A text string, "identity", "unconstrained", "diagonal and unequal", "diagonal and equal", "equalvarcov", "zero". May be specified as a list matrix for general specification of both fixed and shared elements within the matrix. May also be specified as a numeric m x m matrix to use a custom fixed matrix.

D and C

Default="zero". A text string, "identity", "unconstrained", "diagonal and unequal", "diagonal and equal", "equalvarcov", "zero". Can be specified as a list matrix for general specification of both fixed and shared elements within the matrix. May also be specified as a numeric matrix to use custom fixed values. Must have n rows (\(\mathbf{D}\)) or m rows (\(\mathbf{C}\)).

d and c

Default="zero". Numeric matrix. No missing values allowed. Must have 1 column or the same number of columns as the data, \(\mathbf{y}\). The numbers of rows in \(\mathbf{d}\) must be the same as number of columns in \(\mathbf{D}\); similarly for \(\mathbf{c}\) and \(\mathbf{C}\).

G and H

Default="identity". A text string, "identity". Can be specified as a numeric matrix or array for time-varying cases. Must have m rows and g columns (\(\mathbf{G}\)) or n rows and h columns (\(\mathbf{H}\)). g is the dim of \(\mathbf{Q}\) and h is the dim of \(\mathbf{R}\).

tinitx

Default=0. Whether the initial state is specified at t=0 (default) or t=1.

All parameters except \(\mathbf{x}_0\) and \(\mathbf{V}_0\) may be time-varying. If time-varying, then text shortcuts cannot be used. Enter as an array with the 3rd dimension being time. Time dimension must be 1 or equal to the number of time-steps in the data. See Quick Start guide (RShowDoc("Quick_Start",package="MARSS")) or the User Guide (RShowDoc("UserGuide",package="MARSS")) for examples.Valid model structures for method="BFGS" are the same as for method="kem". See MARSSoptim() for the allowed options for this method.

The default estimation method, method="kem", is the EM algorithm described in the MARSS User Guide. The default settings for the control and inits arguments are set via MARSS:::alldefaults$kem in MARSSsettings.R. The defaults for the model argument are set in MARSS_marxss.R For this method, they are:

  • inits = list(B=1, U=0, Q=0.05, Z=1, A=0, R=0.05, x0=-99, V0=0.05, G=0, H=0, L=0, C=0, D=0, c=0, d=0)

  • model = list(Z="identity", A="scaling", R="diagonal and equal", B="identity", U="unconstrained", Q="diagonal and unequal", x0="unconstrained", V0="zero", C="zero",D="zero",c=matrix(0,0,1), d=matrix(0,0,1), tinitx=0, diffuse=FALSE)

  • control=list(minit=15, maxit=500, abstol=0.001, trace=0, sparse=FALSE, safe=FALSE, allow.degen=TRUE, min.degen.iter=50, degen.lim=1.0e-04, min.iter.conv.test=15, conv.test.deltaT=9, conv.test.slope.tol= 0.5, demean.states=FALSE) You can read about these in MARSS(). If you want to speed up your fits, you can turn off most of the model checking using trace=-1.

  • fun.kf = "MARSSkfas"; This sets the Kalman filter function to use. MARSSkfas() is generally more stable as it uses Durban & Koopman's algorithm. But it may dramatically slow down when the data set is large (more than 10 rows of data). Try the classic Kalman filter algorithm to see if it runs faster by setting fun.kf="MARSSkfss". You can read about the two algorithms in MARSSkf.

For method="BFGS", type MARSS:::alldefaults$BFGS to see the defaults.

Value

A object of class marssMLE. See print.marssMLE for a discussion of the various output available for marssMLE objects (coefficients, residuals, Kalman filter and smoother output, imputed values for missing data, etc.). See MARSSsimulate for simulating from marssMLE objects. MARSSboot for bootstrapping, MARSSaic for calculation of various AIC related model selection metrics, and MARSSparamCIs for calculation of confidence intervals and bias. See plot.marssMLE for some default plots of a model fit.

Author

Eli Holmes, NOAA, Seattle, USA.

See also

marssMODEL, MARSS.dfa()

Examples

if (FALSE) {
#See the MARSS man page for examples
?MARSS

#and the Quick Examples chapter in the User Guide
RShowDoc("UserGuide",package="MARSS")
}