randomEffects {momentuHMM}

Random effects estimation

Description

Approximate individual-level random effects estimation for state transition probabilities based on Burnham & White (2002)

Usage

randomEffects(
  m,
  Xformula = ~1,
  alpha = 0.95,
  ncores = 1,
  nlmPar = list(),
  fit = TRUE,
  retryFits = 0,
  retrySD = NULL,
  optMethod = "nlm",
  control = list(),
  modelName = NULL,
  ...
)

Arguments

m

A momentuHMM object.

Xformula

Formula for the design matrix of the random effects model. The default Xformula=~1 specifies an intercept-only model with no additional individual covariate effects.

alpha

Significance level of the confidence intervals. Default: 0.95 (i.e. 95% CIs).

ncores

number of cores to use for parallel processing

nlmPar

List of parameters to pass to the optimization function nlm. See fitHMM.

fit

TRUE if the HMM should be re-fitted at the shrinkage estimates, FALSE otherwise.

retryFits

Non-negative integer indicating the number of times to attempt to iteratively fit the model using random perturbations of the current parameter estimates as the initial values for likelihood optimization. See fitHMM.

retrySD

An optional list of scalars or vectors indicating the standard deviation to use for normal perturbations of each working scale parameter when retryFits>0. See fitHMM.

optMethod

The optimization method to be used. See fitHMM.

control

A list of control parameters to be passed to optim (ignored unless optMethod="Nelder-Mead" or optMethod="SANN").

modelName

An optional character string providing a name for the fitted model. See fitHMM.

...

further arguments passed to or from other methods. Not currently used.

Value

A randomEffects model similar to a momentuHMM object, but including the additional random effect components:

varcomp

A list of length nbStates*(nbStates-1) with each element containing the random effect mean coefficient(s) (mu), random effect variance (sigma), and logit-scale shrinkage estimates for the state transition probability parameters (ztilde).

traceG

The trace of the projection matrix for each random effect.

References

Burnham, K.P. and White, G.C. 2002. Evaluation of some random effects methodology applicable to bird ringing data. Journal of Applied Statistics 29: 245-264.

McClintock, B.T. 2021. Worth the effort? A practical examination of random effects in hidden Markov models for animal telemetry data. Methods in Ecology and Evolution doi:10.1111/2041-210X.13619.

Examples

## Not run: 
# simulated data with normal random effects
# and binary individual covariate 

nbAnimals <- 5 # should be larger for random effects estimation
obsPerAnimal <- 110
indCov <- rbinom(nbAnimals,1,0.5) # individual covariate
betaCov <- c(-0.5,0.5) # covariate effects
mu <- c(-0.1,0.1) # mean for random effects
sigma <- c(0.2,0.4) # sigma for random effects
beta0 <- cbind(rnorm(nbAnimals,mu[1],sigma[1]),
               rnorm(nbAnimals,mu[2],sigma[2]))

reData <- simData(nbAnimals=nbAnimals,obsPerAnimal=obsPerAnimal,nbStates=2,
                  dist=list(step="gamma"),formula=~0+ID+indCov,
                  Par=list(step=c(1,10,1,2)),
                  beta=rbind(beta0,betaCov),
                  covs=data.frame(indCov=rep(indCov,each=obsPerAnimal)))

# fit null model
nullFit <- fitHMM(reData,nbStates=2,
                  dist=list(step="gamma"),
                  Par0=list(step=c(1,10,1,2)))

# fit covariate model
covFit <- fitHMM(reData,nbStates=2,
                 dist=list(step="gamma"),formula=~indCov,
                 Par0=list(step=c(1,10,1,2)),
                 beta0=rbind(mu,betaCov)) 

# fit fixed effects model
fixFit <- fitHMM(reData,nbStates=2,
                 dist=list(step="gamma"),formula=~0+ID,
                 Par0=list(step=c(1,10,1,2)),
                 beta0=beta0)

# fit random effect model
reFit <- randomEffects(fixFit)

# fit random effect model with individual covariate
reCovFit <- randomEffects(fixFit, Xformula=~indCov)

# compare by AICc
AIC(nullFit,covFit,fixFit,reFit,reCovFit, n=nrow(reData))

## End(Not run)