# Covariates in a movement HMM
# https://tidyecology.com/posts/hmm-transition-covariates/
#
# 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)
library(tidyr)

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),
          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
}
# time-varying two-state transition matrix from the covariate
mkG <- function(b, x) { g12 <- plogis(b[1] + b[2] * x); g21 <- plogis(b[3] + b[4] * x)
  matrix(c(1 - g12, g12, g21, 1 - g21), 2, 2, byrow = TRUE) }

## ---- sci-tex-helper ----
sci_tex <- function(x, digits = 2) {
  s <- formatC(x, format = "e", digits = digits)
  paste0("$", sub("e.*", "", s), " \\times 10^{", as.integer(sub(".*e", "", s)), "}$")
}

## ---- simulate ----
b_true <- c(-2.20, 1.60, -1.75, -1.30)              # b0_12, b1_12, b0_21, b1_21
shape_true <- c(2, 4); scale_true <- c(20, 50); kappa_true <- c(0.7, 3.0)
Tn <- 1200
hour <- ((0:(Tn - 1)) * 0.5) %% 24
cov  <- cos(2 * pi * (hour - 12) / 24)      # +1 at midday, -1 at midnight

set.seed(7731)
S <- integer(Tn)
G1 <- mkG(b_true, cov[1]); d1 <- solve(t(diag(2) - G1 + 1), rep(1, 2)); S[1] <- sample(1:2, 1, prob = d1)
for (t in 2:Tn) S[t] <- sample(1:2, 1, prob = mkG(b_true, cov[t])[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

## ---- likelihood ----
nll_cov <- function(w, step, turn, cov) {
  b <- w[1:4]; sh <- exp(w[5:6]); sc <- exp(w[7:8]); ka <- exp(w[9:10]); Tn <- length(step)
  ap <- matrix(1, Tn, 2)
  for (j in 1:2) ap[, j] <- dgamma(step, sh[j], scale = sc[j]) * ifelse(is.na(turn), 1, dvm(turn, 0, ka[j]))
  if (any(!is.finite(ap))) return(1e10)
  G1 <- mkG(b, cov[1]); delta <- solve(t(diag(2) - G1 + 1), rep(1, 2))
  foo <- delta * ap[1, ]; s <- sum(foo); if (s <= 0) return(1e10); ls <- log(s); foo <- foo / s
  for (t in 2:Tn) { Gt <- mkG(b, cov[t]); foo <- (foo %*% Gt) * ap[t, ]; s <- sum(foo); if (s <= 0) return(1e10); ls <- ls + log(s); foo <- foo / s }
  -ls
}
nll_hom <- function(w, step, turn) nll_cov(c(w[1], 0, w[2], 0, w[3:8]), step, turn, rep(0, length(step)))

## ---- fit ----
w0c <- c(-2, 1, -1.5, -1, log(2), log(4), log(20), log(50), log(0.7), log(3))
fc <- optim(w0c, nll_cov, step = step, turn = turn, cov = cov, method = "Nelder-Mead",
            control = list(maxit = 4000, reltol = 1e-11))
fc <- optim(fc$par, nll_cov, step = step, turn = turn, cov = cov, method = "BFGS",
            control = list(maxit = 300, reltol = 1e-12))
w0h <- c(-2, -1.5, log(2), log(4), log(20), log(50), log(0.7), log(3))
fh <- optim(w0h, nll_hom, step = step, turn = turn, method = "Nelder-Mead",
            control = list(maxit = 4000, reltol = 1e-11))
fh <- optim(fh$par, nll_hom, step = step, turn = turn, method = "BFGS",
            control = list(maxit = 300, reltol = 1e-12))
bh <- fc$par[1:4]

## ---- ic ----
kC <- 10; kH <- 8
aic_c <- 2 * fc$value + 2 * kC; aic_h <- 2 * fh$value + 2 * kH
lr <- 2 * (fh$value - fc$value)

## ---- fig-response ----
hr <- seq(0, 24, length.out = 200); cx <- cos(2 * pi * (hr - 12) / 24)
mkg <- function(b, x, which) if (which == 12) plogis(b[1] + b[2] * x) else plogis(b[3] + b[4] * x)
g12h <- plogis(fh$par[1]); g21h <- plogis(fh$par[2])
dfp <- rbind(
  data.frame(hour = hr, prob = mkg(bh, cx, 12), tr = "Start transiting", src = "Covariate model"),
  data.frame(hour = hr, prob = mkg(bh, cx, 21), tr = "Settle",          src = "Covariate model"),
  data.frame(hour = hr, prob = mkg(b_true, cx, 12), tr = "Start transiting", src = "Truth"),
  data.frame(hour = hr, prob = mkg(b_true, cx, 21), tr = "Settle",          src = "Truth"))
hom <- data.frame(tr = c("Start transiting", "Settle"), y = c(g12h, g21h))
ggplot(dfp, aes(hour, prob, colour = tr, linetype = src)) +
  geom_hline(data = hom, aes(yintercept = y, colour = tr), linetype = "dotted", linewidth = 0.6) +
  geom_line(linewidth = 0.9) +
  scale_colour_manual(values = c("Start transiting" = "#b5534e", "Settle" = "#275139"), name = NULL) +
  scale_linetype_manual(values = c("Covariate model" = "solid", "Truth" = "22"), name = NULL) +
  scale_x_continuous(breaks = seq(0, 24, 6)) +
  labs(title = "Transition probabilities vary with time of day",
       subtitle = "Dotted lines: the single constant each transition takes in a homogeneous model",
       x = "Hour of day", y = "Transition probability") + theme_te()

## ---- fig-budget ----
occP2 <- function(b, x) {   # expected share transiting at each half-hour step of a repeating day
  Gs <- lapply(x, function(xx) mkG(b, xx))
  p <- Re(eigen(t(Reduce(`%*%`, Gs)))$vectors[, 1]); p <- p / sum(p)   # repeats from day to day
  out <- numeric(length(x))
  for (i in seq_along(Gs)) { p <- as.vector(p %*% Gs[[i]]); out[i] <- p[2] }
  out
}
hd <- seq(0, 23.5, by = 0.5); xd <- cos(2 * pi * (hd - 12) / 24)
budget <- data.frame(hour = hd, model = occP2(bh, xd), truth = occP2(b_true, xd))
homP <- g12h / (g12h + g21h)
brks <- cut(hour, breaks = seq(0, 24, 2), include.lowest = TRUE)
emp <- data.frame(hour = tapply(hour, brks, mean), p = tapply(S == 2, brks, mean))
ggplot(budget, aes(hour)) +
  geom_hline(yintercept = homP, linetype = "dotted", colour = pal$faint, linewidth = 0.7) +
  annotate("text", x = 1.2, y = homP + 0.03, label = "homogeneous", hjust = 0, size = 3.2, colour = pal$faint) +
  geom_line(aes(y = truth), linetype = "22", colour = pal$sage, linewidth = 0.9) +
  geom_line(aes(y = model), colour = "#275139", linewidth = 1.1) +
  geom_point(data = emp, aes(hour, p), colour = "#b5534e", size = 2.2) +
  scale_x_continuous(breaks = seq(0, 24, 6)) + ylim(0, 1) +
  labs(title = "Diurnal activity budget",
       subtitle = "Expected share transiting: model (green), truth (pale dashed),\ntrue states binned in two-hour blocks (points)",
       x = "Hour of day", y = "P(transiting)") + theme_te()
