# Checking a movement HMM
# https://tidyecology.com/posts/checking-a-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-01

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

pal <- list(ink = "#16241d", body = "#2c3a31", forest = "#275139", label = "#46604a",
            sage = "#93a87f", paper = "#f5f4ee", line = "#dad9ca", faint = "#5d6b61")
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")
}
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
}

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); Tn <- 500
delta_true <- solve(t(diag(2) - Gamma_true + 1), rep(1, 2))
set.seed(4517)
S <- integer(Tn); S[1] <- sample(1:2, 1, prob = delta_true)
for (t in 2:Tn) S[t] <- sample(1:2, 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

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 }
w0 <- c(qlogis(0.1), qlogis(0.15), log(2), log(25), log(4), log(45), log(0.8), log(2.5))
fit <- optim(w0, nll, method = "Nelder-Mead", control = list(maxit = 5000, reltol = 1e-12))
fit <- optim(fit$par, nll, method = "BFGS", control = list(maxit = 1000, reltol = 1e-12))
p2 <- w2n(fit$par)

## ---- fwd-bwd ----
fwd_bwd <- function(p) {
  ap <- allprobs(p); delta <- solve(t(diag(2) - p$Gamma + 1), rep(1, 2))
  phi <- matrix(NA, Tn, 2); cvec <- numeric(Tn)
  foo <- delta * ap[1, ]; cvec[1] <- sum(foo); phi[1, ] <- foo / cvec[1]
  for (t in 2:Tn) { foo <- (phi[t - 1, ] %*% p$Gamma) * ap[t, ]; cvec[t] <- sum(foo); phi[t, ] <- foo / cvec[t] }
  bt <- matrix(NA, Tn, 2); bt[Tn, ] <- 1
  for (t in (Tn - 1):1) bt[t, ] <- as.numeric(p$Gamma %*% (ap[t + 1, ] * bt[t + 1, ])) / cvec[t + 1]
  post <- phi * bt; post <- post / rowSums(post)
  xi <- matrix(NA, Tn, 2); xi[1, ] <- delta
  for (t in 2:Tn) xi[t, ] <- as.numeric(phi[t - 1, ] %*% p$Gamma)
  list(post = post, xi = xi, llk = sum(log(cvec)))
}
fb <- fwd_bwd(p2)

## ---- 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(p2)
loc <- apply(fb$post, 1, which.max)

## ---- fig-uncertainty ----
maxpost <- apply(fb$post, 1, max)
w <- 1:170
dfd <- data.frame(t = w, post = fb$post[w, 2], vit = as.numeric(vit[w] == 2),
                  truth = factor(ifelse(S[w] == 2, "Transiting", "Encamped"), levels = c("Encamped", "Transiting")))
unc <- dfd[dfd$post > 0.2 & dfd$post < 0.8, ]
ggplot(dfd, aes(t)) +
  geom_tile(aes(y = -0.06, fill = truth), height = 0.06) +
  geom_rect(data = unc, aes(xmin = t - 0.5, xmax = t + 0.5, ymin = 0, ymax = 1), fill = "#cda23f", alpha = 0.18, inherit.aes = FALSE) +
  geom_step(aes(y = vit), colour = pal$faint, linewidth = 0.5, direction = "mid") +
  geom_line(aes(y = post), colour = "#275139", linewidth = 0.9) +
  scale_fill_manual(values = c(Encamped = "#cda23f", Transiting = "#275139"), name = "True state") +
  scale_y_continuous(breaks = c(0, 0.5, 1)) +
  labs(title = "Decoding uncertainty the Viterbi path hides",
       subtitle = "Green: posterior P(transiting); grey step: single Viterbi path\nBand: true state; shaded: ambiguous steps",
       x = "Step index", y = "P(transiting)") + theme_te()

## ---- resid-step ----
Fstep2 <- fb$xi[, 1] * pgamma(step, shape = p2$shape[1], scale = p2$scale[1]) +
          fb$xi[, 2] * pgamma(step, shape = p2$shape[2], scale = p2$scale[2])
r_step2 <- qnorm(pmin(pmax(Fstep2, 1e-10), 1 - 1e-10))
qqcor <- function(r) cor(sort(r), qnorm(ppoints(length(r))))
acf1  <- function(r) acf(r, plot = FALSE, lag.max = 1)$acf[2]

## ---- resid-one ----
nll1 <- function(w) { sh <- exp(w[1]); sc <- exp(w[2]); ka <- exp(w[3])
  d <- dgamma(step, shape = sh, scale = sc) * ifelse(is.na(turn), 1, dvm(turn, 0, ka))
  -sum(log(pmax(d, 1e-300))) }
f1 <- optim(c(log(mean(step)^2 / var(step)), log(var(step) / mean(step)), log(1)), nll1,
            method = "Nelder-Mead", control = list(maxit = 2000, reltol = 1e-11))
p1 <- list(shape = exp(f1$par[1]), scale = exp(f1$par[2]), kappa = exp(f1$par[3]))
r_step1 <- qnorm(pmin(pmax(pgamma(step, shape = p1$shape, scale = p1$scale), 1e-10), 1 - 1e-10))
sw_p1 <- shapiro.test(r_step1)$p.value; sw_p2 <- shapiro.test(r_step2)$p.value

## ---- fig-qq ----
qqdat <- function(r, lab) data.frame(theo = qnorm(ppoints(length(r))), samp = sort(r), model = lab)
qq <- rbind(qqdat(r_step2, "Two-state model"), qqdat(r_step1, "One-state model"))
qq$model <- factor(qq$model, levels = c("Two-state model", "One-state model"))
ann <- data.frame(model = factor(c("Two-state model", "One-state model"), levels = levels(qq$model)),
                  lab = c(paste0("lag-1 ACF = ", round(acf1(r_step2), 2)),
                          paste0("lag-1 ACF = ", round(acf1(r_step1), 2))))
ggplot(qq, aes(theo, samp)) +
  geom_abline(slope = 1, intercept = 0, colour = pal$faint, linetype = "dashed") +
  geom_point(colour = "#275139", size = 0.8, alpha = 0.6) +
  geom_text(data = ann, aes(x = -2.7, y = 3.1, label = lab), hjust = 0, size = 3.4, colour = pal$ink) +
  facet_wrap(~model) +
  labs(title = "Pseudo-residual check of the step distribution",
       subtitle = "The one-state model leaves strong residual autocorrelation the two-state model removes",
       x = "Theoretical normal quantile", y = "Pseudo-residual") + theme_te()

## ---- resid-turn ----
gg <- seq(-pi, pi, length.out = 4000)
vmcdf_fun <- function(kappa) {
  dens <- dvm(gg, 0, kappa)
  cdf <- c(0, cumsum((dens[-1] + dens[-length(dens)]) / 2 * diff(gg))); cdf <- cdf / cdf[length(cdf)]
  approxfun(gg, cdf, rule = 2)
}
c1 <- vmcdf_fun(p2$kappa[1]); c2 <- vmcdf_fun(p2$kappa[2]); ok <- !is.na(turn)
Fturn <- fb$xi[ok, 1] * c1(turn[ok]) + fb$xi[ok, 2] * c2(turn[ok])
r_turn2 <- qnorm(pmin(pmax(Fturn, 1e-10), 1 - 1e-10))
