# Multi-event models for uncertain states
# https://tidyecology.com/posts/multievent-uncertain-states/
#
# 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-09-30

## ---- 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"

# state process: latent 1 = alive-A, 2 = alive-B, 3 = dead
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)

## ---- truth ----
phi_t <- 0.75; psiAB_t <- 0.15; psiBA_t <- 0.10   # low true movement
p_t <- 0.55; eps_t <- 0.15                          # detection and misclassification
k <- 8; nA0 <- 320; nB0 <- 280; N <- nA0 + nB0
init_state <- c(rep(1L, nA0), rep(2L, nB0))

# event: 1 = not seen, 2 = seen-as-A, 3 = seen-as-B
sim_me <- function(eps, p, seed) {
  set.seed(seed)
  y <- matrix(1L, N, k)
  for (i in 1:N) {
    s <- init_state[i]; y[i, 1] <- if (s == 1L) 2L else 3L   # state known at marking
    for (t in 2:k) {
      s <- sample.int(3, 1, prob = Gam(psiAB_t, psiBA_t, phi_t)[s, ])
      if (s == 1L)      y[i, t] <- sample.int(3, 1, prob = c(1 - p, p * (1 - eps), p * eps))
      else if (s == 2L) y[i, t] <- sample.int(3, 1, prob = c(1 - p, p * eps, p * (1 - eps)))
    }
  }
  y
}

## ---- fitters ----
# multi-event: par = phi, psiAB, psiBA, p, eps
nll_me <- function(par, y) {
  phi <- plogis(par[1]); psiAB <- plogis(par[2]); psiBA <- plogis(par[3])
  p <- plogis(par[4]); eps <- plogis(par[5])
  G <- Gam(psiAB, psiBA, phi)
  Pm <- list(c(1 - p, 1 - p, 1), c(p * (1 - eps), p * eps, 0), c(p * eps, p * (1 - eps), 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_me <- c(qlogis(0.7), qlogis(0.2), qlogis(0.15), qlogis(0.5), qlogis(0.15))

# naive: take the recorded state as the truth (standard multi-state, eps ignored)
nll_naive <- 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_nv <- c(qlogis(0.7), qlogis(0.2), qlogis(0.15), qlogis(0.4), qlogis(0.4))
fit_naive <- function(y) plogis(optim(start_nv, nll_naive, y = y, method = "BFGS",
                                      control = list(maxit = 600))$par)

## ---- fit-both ----
y <- sim_me(eps_t, p_t, 137)
f <- optim(start_me, nll_me, y = y, method = "BFGS", hessian = TRUE, control = list(maxit = 700))
stopifnot(f$convergence == 0)   # check before inverting the Hessian
me <- plogis(f$par)
se <- sqrt(diag(solve(f$hessian)))
lo <- plogis(f$par - 1.96 * se); hi <- plogis(f$par + 1.96 * se)
nv <- fit_naive(y)
data.frame(param = c("phi", "psiAB", "psiBA", "p", "eps"),
           truth = c(phi_t, psiAB_t, psiBA_t, p_t, eps_t),
           multi_event = round(me, 3), lo = round(lo, 3), hi = round(hi, 3),
           naive = c(round(nv[1:3], 3), NA, NA))

## ---- fig-estimates ----
lab <- c(phi = "phi", psiAB = "psi[AB]", psiBA = "psi[BA]", p = "p", eps = "epsilon")
nm <- c("phi", "psiAB", "psiBA", "p", "eps")
est <- data.frame(param = factor(nm, levels = nm),
                  est = me, lo = lo, hi = hi, truth = c(phi_t, psiAB_t, psiBA_t, p_t, eps_t))
naive_df <- data.frame(param = factor(c("psiAB", "psiBA"), levels = nm), value = c(nv[2], nv[3]))
ggplot(est, aes(x = param)) +
  geom_point(aes(y = truth), shape = 95, size = 11, colour = ink) +
  geom_errorbar(aes(ymin = lo, ymax = hi), width = 0.16, colour = forest, linewidth = 0.8) +
  geom_point(aes(y = est, colour = "Multi-event MLE"), size = 3) +
  geom_point(data = naive_df, aes(y = value, colour = "Naive (states as truth)"), size = 3.4, shape = 17) +
  scale_x_discrete(labels = function(z) parse(text = lab[z])) +
  scale_colour_manual(values = c("Multi-event MLE" = forest, "Naive (states as truth)" = brick)) +
  labs(title = "Multi-event recovers every parameter; naive inflates movement",
       subtitle = "Points are estimates, bars are 95% CIs, dashes are the truth; naive transitions (triangles) sit far above",
       x = NULL, y = "Estimate") + theme_te()

## ---- eps-experiment ----
eps_grid <- c(0.00, 0.05, 0.10, 0.15, 0.20)
R_rep <- 10
rows <- list()
for (ep in eps_grid) {
  mAB <- mBA <- nAB <- nBA <- numeric(R_rep)
  for (r in 1:R_rep) {
    yy <- sim_me(ep, p_t, 1370 + r)
    mm <- plogis(optim(start_me, nll_me, y = yy, method = "BFGS", control = list(maxit = 700))$par)
    nnv <- fit_naive(yy)
    mAB[r] <- mm[2]; mBA[r] <- mm[3]; nAB[r] <- nnv[2]; nBA[r] <- nnv[3]
  }
  rows[[length(rows) + 1]] <- data.frame(eps = ep,
    psiAB_me = mean(mAB), psiBA_me = mean(mBA),
    psiAB_naive = mean(nAB), psiBA_naive = mean(nBA))
}
tab <- do.call(rbind, rows)
round(tab, 3)

## ---- fig-sweep ----
long <- rbind(
  data.frame(eps = tab$eps, param = "psi[AB]", method = "Naive", value = tab$psiAB_naive),
  data.frame(eps = tab$eps, param = "psi[AB]", method = "Multi-event", value = tab$psiAB_me),
  data.frame(eps = tab$eps, param = "psi[BA]", method = "Naive", value = tab$psiBA_naive),
  data.frame(eps = tab$eps, param = "psi[BA]", method = "Multi-event", value = tab$psiBA_me))
tru <- data.frame(param = c("psi[AB]", "psi[BA]"), truth = c(psiAB_t, psiBA_t))
ggplot(long, aes(eps, value, colour = method)) +
  geom_hline(data = tru, aes(yintercept = truth), linetype = "dashed", colour = ink, linewidth = 0.5) +
  geom_line(linewidth = 1) + geom_point(size = 2.6) +
  facet_wrap(~param, labeller = label_parsed) +
  scale_colour_manual(values = c("Multi-event" = forest, "Naive" = brick)) +
  labs(title = "Misclassification inflates apparent movement",
       subtitle = "As the misclassification rate rises, naive transitions climb; multi-event stays on the truth (dashed)",
       x = "Misclassification rate (epsilon)", y = "Estimated transition probability") + theme_te()
