getPar0: Get starting values for new model from existing `momentuHMM` or `momentuHierHMM` model fit

Description

For nested models, this function will extract starting parameter values (i.e., Par0 in fitHMM or MIfitHMM) from an existing momentuHMM or momentuHierHMM model fit based on the provided arguments for the new model. Any parameters that are not in common between model and the new model (as specified by the arguments) are set to 0. This function is intended to help users incrementally build and fit more complicated models from simpler nested models (and vice versa).

Usage

getPar0(model, ...)
# S3 method for default
getPar0(
  model,
  nbStates = length(model$stateNames),
  estAngleMean = model$conditions$estAngleMean,
  circularAngleMean = model$conditions$circularAngleMean,
  formula = model$conditions$formula,
  formulaDelta = model$conditions$formulaDelta,
  stationary = model$conditions$stationary,
  mixtures = model$conditions$mixtures,
  formulaPi = model$conditions$formulaPi,
  DM = model$conditions$DM,
  betaRef = model$conditions$betaRef,
  stateNames = model$stateNames,
  ...
)
# S3 method for hierarchical
getPar0(
  model,
  hierStates = model$conditions$hierStates,
  estAngleMean = model$conditions$estAngleMean,
  circularAngleMean = model$conditions$circularAngleMean,
  hierFormula = model$conditions$hierFormula,
  hierFormulaDelta = model$conditions$hierFormulaDelta,
  mixtures = model$conditions$mixtures,
  formulaPi = model$conditions$formulaPi,
  DM = model$conditions$DM,
  ...
)

Value

A named list containing starting values suitable for Par0 and beta0 arguments in fitHMM or MIfitHMM:

Par: A list of vectors of state-dependent probability distribution parameters for each data stream specified in model$conditions$dist
beta: Matrix of regression coefficients for the transition probabilities
delta: Initial distribution of the HMM. Only returned if stateNames has the same membership as the state names for model

Arguments

model: A momentuHMM, momentuHierHMM, miHMM, or miSum object (as returned by fitHMM, MIfitHMM, or MIpool)
...: further arguments passed to or from other methods
nbStates: Number of states in the new model. Default: nbStates=length(model$stateNames)
estAngleMean: Named list indicating whether or not the angle mean for data streams with angular distributions ('vm' and 'wrpcauchy') are to be estimated in the new model. Default: estAngleMean=model$conditions$estAngleMean
circularAngleMean: Named list indicating whether circular-linear or circular-circular regression on the mean of circular distributions ('vm' and 'wrpcauchy') for turning angles are to be used in the new model. See fitHMM. Default: circularAngleMean=model$conditions$circularAngleMean
formula: Regression formula for the transition probability covariates of the new model (see fitHMM). Default: formula=model$conditions$formula.
formulaDelta: Regression formula for the initial distribution covariates of the new model (see fitHMM). Default: formulaDelta=model$conditions$formulaDelta.
stationary: FALSE if there are time-varying covariates in formula or any covariates in formulaDelta. If TRUE, the initial distribution is considered equal to the stationary distribution. Default: FALSE.
mixtures: Number of mixtures for the state transition probabilities (see fitHMM). Default: formula=model$conditions$mixtures.
formulaPi: Regression formula for the mixture distribution probabilities (see fitHMM). Default: formula=model$conditions$formulaPi.
DM: Named list indicating the design matrices to be used for the probability distribution parameters of each data stream in the new model (see fitHMM). Only parameters with design matrix column names that match those in model$conditions$fullDM are extracted, so care must be taken in naming columns if any elements of DM are specified as matrices instead of formulas. Default: DM=model$conditions$DM.
betaRef: Numeric vector of length nbStates indicating the reference elements for the t.p.m. multinomial logit link. Default: formula=model$conditions$betaRef.
stateNames: Character vector of length nbStates indicating the names and order of the states in the new model. Default: stateNames=model$stateNames[1:nbStates].
hierStates: A hierarchical model structure Node for the states (see fitHMM). Default: hierStates=model$conditions$hierStates.
hierFormula: A hierarchical formula structure for the transition probability covariates for each level of the hierarchy (see fitHMM). Default: hierFormula=model$conditions$hierFormula.
hierFormulaDelta: A hierarchical formula structure for the initial distribution covariates for each level of the hierarchy ('formulaDelta'). Default: NULL (no covariate effects and fixPar$delta is specified on the working scale).

Details

All other fitHMM (or MIfitHMM) model specifications (e.g., dist, hierDist, userBounds, workBounds, etc.) and data are assumed to be the same for model and the new model (as specified by nbStates, hierStates, estAngleMean, circularAngleMean, formula, hierFormula, formulaDelta, hierFormulaDelta, DM, etc.).

Note that for hierarchical models, getPar0 will return hierarchical data.tree objects (hierBeta and hierDelta) with the default values for fixPar, betaCons, and deltaCons; if hierarchical t.p.m. or initial distribution parameters are subject to constraints, then these must be set manually on the list object returned by getPar0.

Examples

Run this code

# model is a momentuHMM object, automatically loaded with the package
model <- example$m
data <- model$data
dist <- model$conditions$dist
nbStates <- length(model$stateNames)
estAngleMean <- model$conditions$estAngleMean

newformula <- ~cov1+cov2
Par0 <- getPar0(model,formula=newformula)

if (FALSE) {
newModel <- fitHMM(model$data,dist=dist,nbStates=nbStates,
                   Par0=Par0$Par,beta0=Par0$beta,
                   formula=newformula,
                   estAngleMean=estAngleMean)
}

newDM1 <- list(step=list(mean=~cov1,sd=~cov1))
Par0 <- getPar0(model,DM=newDM1)

if (FALSE) {
newModel1 <- fitHMM(model$data,dist=dist,nbStates=nbStates,
                   Par0=Par0$Par,beta0=Par0$beta,
                   formula=model$conditions$formula,
                   estAngleMean=estAngleMean,
                   DM=newDM1)
}

# same model but specify DM for step using matrices
newDM2 <- 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,"cov1",0,
                           0,0,0,1,
                           0,0,0,"cov1"),nrow=nbStates*2))
                           
# to be extracted, new design matrix column names must match 
# column names of model$conditions$fullDM
colnames(newDM2$step)<-paste0(rep(c("mean_","sd_"),each=2*nbStates),
                      rep(1:nbStates,each=2),
                      rep(c(":(Intercept)",":cov1"),2*nbStates))
Par0 <- getPar0(model,DM=newDM2)
                      
if (FALSE) {
newModel2 <- fitHMM(model$data,dist=dist,nbStates=nbStates,
                   Par0=Par0$Par,beta0=Par0$beta,
                   formula=model$conditions$formula,
                   estAngleMean=estAngleMean,
                   DM=newDM2)
}