MIpool {momentuHMM}

Calculate pooled parameter estimates and states across multiple imputations

Description

Calculate pooled parameter estimates and states across multiple imputations

Usage

MIpool(im, alpha = 0.95, ncores = 1, covs = NULL, na.rm = FALSE)

Arguments

im

List comprised of momentuHMM or momentuHierHMM objects

alpha

Significance level for calculating confidence intervals of pooled estimates (including location error ellipses). Default: 0.95.

ncores

Number of cores to use for parallel processing. Default: 1 (no parallel processing).

covs

Data frame consisting of a single row indicating the covariate values to be used in the calculation of pooled natural parameters. For any covariates that are not specified using covs, the means of the covariate(s) across the imputations are used (unless the covariate is a factor, in which case the first factor in the data is used). By default, no covariates are specified.

na.rm

Logical indicating whether or not to exclude model fits with NA parameter estimates or standard errors from pooling. Default: FALSE.

Details

Pooled estimates, standard errors, and confidence intervals are calculated using standard multiple imputation formulas. Working scale parameters are pooled using MIcombine and t-distributed confidence intervals. Natural scale parameters and normally-distributed confidence intervals are calculated by transforming the pooled working scale parameters and, if applicable, are based on covariate means across all imputations (and/or values specified in covs).

The calculation of pooled error ellipses uses dataEllipse from the car package. The suggested package car is not automatically imported by momentuHMM and must be installed in order to calculate error ellipses. A warning will be triggered if the car package is required but not installed.

Note that pooled estimates for timeInStates and stateProbs do not include within-model uncertainty and are based entirely on across-model variability.

Value

A miSum object, i.e., a list comprised of model and pooled parameter summaries, including data (averaged across imputations), conditions, Par, and MIcombine (as returned by MIcombine for working parameters).

miSum$Par is a list comprised of:

beta

Pooled estimates for the working parameters

real

Estimates for the natural parameters based on pooled working parameters and covariate means (or covs) across imputations (if applicable)

timeInStates

The proportion of time steps assigned to each state

states

The most freqent state assignment for each time step based on the viterbi algorithm for each model fit

stateProbs

Pooled state probability estimates for each time step

mixtureProbs

Pooled mixture probabilities for each individual (only applies if mixtures>1)

hierStateProbs

Pooled state probability estimates for each time step at each level of the hierarchy (only applies if im is comprised of momentuHierHMM objects)

Examples

## Not run: 
# Extract data and crawl inputs from miExample
obsData <- miExample$obsData

# error ellipse model
err.model <- list(x= ~ ln.sd.x - 1, y =  ~ ln.sd.y - 1, rho =  ~ error.corr)

# Fit crawl to obsData
crwOut <- crawlWrap(obsData,theta=c(4,0),fixPar=c(1,1,NA,NA),
                    err.model=err.model)
                    
# Fit four imputations
bPar <- miExample$bPar
HMMfits <- MIfitHMM(crwOut,nSims=4,poolEstimates=FALSE,
                   nbStates=2,dist=list(step="gamma",angle="vm"),
                   Par0=bPar$Par,beta0=bPar$beta,
                   formula=~cov1+cos(cov2),
                   estAngleMean=list(angle=TRUE),
                   covNames=c("cov1","cov2"))
                   
# Pool estimates
miSum <- MIpool(HMMfits)
print(miSum)

## End(Not run)