MARSS: MARSS Model Specification and Estimation

Description

This is the main MARSS function for fitting multivariate autoregressive state-space (MARSS) models. Scroll down to the bottom to see some short examples. To open the user guide from the command line, type RShowDoc("UserGuide",package="MARSS"). To open a guide to show you how to get started quickly, type RShowDoc("Quick_Start",package="MARSS"). To open an overview page with package information and how to find all the R code for the user guide chapters, type RShowDoc("index",package="MARSS"). To get info on the axillary functions (like for bootstrapping and confidence intervals) go to MARSS-package. To see a discussion of how to get output from your model fits, go to print.MARSS. If MARSS() is throwing errors or warnings that you don't understand, try the Troubleshooting section of the user guide or type MARSSinfo() at the command line. The background section on this page is focused on fitting MARSS models in vectorized form. This form will almost certainly look unfamilar. MARSS works by converting the users' (more familiar model form) into the vectorized form which allows general linear constraints. You should go to the help page for the form of the model you are fitting to get background on that model form. Currently the MARSS package has two model forms: marxss and dfa. [object Object],[object Object] The rest of this help page discusses the vectorized form of a MARSS model. The MARSS package fits time-varying state-space models that can be transformed into the form (termed form=marss): [object Object],[object Object],[object Object] where beta, upsilon, zeta, and alpha are column vectors of estimated values, the f are column vectors of inputs, and the D are matrices of inputs. The f and D are potentially time-varying. (x) means kronecker product and I_p is a p x p identity matrix. The function MARSS() is used to fit MARSS models using the argument form to specify the type of state-space model being fit. Most commonly used multivariate autoregressive state-space models can be reformulated into the form above. The user is not required to specify their model in the marss form (which is unfamiliar and unwieldy). Instead MARSS() uses the form argument to specify a more familiar state-space form. The user specifies their model in that (more familiar) form. MARSS() calls a helper function MARSS_form to translate the user's model into form=marss. The default MARSS form is "marxss" which is the state-space model: [object Object],[object Object],[object Object] See MARSS.marxss for arguments and defaults information. If you are working with models with time-varying parameters, it is important to notice the time-index for the parameters in the process equation (the x equation). In some formulations (e.g. in the KFAS), the process equation is x(t)=B(t-1)x(t-1)+w(t-1) so B(t-1) goes with x(t) not B(t). Thus one needs to be careful to line up the time indices when passing in time-varying parameters to MARSS().

Usage

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

Arguments

A n x T matrix of n time series over T time steps.

inits

A list with the same form as the list outputted by coef(fit) that specifies initial values for the parameters. See also MARSS.marxss.

model

