MIpool: Calculate pooled parameter estimates and states across...

In bmcclintock/momentuHMM: Maximum Likelihood Analysis of Animal Movement Behavior Using Multivariate Hidden Markov Models

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)

bmcclintock/momentuHMM documentation built on Oct. 26, 2022, 1 a.m.