ddwell: State dwell-time distributions of periodically inhomogeneous...

In LaMa: Fast Numerical Maximum Likelihood Estimation for Latent Markov Models

State dwell-time distributions of periodically inhomogeneous Markov chains

Description

Computes the dwell-time distribution of a periodically inhomogeneous Markov chain for a given transition probability matrix.

Usage

ddwell(x, Gamma, time = NULL, state = NULL)

Arguments

x	vector of (non-negative) dwell times to compute the dwell-time distribution for
Gamma	array of L unique transition probability matrices of a periodically inhomogeneous Markov chain, with dimensions c(N,N,L), where N is the number of states and L is the cycle length
time	integer vector of time points in 1:L at which to compute the dwell-time distribution. If NULL, the overall dwell-time distribution is computed.
state	integer vector of state indices for which to compute the dwell-time distribution. If NULL, dwell-time distributions for all states are returned in a named list.

Details

For Markov chains whose transition probabilities vary only periodically, which is achieved for example by expressing the transition probability matrix as a periodic function of the time of day using tpm_p or cosinor, the probability distribution of time spent in a state can be computed analytically. This function computes said distribution, either for a specific time point (conditioning on transitioning into the state at that time point) or for the overall distribution (conditioning on transitioning into the state at any time point).

Value

either time-varying dwell-time distribution(s) if time is specified, or overall dwell-time distribution if time is NULL. If more than one state is specified, a named list over states is returned.

References

Koslik, J. O., Feldmann, C. C., Mews, S., Michels, R., & Langrock, R. (2023). Inference on the state process of periodically inhomogeneous hidden Markov models for animal behavior. arXiv preprint arXiv:2312.14583.

Examples

# setting parameters for trigonometric link
beta = matrix(c(-1, 2, -1, -2, 1, -1), nrow = 2, byrow = TRUE)
Gamma = tpm_p(beta = beta, degree = 1)

# at specific times and for specific state
ddwell(1:20, Gamma, time = 1:4, state = 1)
# results in 4x20 matrix

# or overall distribution for all states
ddwell(1:20, Gamma)
# results in list of length 2, each element is a vector of length 20

LaMa documentation built on Nov. 5, 2025, 6:42 p.m.