getTrProbs: Transition probability matrix

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

Transition probability matrix

Description

Computation of the transition probability matrix for each time step as a function of the covariates and the regression parameters.

Usage

getTrProbs(data, ...)

## Default S3 method:
getTrProbs(
  data,
  nbStates,
  beta,
  workBounds = NULL,
  formula = ~1,
  mixtures = 1,
  betaRef = NULL,
  stateNames = NULL,
  getCI = FALSE,
  covIndex = NULL,
  alpha = 0.95,
  ...
)

## S3 method for class 'hierarchical'
getTrProbs(
  data,
  hierStates,
  hierBeta,
  workBounds = NULL,
  hierFormula = NULL,
  mixtures = 1,
  hierDist,
  getCI = FALSE,
  covIndex = NULL,
  alpha = 0.95,
  ...
)

Arguments

data	momentuHMM object, momentuHierHMM object, miSum object, miHMM object, momentuHMMData object, momentuHierHMMData object, or a data frame containing the covariate values. If a data frame is provided, then either nbStates must be specified (for a regular HMM) or hierStates and hierDist must be specified (for a hierarchical HMM).
...	further arguments passed to or from other methods; most are ignored if data is a momentuHMM or momentuHierHMM object
nbStates	Number of states. Ignored unless data is a data frame.
beta	Matrix of regression coefficients for the transition probabilities
workBounds	An optional named list of 2-column matrices specifying bounds on the working scale of the transition probability parameters ('beta' and, for recharge models, 'g0' and 'theta'). workBounds$beta must be a k x 2 matrix, where k=length(beta). The first column pertains to the lower bound and the second column the upper bound. Ignored unless data is a data frame.
formula	Regression formula for the transition probability covariates. Ignored unless data is a data frame.
mixtures	Number of mixtures for the state transition probabilities. Ignored unless data is a data frame.
betaRef	Indices of reference elements for t.p.m. multinomial logit link. Ignored unless data is a data frame.
stateNames	Optional character vector of length nbStates indicating state names. Ignored unless data is a data frame.
getCI	Logical indicating whether to calculate standard errors and logit-transformed confidence intervals based on fitted momentuHMM or momentuHierHMM object. Default: FALSE.
covIndex	Integer vector indicating specific rows of the data to be used in the calculations. This can be useful for reducing unnecessarily long computation times (paricularly when getCI=TRUE), e.g., when formula includes factor covariates (such as ID) but no temporal covariates. Ignored if data is not a momentuHMM, momentuHierHMM, miSum, or miHMM object.
alpha	Significance level of the confidence intervals (if getCI=TRUE). Default: 0.95 (i.e. 95% CIs).
hierStates	A hierarchical model structure Node for the states ('state'). See fitHMM.
hierBeta	A hierarchical data structure Node for the matrix of regression coefficients for the transition probabilities at each level of the hierarchy, including initial values ('beta'), parameter equality constraints ('betaCons'), fixed parameters ('fixPar'), and working scale bounds ('workBounds'). See details.
hierFormula	A hierarchical formula structure for the transition probability covariates for each level of the hierarchy ('formula'). See fitHMM.
hierDist	A hierarchical data structure Node for the data streams ('dist'). See fitHMM.

Value

If mixtures=1, an array of dimension nbStates x nbStates x nrow(data) containing the t.p.m for each observation in data. If mixtures>1, a list of length mixtures, where each element is an array of dimension nbStates x nbStates x nrow(data) containing the t.p.m for each observation in data.

If getCI=TRUE then a list of arrays is returned (with elements est, se, lower, and upper).

If a hierarchical HMM structure is provided, then a hierarchical data structure containing the state transition probabilities for each time step at each level of the hierarchy ('gamma') is returned.

Examples

m <- example$m
trProbs <- getTrProbs(m)

# equivalent
trProbs <- getTrProbs(m$data,nbStates=2,beta=m$mle$beta,formula=m$conditions$formula)

## Not run: 
# calculate SEs and 95% CIs
trProbsSE <- getTrProbs(m, getCI=TRUE)

# plot estimates and CIs for each state transition
par(mfrow=c(2,2))
for(i in 1:2){
  for(j in 1:2){
    plot(trProbsSE$est[i,j,],type="l", 
         ylim=c(0,1), ylab=paste(i,"->",j))
    arrows(1:dim(trProbsSE$est)[3],
           trProbsSE$lower[i,j,],
           1:dim(trProbsSE$est)[3],
           trProbsSE$upper[i,j,],
           length=0.025, angle=90, code=3, col=gray(.5), lwd=1.3)
  }
}

# limit calculations to first 10 observations
trProbsSE_10 <- getTrProbs(m, getCI=TRUE, covIndex=1:10)

## End(Not run)

momentuHMM documentation built on Oct. 19, 2022, 1:07 a.m.