momentuHMM (version 1.2.0)

getParDM: Get starting values on working scale based on design matrix and other parameter constraints

Description

Convert starting values on the natural scale of data stream probability distributions to a feasible set of working scale parameters based on a design matrix and other parameter constraints.

Usage

getParDM(data = data.frame(), nbStates, dist, Par, zeroInflation = NULL,
  oneInflation = NULL, estAngleMean = NULL, circularAngleMean = NULL,
  DM = NULL, cons = NULL, userBounds = NULL, workcons = NULL)

Arguments

data

Optional momentuHMMData object or a data frame containing the covariate values. data must be specified if covariates are included in DM.

nbStates

Number of states of the HMM.

dist

A named list indicating the probability distributions of the data streams. Currently supported distributions are 'gamma','weibull','exp','lnorm','beta','pois','wrpcauchy', and 'vm'. For example, dist=list(step='gamma', angle='vm', dives='pois') indicates 3 data streams ('step', 'angle', and 'dives') and their respective probability distributions ('gamma', 'vm', and 'pois').

Par

A named list containing vectors of state-dependent probability distribution parameters for each data stream specified in dist. The parameters should be on the natural scale, in the order expected by the pdfs of dist, and any zero-mass parameters should be the last.

zeroInflation

A named list of logicals indicating whether the probability distributions of the data streams should be zero-inflated. If zeroInflation is TRUE for a given data stream, then values for the zero-mass parameters should be included in the corresponding element of Par. Ignored if data is a momentuHMMData object.

oneInflation

Named list of logicals indicating whether the probability distributions of the data streams are one-inflated. If oneInflation is TRUE for a given data stream, then values for the one-mass parameters should be included in the corresponding element of Par. Ignored if data is a momentuHMMData object.

estAngleMean

An optional named list indicating whether or not to estimate the angle mean for data streams with angular distributions ('vm' and 'wrpcauchy'). Any estAngleMean elements corresponding to data streams that do not have angular distributions are ignored.

circularAngleMean

An optional named list indicating whether to use circular-linear (FALSE) or circular-circular (TRUE) regression on the mean of circular distributions ('vm' and 'wrpcauchy') for turning angles. circularAngleMean elements corresponding to angular data streams are ignored unless the corresponding element of estAngleMean is TRUE. Any circularAngleMean elements corresponding to data streams that do not have angular distributions are ignored.

DM

A named list indicating the design matrices to be used for the probability distribution parameters of each data stream. Each element of DM can either be a named list of linear regression formulas or a matrix. For example, for a 2-state model using the gamma distribution for a data stream named 'step', DM=list(step=list(mean=~cov1, sd=~1)) specifies the mean parameters as a function of the covariate 'cov1' for each state. This model could equivalently be specified as a 4x6 matrix using character strings for the covariate: DM=list(step=matrix(c(1,0,0,0,'cov1',0,0,0,0,1,0,0,0,'cov1',0,0,0,0,1,0,0,0,0,1),4,6)) where the 4 rows correspond to the state-dependent paramaters (mean_1,mean_2,sd_1,sd_2) and the 6 columns correspond to the regression coefficients.

cons

An optional named list of vectors specifying a power to raise parameters corresponding to each column of the design matrix for each data stream. While there could be other uses, primarily intended to constrain specific parameters to be positive. For example, cons=list(step=c(1,2,1,1)) raises the second parameter to the second power. Default=NULL, which simply raises all parameters to the power of 1. cons is ignored for any given data stream unless DM is specified.

userBounds

An optional named list of 2-column matrices specifying bounds on the natural (i.e, real) scale of the probability distribution parameters for each data stream. For example, for a 2-state model using the wrapped Cauchy ('wrpcauchy') distribution for a data stream named 'angle' with estAngleMean$angle=TRUE), userBounds=list(angle=matrix(c(-pi,-pi,-1,-1,pi,pi,1,1),4,2)) specifies (-1,1) bounds for the concentration parameters instead of the default [0,1) bounds.

workcons

An optional named list of vectors specifying constants to add to the regression coefficients on the working scale for each data stream. Warning: use of workcons is recommended only for advanced users implementing unusual parameter constraints through a combination of DM, cons, and workcons. workcons is ignored for any given data stream unless DM is specified.

Value

A list of parameter values that can be used as starting values (Par0) in fitHMM or MIfitHMM

Details

If design matrix includes non-factor covariates, then natural scale parameters are assumed to correspond to the mean value(s) for the covariate(s) (if nrow(data)>1) and getParDM simply returns one possible solution to the system of linear equations defined by Par, DM, and any other constraints using singular value decomposition. This can be helpful for exploring relationships between the natural and working scale parameters when covariates are included, but getParDM will not necessarily return ``good'' starting values (i.e., Par0) for fitHMM or MIfitHMM.

See Also

getPar, getPar0, fitHMM, MIfitHMM

Examples

# NOT RUN {
# data is a momentuHMMData object, automatically loaded with the package
data <- example$m$data
stepDist <- "gamma"
angleDist <- "vm"
nbStates <- 2
stepPar0 <- c(15,50,10,20) # natural scale mean_1, mean_2, sd_1, sd_2
anglePar0 <- c(0.7,1.5) # natural scale conentration_1, concentration_2

# get working parameters for 'DM' and 'cons' that constrain step length mean_1 < mean_2
stepDM <- matrix(c(1,1,0,0,0,1,0,0,0,0,1,0,0,0,0,1),4,4,
          dimnames=list(NULL,c("mean:(Intercept)","mean_2",
                               "sd_1:(Intercept)","sd_2:(Intercept)")))
stepcons <- c(1,2,1,1) # coefficient for 'mean_2' constrained to be positive
wPar0 <- getParDM(nbStates=2,dist=list(step=stepDist),
                      Par=list(step=stepPar0),
                      DM=list(step=stepDM),cons=list(step=stepcons))

# }
# NOT RUN {
# Fit HMM using wPar0 as initial values for the step data stream
mPar <- fitHMM(data,nbStates=2,dist=list(step=stepDist,angle=angleDist),
               Par0=list(step=wPar0$step,angle=anglePar0),
               DM=list(step=stepDM),cons=list(step=stepcons))
# }
# NOT RUN {
# get working parameters for 'DM' using 'cov1' and 'cov2' covariates
stepDM2 <- list(mean=~cov1,sd=~cov2)
wPar20 <- getParDM(data,nbStates=2,dist=list(step=stepDist),
                      Par=list(step=stepPar0),
                      DM=list(step=stepDM2))

# }
# NOT RUN {
# Fit HMM using wPar20 as initial values for the step data stream
mPar2 <- fitHMM(data,nbStates=2,dist=list(step=stepDist,angle=angleDist),
               Par0=list(step=wPar20$step,angle=anglePar0),
               DM=list(step=stepDM2))
# }
# NOT RUN {
# }