# Fitting a two-state movement HMM in R
# https://tidyecology.com/posts/two-state-movement-hmm/
#
# The R code of this Tidy Ecology tutorial, chunk by chunk, in the order of the post.
# Run it top to bottom in a fresh R session. Code the post shows but does not run
# is commented out. The prose, and the numbers it quotes, are in the post itself.
# Post last modified: 2026-10-15

## ---- setup ----
library(ggplot2)
library(dplyr)
library(tidyr)

pal <- list(ink = "#16241d", body = "#2c3a31", forest = "#275139", label = "#46604a",
            sage = "#93a87f", paper = "#f5f4ee", line = "#dad9ca", faint = "#5d6b61")
state_cols <- c(Encamped = "#cda23f", Transiting = "#275139")
theme_te <- function(base_size = 12) {
  theme_minimal(base_size = base_size) +
    theme(plot.background = element_rect(fill = pal$paper, colour = NA),
          panel.background = element_rect(fill = pal$paper, colour = NA),
          panel.grid.major = element_line(colour = pal$line, linewidth = 0.3),
          panel.grid.minor = element_blank(),
          axis.text = element_text(colour = pal$faint), axis.title = element_text(colour = pal$body),
          plot.title = element_text(colour = pal$ink, face = "bold"),
          plot.subtitle = element_text(colour = pal$label),
          strip.text = element_text(colour = pal$ink, face = "bold"),
          legend.text = element_text(colour = pal$body), legend.position = "top")
}

# von Mises density (besselI) and a Best-Fisher (1979) sampler
dvm <- function(theta, mu, kappa) exp(kappa * cos(theta - mu)) / (2 * pi * besselI(kappa, 0))
rvm <- function(n, mu, kappa) {
  mu <- rep(mu, length.out = n); kappa <- rep(kappa, length.out = n); out <- numeric(n)
  for (i in 1:n) {
    k <- kappa[i]; a <- 1 + sqrt(1 + 4 * k^2); b <- (a - sqrt(2 * a)) / (2 * k); r <- (1 + b^2) / (2 * b)
    repeat {
      u1 <- runif(1); u2 <- runif(1); u3 <- runif(1)
      z <- cos(pi * u1); f <- (1 + r * z) / (r + z); cc <- k * (r - f)
      if (cc * (2 - cc) - u2 > 0 || log(cc / u2) + 1 - cc >= 0) { out[i] <- sign(u3 - 0.5) * acos(f) + mu[i]; break }
    }
  }
  ((out + pi) %% (2 * pi)) - pi
}

## ---- simulate ----
Gamma_true <- matrix(c(0.90, 0.10, 0.15, 0.85), 2, 2, byrow = TRUE)
shape_true <- c(2, 4); scale_true <- c(20, 50); kappa_true <- c(0.7, 3.0)
N <- 2; Tn <- 500
delta_true <- solve(t(diag(N) - Gamma_true + 1), rep(1, N))   # stationary distribution

set.seed(4517)
S <- integer(Tn); S[1] <- sample(1:N, 1, prob = delta_true)
for (t in 2:Tn) S[t] <- sample(1:N, 1, prob = Gamma_true[S[t - 1], ])
step <- rgamma(Tn, shape = shape_true[S], scale = scale_true[S])
phi  <- rvm(Tn, 0, kappa_true[S]); turn <- phi; turn[1] <- NA   # first turn undefined

# build the (x, y) track by integrating the turning angles into a heading
heading <- numeric(Tn); heading[1] <- 0
for (t in 2:Tn) heading[t] <- heading[t - 1] + phi[t]
x <- numeric(Tn + 1); y <- numeric(Tn + 1)
for (t in 1:Tn) { x[t + 1] <- x[t] + step[t] * cos(heading[t]); y[t + 1] <- y[t] + step[t] * sin(heading[t]) }

## ---- likelihood ----
w2n <- function(w) {
  g12 <- plogis(w[1]); g21 <- plogis(w[2])
  list(Gamma = matrix(c(1 - g12, g12, g21, 1 - g21), 2, 2, byrow = TRUE),
       shape = exp(w[c(3, 5)]), scale = exp(w[c(4, 6)]), kappa = exp(w[c(7, 8)]))
}
allprobs <- function(p) {
  ap <- matrix(1, Tn, 2)
  for (j in 1:2) ap[, j] <- dgamma(step, shape = p$shape[j], scale = p$scale[j]) *
    ifelse(is.na(turn), 1, dvm(turn, 0, p$kappa[j]))
  ap
}
nll <- function(w) {
  p <- w2n(w); ap <- allprobs(p)
  delta <- solve(t(diag(2) - p$Gamma + 1), rep(1, 2))
  foo <- delta * ap[1, ]; s <- sum(foo); ls <- log(s); foo <- foo / s
  for (t in 2:Tn) { foo <- (foo %*% p$Gamma) * ap[t, ]; s <- sum(foo); ls <- ls + log(s); foo <- foo / s }
  -ls
}

