momentuHMM (version 1.2.0)

MIfitHMM: Fit HMMs to multiple imputation data

Description

Fit a (multivariate) hidden Markov model to multiple imputation data. Multiple imputation is a method for accommodating missing data, temporal-irregularity, or location measurement error in hidden Markov models, where pooled parameter estimates reflect uncertainty attributable to observation error.

Usage

MIfitHMM(miData, nSims, ncores, poolEstimates = TRUE, alpha = 0.95,
  nbStates, dist, Par0, beta0 = NULL, delta0 = NULL, estAngleMean = NULL,
  circularAngleMean = NULL, formula = ~1, formulaDelta = ~1,
  stationary = FALSE, verbose = 0, nlmPar = NULL, fit = TRUE,
  DM = NULL, cons = NULL, userBounds = NULL, workcons = NULL,
  stateNames = NULL, knownStates = NULL, fixPar = NULL, retryFits = 0,
  covNames = NULL, spatialCovs = NULL, centers = NULL, angleCovs = NULL,
  method = "IS", parIS = 1000, dfSim = Inf, grid.eps = 1, crit = 2.5,
  scaleSim = 1, force.quad = TRUE, fullPost = TRUE, dfPostIS = Inf,
  scalePostIS = 1, thetaSamp = NULL)

Arguments

miData

A crwData object, a crwSim object, or a list of momentuHMMData objects.

nSims

Number of imputations in which to fit the HMM using fitHMM. If miData is a list of momentuHMMData objects, nSims cannot exceed the length of miData.

ncores

Number of cores to use for parallel processing.

poolEstimates

Logical indicating whether or not to calculate pooled parameter estimates across the nSims imputations using MIpool. Default: TRUE.

alpha

Significance level for calculating confidence intervals of pooled estimates when poolEstimates=TRUE (see MIpool). Default: 0.95.

nbStates

Number of states of the HMM. See fitHMM.

dist

A named list indicating the probability distributions of the data streams. See fitHMM.

Par0

A named list containing vectors of initial state-dependent probability distribution parameters for each data stream specified in dist. See fitHMM. Par0 may also be a list of length nSims, where each element is a named list containing vectors of initial state-dependent probability distribution parameters for each imputation.

beta0

Initial matrix of regression coefficients for the transition probabilities. See fitHMM. beta0 may also be a list of length nSims, where each element is an initial matrix of regression coefficients for the transition probabilities for each imputation.

delta0

Initial values for the initial distribution of the HMM. See fitHMM. delta0 may also be a list of length nSims, where each element is the initial values for the initial distribution of the HMM for each imputation.

estAngleMean

An optional named list indicating whether or not to estimate the angle mean for data streams with angular distributions ('vm' and 'wrpcauchy'). See fitHMM.

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. See fitHMM.

formula

Regression formula for the transition probability covariates. See fitHMM.

formulaDelta

Regression formula for the initial distribution. See fitHMM.

stationary

FALSE if there are covariates. If TRUE, the initial distribution is considered equal to the stationary distribution. See fitHMM.

verbose

Determines the print level of the fitHMM optimizer. The default value of 0 means that no printing occurs, a value of 1 means that the first and last iterations of the optimization are detailed, and a value of 2 means that each iteration of the optimization is detailed.

nlmPar

