MARSS (version 3.2)

MARSS: Interface MARSS Model Specification and Estimation

Description

A top-level MARSS-package function to perform model specification and estimation for multivariate autoregressive state-space (MARSS) models. To open the user guide from the command line, type RShowDoc("UserGuide",package="MARSS"). To open an overview page with package information, type RShowDoc("index",package="MARSS") or go to MARSS-package. The MARSS package fits state-space models that can be written in the marssm form: [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. MARSS() reformulates the model into marssm form and fits the model. The default MARSS form is "marxss" which is the state-space model: [object Object],[object Object],[object Object]

Usage

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

Arguments

y

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

inits

List with up to 7 matrices A, R, B, U, Q, x0, V0, specifying initial values for beta, upsilon, zeta and alpha. All matrices have 1 column. Each row is one estimtated value.

• Bbeta: Initial value(s) for estimates values in the B

model

Model specification using parameter model descriptions. See Details.

miss.value

How are missing values represented in the data?

method

Estimation method. MARSS allows method="kem" (see MARSSkem for more info) and "BFGS" (see MARSSoptim for more info).

form

The equation form used to translate the model argument into a marssm model object for the fitting algorithms. The default is marxss.

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.

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 with the following components:
• model
  MARSS model specification.
• start
  List with 8 matrices A, R, B, U, Q, Z, x0, V0, specifying initial values that were used for the values estimated.
• control
  A list of estimation options, as specified by arguments control.
• method
  Estimation 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.
• par
  A list with 8 matrices of estimated parameter values Z, A, R, B, U, Q, x0, V0. The model argument is needed to translate this to parameter matrices as it is a vector of only the estimated elements in a model parameter.
• kf
  A list containing Kalman filter/smoother output from MARSSkf.
• numIter
  Number of iterations required for convergence.
• convergence
  Convergence 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.
• logLik
  Log-likelihood.
• AIC
  Akaike's Information Criterion.
• AICc
  Sample size corrected AIC.

item

• MCbounds
• ...

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 which is a list specifying the structure for each parameter matrix. The user can use text strings for common classes of parameter matrices. It also allows the user to specify fixed values for matrices by passing in numeric matrices in the model list. Models with a combination of fixed values and shared estimated values can be specified using list matrices. See marssm or the user guide (reference and link below) for documentation and instructions on specifying list matrices for the model parameters. Many different types of multivariate time-series models can be converted to the MARSS form (see the user guide). MARSS() also 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 marssm model object 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, this seems to slow down the EM algorithm considerably and 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. Type RShowDoc("EMDerivation",package="MARSS") to open a copy.

See Also

marssm marssMLE MARSSkem MARSSoptim MARSS-package

Examples

#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=factor(c(1,1,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))

#fit a model with 3 correlated hidden states
#maxit set low to speed up example, but more iterations are need for convergence  
kemfit = MARSS(dat, model=list(Q="unconstrained"), control=list(maxit=50))

#fit a model with 3 independent hidden states 
#where each observation time series is independent
#the hidden trajectories 1-3 & 4-5 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
kemfit = MARSS(dat, model=list(Z=factor(c("N","N","S")),
   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=100)


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