# Checking multi-state models
# https://tidyecology.com/posts/checking-multistate-models/
#
# 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-07

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

theme_te <- function(bs = 12) theme_minimal(base_size = bs) + theme(
  text = element_text(colour = "#2c3a31"),
  plot.title = element_text(colour = "#16241d", face = "bold", size = rel(1.05)),
  plot.subtitle = element_text(colour = "#5d6b61", size = rel(0.9)),
  axis.title = element_text(colour = "#46604a"), axis.text = element_text(colour = "#46604a"),
  panel.grid.major = element_line(colour = "#dad9ca", linewidth = 0.3),
  panel.grid.minor = element_blank(),
  plot.background = element_rect(fill = "#f5f4ee", colour = NA),
  panel.background = element_rect(fill = "#f5f4ee", colour = NA),
  strip.text = element_text(colour = "#16241d", face = "bold"),
  legend.position = "bottom", legend.title = element_blank())
forest <- "#275139"; brick <- "#b5534e"; ink <- "#16241d"; gold <- "#c9b458"

phi_t <- 0.78; psiAB_t <- 0.30; psiBA_t <- 0.30; p_t <- 0.65
k <- 9; nA0 <- 360; nB0 <- 340; N <- nA0 + nB0
init_state <- c(rep(1L, nA0), rep(2L, nB0))

## ---- dgp ----
sim_ms <- function(mem, p, seed) {
  set.seed(seed)
  y <- matrix(1L, N, k)
  for (i in 1:N) {
    s <- init_state[i]; sprev <- s; y[i, 1] <- if (s == 1L) 2L else 3L
    for (t in 2:k) {
      if (s == 3L) { y[i, t] <- 1L; next }
      pAB <- psiAB_t; pBA <- psiBA_t
      if (sprev != s && sprev != 3L) {              # just switched: raise return
        if (s == 2L && sprev == 1L) pBA <- min(1, psiBA_t + mem)
        if (s == 1L && sprev == 2L) pAB <- min(1, psiAB_t + mem)
      }
      if (runif(1) >= phi_t) { sprev <- s; s <- 3L; y[i, t] <- 1L; next }
      ns <- if (s == 1L) sample.int(2, 1, prob = c(1 - pAB, pAB))
            else         sample.int(2, 1, prob = c(pBA, 1 - pBA))
      sprev <- s
      s <- c(1L, 2L)[ns]
      y[i, t] <- if (s == 1L) sample.int(3, 1, prob = c(1 - p, p, 0))
                 else         sample.int(3, 1, prob = c(1 - p, 0, p))
    }
  }
  y
}

## ---- model ----
Gam <- function(psiAB, psiBA, phi) matrix(c(
  phi * (1 - psiAB), phi * psiAB,     1 - phi,
  phi * psiBA,       phi * (1 - psiBA), 1 - phi,
  0,                 0,                1), nrow = 3, byrow = TRUE)
nll_ms <- function(par, y) {
  phi <- plogis(par[1]); psiAB <- plogis(par[2]); psiBA <- plogis(par[3])
  pA <- plogis(par[4]); pB <- plogis(par[5]); G <- Gam(psiAB, psiBA, phi)
  Pm <- list(c(1 - pA, 1 - pB, 1), c(pA, 0, 0), c(0, pB, 0)); ll <- 0
  for (i in 1:N) {
    a <- rep(0, 3); a[init_state[i]] <- 1; lg <- 0
    for (t in 2:k) { a <- (a %*% G) * Pm[[y[i, t]]]; s <- sum(a)
      if (s <= 0) return(1e10); a <- a / s; lg <- lg + log(s) }
    ll <- ll + lg
  }
  -ll
}
start <- c(qlogis(0.7), qlogis(0.3), qlogis(0.3), qlogis(0.6), qlogis(0.6))
fit_ms <- function(y) plogis(optim(start, nll_ms, y = y, method = "BFGS",
                                  control = list(maxit = 600))$par)
sim_markov <- function(th, seed) {
  set.seed(seed); phi <- th[1]; psiAB <- th[2]; psiBA <- th[3]; pA <- th[4]; pB <- th[5]
  G <- Gam(psiAB, psiBA, phi); y <- matrix(1L, N, k)
  for (i in 1:N) {
    s <- init_state[i]; y[i, 1] <- if (s == 1L) 2L else 3L
    for (t in 2:k) { s <- sample.int(3, 1, prob = G[s, ])
      if (s == 1L) y[i, t] <- sample.int(3, 1, prob = c(1 - pA, pA, 0))
      else if (s == 2L) y[i, t] <- sample.int(3, 1, prob = c(1 - pB, 0, pB)) }
  }
  y
}