## ---- fit ----
w0 <- c(qlogis(0.1), qlogis(0.15), log(2), log(25), log(4), log(45), log(0.8), log(2.5))
fit0 <- optim(w0, nll, method = "Nelder-Mead", control = list(maxit = 5000, reltol = 1e-12))
fit  <- optim(fit0$par, nll, method = "BFGS", control = list(maxit = 1000, reltol = 1e-12))
p_hat <- w2n(fit$par)
delta_hat <- solve(t(diag(2) - p_hat$Gamma + 1), rep(1, 2))

## ---- viterbi ----
viterbi <- function(p) {
  ap <- allprobs(p); delta <- solve(t(diag(2) - p$Gamma + 1), rep(1, 2))
  xi <- matrix(0, Tn, 2); foo <- delta * ap[1, ]; xi[1, ] <- foo / sum(foo)
  for (t in 2:Tn) { foo <- apply(xi[t - 1, ] * p$Gamma, 2, max) * ap[t, ]; xi[t, ] <- foo / sum(foo) }
  iv <- integer(Tn); iv[Tn] <- which.max(xi[Tn, ])
  for (t in (Tn - 1):1) iv[t] <- which.max(p$Gamma[, iv[t + 1]] * xi[t, ])
  iv
}
vit <- viterbi(p_hat)

## ---- fig-track ----
seg <- data.frame(x = x[1:Tn], y = y[1:Tn], xend = x[2:(Tn + 1)], yend = y[2:(Tn + 1)],
                  state = factor(c("Encamped", "Transiting")[vit], levels = names(state_cols)))
ggplot(seg) +
  geom_segment(aes(x, y, xend = xend, yend = yend, colour = state), linewidth = 0.5) +
  geom_point(data = subset(seg, state == "Encamped"), aes(x, y, colour = state), size = 0.5, alpha = 0.5) +
  scale_colour_manual(values = state_cols, name = NULL) + coord_equal() +
  labs(title = "Decoded movement track", subtitle = "Viterbi state sequence from a two-state HMM",
       x = "Easting (m)", y = "Northing (m)") + theme_te()

## ---- naive ----
grid <- seq(min(step), max(step), length.out = 20000)
d1 <- delta_hat[1] * dgamma(grid, shape = p_hat$shape[1], scale = p_hat$scale[1])
d2 <- delta_hat[2] * dgamma(grid, shape = p_hat$shape[2], scale = p_hat$scale[2])
cross <- grid[which(diff(sign(d2 - d1)) != 0)]
thr <- cross[cross > p_hat$shape[1] * p_hat$scale[1]][1]
naive <- ifelse(step > thr, 2, 1)
switches <- function(z) sum(diff(z) != 0)

## ---- fig-emissions ----
sx <- seq(0, max(step), length.out = 300); tx <- seq(-pi, pi, length.out = 300)
obs <- rbind(data.frame(val = step, panel = "Step length (m)"),
             data.frame(val = turn[!is.na(turn)], panel = "Turning angle (rad)"))
cur <- rbind(
  data.frame(val = sx, dens = delta_hat[1] * dgamma(sx, p_hat$shape[1], scale = p_hat$scale[1]), state = "Encamped",  panel = "Step length (m)"),
  data.frame(val = sx, dens = delta_hat[2] * dgamma(sx, p_hat$shape[2], scale = p_hat$scale[2]), state = "Transiting", panel = "Step length (m)"),
  data.frame(val = tx, dens = delta_hat[1] * dvm(tx, 0, p_hat$kappa[1]), state = "Encamped",  panel = "Turning angle (rad)"),
  data.frame(val = tx, dens = delta_hat[2] * dvm(tx, 0, p_hat$kappa[2]), state = "Transiting", panel = "Turning angle (rad)"))
ggplot() +
  geom_histogram(data = obs, aes(val, after_stat(density)), bins = 40, fill = pal$sage, alpha = 0.32) +
  geom_line(data = cur, aes(val, dens, colour = state), linewidth = 0.9) +
  facet_wrap(~panel, scales = "free") +
  scale_colour_manual(values = state_cols, name = NULL) +
  labs(title = "State-dependent emission distributions",
       subtitle = "Fitted gamma (step length) and von Mises (turning angle) per state",
       x = NULL, y = "Density") + theme_te()
