prep.initial {dynr}

Recipe function for preparing the initial conditions for the model.

Description

Recipe function for preparing the initial conditions for the model.

Usage

prep.initial(values.inistate, params.inistate, values.inicov, params.inicov,
  values.regimep = 1, params.regimep = 0, covariates, deviation = FALSE,
  refRow)

Arguments

values.inistate

a vector or list of vectors of the starting or fixed values of the initial state vector in one or more regimes. May also be a matrix or list of matrices.

params.inistate

a vector or list of vectors of the parameter names that appear in the initial state vector in one or more regimes. If an element is 0 or "fixed", the corresponding element is fixed at the value specified in the values vector; Otherwise, the corresponding element is to be estimated with the starting value specified in the values vector. May also be a matrix or list of matrices.

values.inicov

a positive definite matrix or a list of positive definite matrices of the starting or fixed values of the initial error covariance structure(s) in one or more regimes. If only one matrix is specified for a regime-switching dynamic model, the initial error covariance structure stays the same across regimes. To ensure the matrix is positive definite in estimation, we apply LDL transformation to the matrix. Values are hence automatically adjusted for this purpose.

params.inicov

a matrix or list of matrices of the parameter names that appear in the initial error covariance(s) in one or more regimes. If an element is 0 or "fixed", the corresponding element is fixed at the value specified in the values matrix; Otherwise, the corresponding element is to be estimated with the starting value specified in the values matrix. If only one matrix is specified for a regime-switching dynamic model, the process noise structure stays the same across regimes. If a list is specified, any two sets of the parameter names as in two matrices should be either the same or totally different to ensure proper parameter estimation.

values.regimep

a vector/matrix of the starting or fixed values of the initial probabilities of being in each regime. By default, the initial probability of being in the first regime is fixed at 1.

params.regimep

a vector/matrix of the parameter indices of the initial probabilities of being in each regime. If an element is 0 or "fixed", the corresponding element is fixed at the value specified in the "values" vector/matrix; Otherwise, the corresponding element is to be estimated with the starting value specified in the values vector/matrix.

covariates

character vector of the names of the (person-level) covariates

deviation

logical. Whether to use the deviation form or not. See Details.

refRow

numeric. Which row is treated at the reference. See Details.

Details

The initial condition model includes specifications for the intial state vector, initial error covariance matrix, initial probabilities of being in each regime and all associated parameter specifications. The initial probabilities are specified in multinomial logistic regression form. When there are no covariates, this implies multinomial logistic regression with intercepts only. In particular, the initial probabilities not not specified on a 0 to 1 probability scale, but rather a negative infinity to positive infinity log odds scale. Fixing an initial regime probability to zero does not mean zero probability. It translates to a comparison log odds scale against which other regimes will be judged.

The structure of the initial state vector and the initial probability vector depends on the presence of covariates. When there are no covariates these should be vectors, or equivalently single-column matrices. When there are covariates they should have c+1 columns for c covariates. For values.regimep and params.regimep the number of rows should be the number of regimes. For inistate and inicov the number of rows should be the number of latent states. Of course, inicov is a square and symmetric so its number of rows should be the same as its number of columns.

When deviation=FALSE, the non-deviation form of the multinomial logistic regression is used. This form has a separate intercept term for each entry of the initial probability vector. When deviation=TRUE, the deviation form of the multinomial logistic regression is used. This form has an intercept term that is common to all rows of the initial probability vector. The rows are then distinguished by their own individual deviations from the common intercept. The deviation form requires the same reference row constraint as the non-deviation form (described below). By default the reference row is taken to be the row with all zero covariate effects. Of course, if there are no covariates and the deviation form is desired, then the user must provide the reference row.

The refRow argument determines which row is used as the intercept row. It is only used in the deviation form (i.e. deviation=TRUE). In the deviation form, one row of values.regimep and params.regimep contains the intercepts, other rows contain deviations from these intercepts. The refRow argument says which row contains the intercept terms. The default behavior for refRow is to detect the reference row automatically based on which parameters are fixed. If we have problems detecting which is the reference row, then we provide error messages that are as helpful as we can make them.

Value

Object of class 'dynrInitial'

See Also

Methods that can be used include: print, printex, show

Examples

#### No-covariates
# Single regime, no covariates
# latent states are position and velocity
# initial position is free and called 'inipos'
# initial slope is fixed at 1
# initial covariance is fixed to a diagonal matrix of 1s
initialNoC <- prep.initial(
	values.inistate=c(0, 1),
	params.inistate=c('inipos', 'fixed'),
	values.inicov=diag(1, 2),
	params.inicov=diag('fixed', 2))

#### One covariate
# Single regime, one covariate on the inital mean
# latent states are position and velocity
# initial covariance is fixed to a diagonal matrix of 1s
# initial latent means have
#   nrow = numLatentState, ncol = numCovariates + 1
# initial position has free intercept and free u1 effect
# initial slope is fixed at 1
initialOneC <- prep.initial(
	values.inistate=matrix(
		c(0, .5,
		  1,  0), byrow=TRUE,
		nrow=2, ncol=2),
	params.inistate=matrix(
		c('iniPosInt', 'iniPosSlopeU1',
		'fixed', 'fixed'), byrow=TRUE,
		nrow=2, ncol=2),
	values.inicov=diag(1, 2),
	params.inicov=diag('fixed', 2),
	covariates='u1')

#### Regime-switching, one covariate
# latent states are position and velocity
# initial covariance is fixed to a diagonal matrix of 1s
# initial latent means have
#   nrow = numLatentState, ncol = numCovariates + 1
# initial position has free intercept and free u1 effect
# initial slope is fixed at 1
# There are 3 regimes but the mean and covariance
#   are not regime-switching.
initialRSOneC <- prep.initial(
	values.regimep=matrix(
		c(1, 1,
		  0, 1,
		  0, 0), byrow=TRUE,
		nrow=3, ncol=2),
	params.regimep=matrix(
		c('r1int', 'r1slopeU1',
		  'r2int', 'r2slopeU2',
		  'fixed', 'fixed'), byrow=TRUE,
		nrow=3, ncol=2),
	values.inistate=matrix(
		c(0, .5,
		  1,  0), byrow=TRUE,
		nrow=2, ncol=2),
	params.inistate=matrix(
		c('iniPosInt', 'iniPosSlopeU1',
		'fixed', 'fixed'), byrow=TRUE,
		nrow=2, ncol=2),
	values.inicov=diag(1, 2),
	params.inicov=diag('fixed', 2),
	covariates='u1')