## ---- statistic ----
Tstat <- function(y) {
  rev <- 0; sw <- 0
  for (i in 1:nrow(y)) {
    obs <- which(y[i, ] != 1L)
    if (length(obs) < 3) next
    st <- ifelse(y[i, obs] == 2L, 1L, 2L)
    for (j in 1:(length(obs) - 2)) {
      if (obs[j + 1] == obs[j] + 1 && obs[j + 2] == obs[j] + 2) {
        if (st[j] != st[j + 1]) { sw <- sw + 1; if (st[j + 2] == st[j]) rev <- rev + 1 }
      }
    }
  }
  if (sw == 0) return(NA); rev / sw
}
run_gof <- function(y, B = 200) {
  th <- fit_ms(y); Tobs <- Tstat(y); Tboot <- numeric(B)
  for (b in 1:B) Tboot[b] <- Tstat(sim_markov(th, seed = 9000 + b))
  Tboot <- Tboot[!is.na(Tboot)]
  list(Tobs = Tobs, Tboot = Tboot,
       pval = (1 + sum(Tboot >= Tobs)) / (1 + length(Tboot)), theta = th)
}

## ---- run-both ----
yM <- sim_ms(0.0, p_t, 138)                     # well specified
gofM <- run_gof(yM, B = 200)
yMem <- sim_ms(0.22, p_t, 138)                  # memory in the data
gofMem <- run_gof(yMem, B = 200)
data.frame(
  data = c("Markov", "Memory"),
  phi = c(round(gofM$theta[1], 3), round(gofMem$theta[1], 3)),
  psiAB = c(round(gofM$theta[2], 3), round(gofMem$theta[2], 3)),
  T_obs = c(round(gofM$Tobs, 3), round(gofMem$Tobs, 3)),
  boot_mean = c(round(mean(gofM$Tboot), 3), round(mean(gofMem$Tboot), 3)),
  gof_p = c(round(gofM$pval, 3), round(gofMem$pval, 3)))

## ---- fig-bootstrap ----
bd <- rbind(
  data.frame(case = "Well-specified (Markov data)", T = gofM$Tboot),
  data.frame(case = "Misspecified (memory in data)", T = gofMem$Tboot))
bd$case <- factor(bd$case, levels = c("Well-specified (Markov data)", "Misspecified (memory in data)"))
obs <- data.frame(
  case = factor(c("Well-specified (Markov data)", "Misspecified (memory in data)"), levels = levels(bd$case)),
  Tobs = c(gofM$Tobs, gofMem$Tobs),
  lab = c(paste0("observed = ", round(gofM$Tobs, 3), "\np = ", round(gofM$pval, 3)),
          paste0("observed = ", round(gofMem$Tobs, 3), "\np = ", round(gofMem$pval, 3))),
  hj = c(-0.06, 1.06))
ggplot(bd, aes(T)) +
  geom_histogram(aes(y = after_stat(density)), bins = 26, fill = forest, alpha = 0.55, colour = NA) +
  geom_vline(data = obs, aes(xintercept = Tobs), colour = brick, linewidth = 1.1) +
  geom_text(data = obs, aes(x = Tobs, y = Inf, label = lab, hjust = hj), colour = ink, size = 3.3, vjust = 1.4) +
  facet_wrap(~case) +
  labs(title = "A goodness-of-fit test catches what estimates hide",
       subtitle = "Bootstrap distribution of the reversal statistic under the fitted Markov model; red is the observed value",
       x = "Reversal rate under the fitted model", y = "Density") +
  theme_te() + coord_cartesian(xlim = c(0.2, 0.62))

## ---- sweep ----
mem_grid <- c(0, 0.05, 0.10, 0.15, 0.20, 0.25)
R_rep <- 8
Tsweep <- sapply(mem_grid, function(mm)
  mean(sapply(1:R_rep, function(r) Tstat(sim_ms(mm, p_t, 1380 + r))), na.rm = TRUE))
null_lo <- as.numeric(quantile(gofM$Tboot, 0.025))
null_hi <- as.numeric(quantile(gofM$Tboot, 0.975))
data.frame(mem = mem_grid, T_obs = round(Tsweep, 3))

## ---- fig-sweep ----
sw <- data.frame(mem = mem_grid, Tobs = Tsweep)
ggplot(sw, aes(mem, Tobs)) +
  annotate("rect", xmin = -Inf, xmax = Inf, ymin = null_lo, ymax = null_hi, fill = gold, alpha = 0.25) +
  geom_hline(yintercept = mean(gofM$Tboot), linetype = "dashed", colour = "#7a6f2e", linewidth = 0.4) +
  annotate("text", x = 0.252, y = null_hi, label = "Markov null (95%)", colour = "#7a6f2e", size = 3.5, hjust = 1, vjust = -0.5) +
  geom_line(linewidth = 1, colour = brick) + geom_point(size = 2.8, colour = brick) +
  labs(title = "The mean reversal rate rises with the strength of memory",
       subtitle = "Means over several simulated data sets: a trend, not a power curve",
       x = "Strength of state memory", y = "Mean observed reversal rate") + theme_te()