List of parameters to pass to the fitHMM optimization function nlm (which should be either 'gradtol', 'stepmax', 'steptol', or 'iterlim' -- see nlm's documentation for more detail)

fit

TRUE if the HMM should be fitted to the data, FALSE otherwise. See fitHMM. If fit=FALSE and miData is a crwData object, then MIfitHMM returns a list containing a momentuHMMData object (if nSims=1) or, if nSims>1, a crwSim object.

DM

An optional named list indicating the design matrices to be used for the probability distribution parameters of each data stream. See fitHMM.

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. See fitHMM.

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. See fitHMM.

workcons

An optional named list of vectors specifying constants to add to the regression coefficients on the working scale for each data stream. See fitHMM.

stateNames

Optional character vector of length nbStates indicating state names.

knownStates

Vector of values of the state process which are known prior to fitting the model (if any). See fitHMM. If miData is a list of momentuHMMData objects, then knownStates can alternatively be a list of vectors containing the known values for the state process for each element of miData.

fixPar

An optional list of vectors indicating parameters which are assumed known prior to fitting the model. See fitHMM.

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.

covNames

Names of any covariates in miData$crwPredict (if miData is a crwData object; otherwise covNames is ignored). See prepData.

spatialCovs

List of raster layer(s) for any spatial covariates not included in miData$crwPredict (if miData is a crwData object; otherwise spatialCovs is ignored). See prepData.

centers

2-column matrix providing the x-coordinates (column 1) and y-coordinates (column 2) for any activity centers (e.g., potential centers of attraction or repulsion) from which distance and angle covariates will be calculated based on realizations of the position process. See prepData. Ignored unless miData is a crwData object.

angleCovs

Character vector indicating the names of any circular-circular regression angular covariates in miData$crwPredict that need conversion from standard direction (in radians relative to the x-axis) to turning angle (relative to previous movement direction) See prepData. Ignored unless miData is a crwData object.

method

Method for obtaining weights for movement parameter samples. See crwSimulator. Ignored unless miData is a crwData object.

parIS

Size of the parameter importance sample. See crwSimulator. Ignored unless miData is a crwData object.

dfSim

Degrees of freedom for the t approximation to the parameter posterior. See 'df' argument in crwSimulator. Ignored unless miData is a crwData object.

grid.eps

Grid size for method="quadrature". See crwSimulator. Ignored unless miData is a crwData object.

crit

Criterion for deciding "significance" of quadrature points (difference in log-likelihood). See crwSimulator. Ignored unless miData is a crwData object.

scaleSim

Scale multiplier for the covariance matrix of the t approximation. See 'scale' argument in crwSimulator. Ignored unless miData is a crwData object.

force.quad

A logical indicating whether or not to force the execution of the quadrature method for large parameter vectors. See crwSimulator. Default: TRUE. Ignored unless miData is a crwData object and method=``quadrature''.

fullPost

Logical indicating whether to draw parameter values as well to simulate full posterior. See crwPostIS. Ignored unless miData is a crwData object.

dfPostIS

Degrees of freedom for multivariate t distribution approximation to parameter posterior. See 'df' argument in crwPostIS. Ignored unless miData is a crwData object.

scalePostIS

Extra scaling factor for t distribution approximation. See 'scale' argument in crwPostIS. Ignored unless miData is a crwData object.

thetaSamp

If multiple parameter samples are available in crwSimulator objects, setting thetaSamp=n will use the nth sample. Defaults to the last. See crwSimulator and crwPostIS. Ignored unless miData is a crwData object.

Value

If nSims>1, poolEstimates=TRUE, and fit=TRUE, a miHMM object, i.e., a list consisting of:

miSum

miSum object returned by MIpool.

HMMfits

List of length nSims comprised of momentuHMM objects.

If poolEstimates=FALSE and fit=TRUE, a list of length nSims consisting of momentuHMM objects is returned.

However, if fit=FALSE and miData is a crwData object, then MIfitHMM returns a crwSim object, i.e., a list containing miData (a list of momentuHMMData objects) and crwSimulator (a list of crwSimulator objects),and most other arguments related to fitHMM are ignored.

Details

miData can either be a crwData object (as returned by crawlWrap), a crwSim object (as returned by MIfitHMM when fit=FALSE), or a list of momentuHMMData objects (e.g., each element of the list as returned by prepData).

If miData is a crwData object, MIfitHMM uses a combination of crwSimulator, crwPostIS, prepData, and fitHMM to draw nSims realizations of the position process and fit the specified HMM to each imputation of the data. The vast majority of MIfitHMM arguments are identical to the corresponding arguments from these functions.

If miData is a crwData object, nSims determines both the number of realizations of the position process to draw (using crwSimulator and crwPostIS) as well as the number of HMM fits.

If miData is a crwSim object or a list of momentuHMMData object(s), the specified HMM will simply be fitted to each of the momentuHMMData objects and all arguments related to crwSimulator, crwPostIS, or prepData are ignored.

References

Hooten M.B., Johnson D.S., McClintock B.T., Morales J.M. 2017. Animal Movement: Statistical Models for Telemetry Data. CRC Press, Boca Raton.

McClintock B.T. 2017. Incorporating telemetry error into hidden Markov movement models using multiple imputation. Journal of Agricultural, Biological, and Environmental Statistics.

See Also

crawlWrap, crwPostIS, crwSimulator, fitHMM, getParDM, MIpool, prepData

Examples

# NOT RUN {
# Don't run because it takes too long on a single core
# }
# NOT RUN {
# extract simulated obsData from example data
obsData <- miExample$obsData

# extract crwMLE inputs from example data
inits <- miExample$inits # initial state
err.model <- miExample$err.model # error ellipse model

# create crwData object by fitting crwMLE models to obsData and predict locations 
# at default intervals for both individuals
crwOut <- crawlWrap(obsData=obsData,ncores=1,
         theta=c(4,0),fixPar=c(1,1,NA,NA),
         initial.state=inits,
         err.model=err.model)

# HMM specifications
nbStates <- 2
stepDist <- "gamma"
angleDist <- "vm"
mu0 <- c(20,70)
sigma0 <- c(10,30)
kappa0 <- c(1,1)
stepPar0 <- c(mu0,sigma0)
anglePar0 <- c(-pi/2,pi/2,kappa0)
formula <- ~cov1+cos(cov2)
nbCovs <- 2
beta0 <- matrix(c(rep(-1.5,nbStates*(nbStates-1)),rep(0,nbStates*(nbStates-1)*nbCovs)),
                nrow=nbCovs+1,byrow=TRUE)

# first fit HMM to best predicted position process
bestData<-prepData(crwOut,covNames=c("cov1","cov2"))
bestFit<-fitHMM(bestData,
                nbStates=nbStates,dist=list(step=stepDist,angle=angleDist),
                Par0=list(step=stepPar0,angle=anglePar0),beta0=beta0,
                formula=formula,estAngleMean=list(angle=TRUE))
            
print(bestFit)

# extract estimates from 'bestFit'
bPar0 <- getPar(bestFit)

# Fit nSims=5 imputations of the position process
miFits<-MIfitHMM(miData=crwOut,nSims=5,ncores=1,
                  nbStates=nbStates,dist=list(step=stepDist,angle=angleDist),
                  Par0=bPar0$Par,beta0=bPar0$beta,delta0=bPar0$delta,
                  formula=formula,estAngleMean=list(angle=TRUE),
                  covNames=c("cov1","cov2"))

# print pooled estimates
print(miFits)
# }
# NOT RUN {
# }