Model specification using parameter model text shortcuts or matrices. See Details and MARSS.marxss for the default form. Or better yet open the Quick Start Guide RShowDoc("Quick_Start",package="M

miss.value

Deprecated. Denote missing values by NAs in your data.

method

Estimation method. MARSS provides an EM algorithm (method="kem") (see MARSSkem) and the BFGS algorithm (method="BFGS") (see MARSSoptim

form

The equation form used in the MARSS() call. The default is "marxss". See MARSS.marxss or MARSS.dfa.

fit

TRUE/FALSE Whether to fit the model to the data. If FALSE, a marssMLE object with only the model is returned.

silent

TRUE/FALSE Suppresses printing of full error messages, warnings, progress bars and convergence information. Setting silent=2 will produce more verbose error messages and progress information.

control

Estimation options for the maximization algorithm. The typically used control options for method="kem" are below but see marssMLE for the full list of control options. Note many of these are not allowed

Value

An object of class marssMLE. The structure of this object is discussed below, but if you want to know how to get specific output (like residuals, coefficients, smoothed states, confidence intervals, etc), go here print.MARSS. The outputted marssMLE object has the following components:
modelMARSS model specification. It is a marssMODEL object in the form specified by the user in the MARSS() call. This is used by print functions so that the user sees the expected form.
marssThe marssMODEL object in marss form. This form is needed for all the internal algorithms, thus is a required part of a marssMLE object.
callAll the information passed in in the MARSS() call.
startList with specifying initial values that were used for each parameter matrix.
controlA list of estimation options, as specified by arguments control.
methodEstimation method.
If fit=TRUE, the following are also added to the marssMLE object. If fit=FALSE, an marssMLE object ready for fitting via the specified method is returned.
parA list of estimated parameter values Z, A, R, B, U, Q, x0, V0. See print.marssMLE or coef.marssMLE for information on outputing the model estimates. This will be in form "marss". Use print or coef to output the estimated parameters in the form in the MARSS() call (e.g. the default "marxss" form).
statesThe expected value of x conditioned on the data.
states.seThe standard errors of the expected value of x.
ytTThe expected value of y conditioned on the data. Note this is just y for those y that are not missing.
y.seThe standard errors of the expected value of y. Note this is 0 for any non-missing y.
numIterNumber of iterations required for convergence.
convergenceConvergence status. 0 means converged successfully. Anything else is a warning or error. 2 means the MLEobj has an error; the MLEobj is returned so you can debug it. The other numbers are errors during fitting. The error code depends on the fitting method. See MARSSkem and MARSSoptim.
logLikLog-likelihood.
AICAkaike's Information Criterion.
AICcSample size corrected AIC.
If control$trace is set to 1 or greater, the following are also added to the marssMLE object.
kfA list containing Kalman filter/smoother output from MARSSkf. This isn't normally added to a marssMLE object since it is verbose, but can be computed using MARSSkf(marssMLE).
EyA list containing output from MARSShatyt. This isn't normally added to a marssMLE object since it is verbose, but can be computed using MARSShatyt(marssMLE).

item

MCbounds
fun.kf
...

Details

MARSS provides an interface to the base MARSS-package functions and allows specification and fitting of MARSS models. The available estimation methods are maximum-likelihood via an EM algorithm (method="kem") or via a quasi-Newton algorithm provided by function optim (method="BFGS"). The function MARSS() allows the user to specify models using the model argument. See MARSS.marxss for the format of the model argument for the default marxss form. See also the User Guide (reference and link below) or Quick Start Guide. A call to MARSS() returns an object of class marssMLE. The MARSS package has print, coef, residuals, and predict functions that will handle marssMLE objects. See print.marssMLE, coef.marssMLE, residuals.marssMLE, and predict.marssMLE. The help page for print.marssMLE summarizes all the different output available for marssMLE objects and describes what the output is mathematically. Thus, this page is the first place to start and will direct you to the appropriate other method functions (like coef). Many different types of multivariate time-series models can be converted to the MARSS form (see the User Guide). MARSS() allows the user to specify the form of their model using the argument form. The default form is a multivariate lag-1 (time-varying) state-space model which is denoted using form="marxss". Look at MARSS.marxss) to see how the model argument for the marxss form is specified. The model argument is a list, but the elements of that and how it is converted to a marssMODEL(form=marss) object (needed for the internal algorithms) depends intimately on the equation form. Thus you will need to refer to that appropriate help page (MARSS.formname) for your equation form. The likelihood surface for MARSS models can be multimodal or with strong ridges. It is recommended that for final analyses the ML estimates are checked by using the Monte Carlo initial conditions search using MCInit=TRUE in the control list. This requires more computation time, but reduces the chance of the algorithm terminating at a local maximum and not reaching the true MLEs. Also it is wise to check the EM results against the BFGS results (if possible) since if there are strong ridges in the likelihood. Such ridges seems to slow down the EM algorithm considerably and can cause the algorithm to report convergence far from the ML values. EM steps up the likelihood and the convergence test is based on the rate of change of the LL in each step; once on a strong ridge, the steps can slow dramatically. You can force the algorithm to keep working by setting minit. BFGS seems less hindered by the ridges but can be prodigiously slow for some multivariate problems.

References

The 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 Type RShowDoc("UserGuide",package="MARSS") to open a copy. Holmes, E. E. (2012). Derivation of the EM algorithm for constrained and unconstrained multivariate autoregressive state-space (MARSS) models. Technical Report. arXiv:1302.3919 [stat.ME] Holmes, E. E., E. J. Ward and K. Wills. (2012) MARSS: Multivariate autoregressive state-space models for analyzing time-series data. R Journal 4: 11-19.

Examples

Run this code

#harborSealWA is a n=5 matrix of logged population counts
dat = t(harborSealWA)
dat = dat[2:4,] #remove the year row
#fit a model with 1 hidden state and 3 observation time series
kemfit = MARSS(dat, model=list(Z=matrix(1,3,1), 
   R="diagonal and equal"))
kemfit$model #This gives a description of the model
print(kemfit$model) # same as kemfit$model
summary(kemfit$model) #This shows the model structure

#add CIs to a marssMLE object
#default uses an estimated Hessian matrix
kem.with.hess.CIs = MARSSparamCIs(kemfit)   
kem.with.hess.CIs #print with se's and CIs

#fit a model with 3 hidden states (default)
kemfit = MARSS(dat, silent=TRUE)  #suppress printing
kemfit #print information on the marssMLE object

#fit a model with 3 correlated hidden states 
# with one variance and one  covariance
#maxit set low to speed up example, but more iterations are need for convergence  
kemfit = MARSS(dat, model=list(Q="equalvarcov"), control=list(maxit=50))
# use Q="unconstrained" to allow different variances and covariances

#fit a model with 3 independent hidden states 
#where each observation time series is independent
#the hidden trajectories 2-3 share their U parameter
kemfit = MARSS(dat, model=list(U=matrix(c("N","S","S"),3,1)))

#same model, but with fixed independent observation errors
#and the 3rd x processes are forced to have a U=0
#Notice how a list matrix is used to combine fixed and estimated elements
#all parameters can be specified in this way using list matrices
kemfit = MARSS(dat, model=list(U=matrix(list("N","N",0),3,1), R=diag(0.01,3)))

#fit a model with 2 hidden states (north and south) 
#where observation time series 1-2 are north and 3 is south
#Make the hidden state process independent with same process var
#Make the observation errors different but independent
#Make the growth parameters (U) the same
#Create a Z matrix as a design matrix that assigns the "N" state to the first 2 rows of dat
#and the "S" state to the 3rd row of data
Z=matrix(c(1,1,0,0,0,1),3,2)
#You can use factor is a shortcut making the above design matrix for Z
#Z=factor(c("N","N","S"))
#name the state vectors
colnames(Z)=c("N","S")
kemfit = MARSS(dat, model=list(Z=Z,
   Q="diagonal and equal",R="diagonal and unequal",U="equal"))

#print the model followed by the marssMLE object
kemfit$model
kemfit

#simulate some new data from our fitted model
sim.data=MARSSsimulate(kemfit, nsim=10, tSteps=10)

#Compute bootstrap AIC for the model; this takes a long, long time
kemfit.with.AICb = MARSSaic(kemfit, output = "AICbp")
kemfit.with.AICb

#Many more short examples can be found in the
#Quick Examples chapter in the User Guide
RShowDoc("UserGuide",package="MARSS")

#You can find the R scripts from the chapters by
#going to the index page
RShowDoc("index",package="MARSS")

Run the code above in your browser using DataLab