%\VignetteIndexEntry{Quick Start Guide}
%\VignettePackage{MARSS}
\documentclass[12pt]{article}
\usepackage{amsmath} % the standard math package
\usepackage[landscape]{geometry}
\title{Quick Start Guide}
\begin{document}
<<RUNFIRST, echo=FALSE>>=
options(prompt=" ", continue=" ")
@
\section*{MARSS Quick Start Guide}
A MARSS model is a linear multivariate autoregressive state-space model, also called dynamic linear models (DLMs) or variable autoregressive (VAR) state-space models.  In its most general form a MARSS model is written as follows (using $m=2$ and $n=3$):
\begin{gather*}
\begin{bmatrix}x_1\\ x_2\end{bmatrix}_t
= \begin{bmatrix}b_{11}&b_{12}\\b_{21}&b_{22}\end{bmatrix}
\begin{bmatrix}x_1\\x_2\end{bmatrix}_{t-1}
+ \begin{bmatrix}w_1\\ w_2\end{bmatrix}_t,\quad 
\begin{bmatrix}w_1\\ w_2\end{bmatrix}_t \sim MVN\begin{pmatrix}\begin{bmatrix}u_1\\u_2\end{bmatrix},\begin{bmatrix}q_{11}&q_{12}\\q_{21}&q_{22}\end{bmatrix} \end{pmatrix}  \\
\\
\begin{bmatrix}y_1\\ y_2\\ y_3\end{bmatrix}_t
= \begin{bmatrix}z_{11}&z_{12}\\ z_{21}&z_{22}\\ z_{31}&z_{32}\end{bmatrix}
\begin{bmatrix}x_1\\ x_2\end{bmatrix}_t
+ \begin{bmatrix}v_1\\ v_2\\ v_3\end{bmatrix}_t,\quad 
\begin{bmatrix}v_1\\ v_2\\ v_3\end{bmatrix}_t \sim MVN\begin{pmatrix}\begin{bmatrix}a_1\\ a_2\\ a_3\end{bmatrix},
 \begin{bmatrix}r_{11}&r_{12}&r_{13}\\r_{21}&r_{22}&r_{23}\\r_{31}&r_{32}&r_{33}\end{bmatrix} \end{pmatrix}  \\
\\
\begin{bmatrix}x_1\\ x_2\end{bmatrix}_0 \sim MVN\begin{pmatrix}\begin{bmatrix}\pi_1\\ \pi_2\end{bmatrix},\begin{bmatrix}\nu_{11}&\nu_{12}\\ \nu_{21}&\nu_{22}\end{bmatrix} \end{pmatrix} \quad 
or\quad 
\begin{bmatrix}x_1\\ x_2\end{bmatrix}_1 \sim MVN\begin{pmatrix}\begin{bmatrix}\pi_1\\ \pi_2\end{bmatrix},\begin{bmatrix}\nu_{11}&\nu_{12}\\ \nu_{21}&\nu_{22}\end{bmatrix} \end{pmatrix} 
\end{gather*}

To fit your MARSS model, first write the model in the form above.  Many of the parameter elements will be fixed and others will be shared (equal) within a matrix.  The following shows an example of a mean-reverting random walk model with three observation time series:
\begin{gather*}
\begin{bmatrix}x_1\\ x_2\end{bmatrix}_t
= \begin{bmatrix}b&0\\ 0&b\end{bmatrix}
\begin{bmatrix}x_1\\ x_2\end{bmatrix}_{t-1}
+ \begin{bmatrix}w_1\\ w_2\end{bmatrix}_t, \quad 
\begin{bmatrix}w_1\\ w_2\end{bmatrix}_t \sim MVN\begin{pmatrix}\begin{bmatrix}0\\0\end{bmatrix},\begin{bmatrix}q_{11}&q_{12}\\ q_{12}&q_{22}\end{bmatrix} \end{pmatrix}, \quad
\begin{bmatrix}x_1\\ x_2\end{bmatrix}_0 \sim MVN\begin{pmatrix}\begin{bmatrix}0\\ 0\end{bmatrix},\begin{bmatrix}1&0\\ 0&1\end{bmatrix} \end{pmatrix} \\
\\
\begin{bmatrix}y_1\\y_2\\y_3\end{bmatrix}_t
= \begin{bmatrix}1&1\\ 0&1\\ 1&0\end{bmatrix}
\begin{bmatrix}x_1\\x_2\end{bmatrix}_t
+ \begin{bmatrix}v_1\\ v_2\\ v_3\end{bmatrix}_t,\quad 
\begin{bmatrix}v_1\\ v_2\\ v_3\end{bmatrix}_t \sim MVN\begin{pmatrix}\begin{bmatrix}a_1\\ 0\\ 0\end{bmatrix},
 \begin{bmatrix}r_{11}&0&0\\ 0&r&0\\ 0&0&r\end{bmatrix} \end{pmatrix} 
\end{gather*}

The model specification for the MARSS package has a one-to-one relationship to the model written on paper, i.e. you specify the form of the parameter matrices using matrices in R.  Matrices that combine fixed and estimated values are specified using a list matrix with numerical values for fixed values and  character names for the estimated values. The following shows how to specify the model above.
<<model.spec, eval=FALSE>>=
B1=matrix(list("b",0,0,"b"),2,2)
U1=matrix(0,2,1)
Q1=matrix(c("q11","q12","q12","q22"),2,2)
Z1=matrix(c(1,0,1,1,1,0),3,2)
A1=matrix(list("a1",0,0),3,1)
R1=matrix(list("r11",0,0,0,"r",0,0,0,"r"),3,3)
pi1=matrix(0,2,1)
V1=diag(1,2)
model.list=list(B=B1,U=U1,Q=Q1,Z=Z1,A=A1,R=R1,x0=pi1,V0=V1)
@
The matrix names in the model list must be B, U, Q, Z, A, R, x0, and V0.  The data must be entered as a $n \times T$ matrix; a dataframe is not a matrix nor is a vector.  There are many text shortcuts for common parameter forms, such as ``diagonal and unequal''; see the User Guide for the possible shortcuts.

The call to MARSS then becomes
<<marss.call, eval=FALSE>>=
fit=MARSS(data, model=model.list, control=list(kf.x0="x00"))
@
The control list tells MARSS whether the initial state (x0) is at $t=1$ (\verb@"x10"@) or $t=0$ (\verb@"x00"@).   Type \verb@?MARSS@ at the command line to get more information on control values and shortcuts and defaults for the model specification.

 \textit{Specification of a properly constrained model with a unique solution is the responsibility of the user because MARSS has no way to tell if you have specified an insufficiently constrained model---with correspondingly infinite number of solutions.}

Although the MARSS appears to not include covariates, covariates enter the model as data with a corresponding covariate state process.  The R or Q variances can be set to zero to specify partially deterministic systems.  The model appears to be only AR-1 but AR-p models can be written in the above form by properly defining the $x_t$ vector. Although the model appears to only include i.i.d. errors, in practice, AR-p errors can be included by moving the errors into the state model.  See the User Guide for examples.
<<Reset, echo=FALSE>>=
options(prompt="> ", continue="+ ")
@
\end{document}