# Multi-state capture-recapture
# https://tidyecology.com/posts/multistate-capture-recapture/
#
# 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),
  legend.position = "bottom", legend.title = element_blank())

ink <- "#16241d"; forest <- "#275139"; gold <- "#c9b458"; brick <- "#b5534e"

## ---- truth ----
phiA_t <- 0.75; phiB_t <- 0.60      # state-specific survival
psiAB_t <- 0.25; psiBA_t <- 0.15    # movement A->B and B->A
pA_t <- 0.55; pB_t <- 0.45          # state-specific detection
k <- 8                               # occasions
nA0 <- 260; nB0 <- 200               # initial marks per state
N <- nA0 + nB0

# state process (1 = alive-A, 2 = alive-B, 3 = dead); rows = from, cols = to
Gam <- function(phiA, phiB, psiAB, psiBA) matrix(c(
  phiA * (1 - psiAB), phiA * psiAB,     1 - phiA,
  phiB * psiBA,       phiB * (1 - psiBA), 1 - phiB,
  0,                  0,                1), nrow = 3, byrow = TRUE)
G_true <- Gam(phiA_t, phiB_t, psiAB_t, psiBA_t)
init_state <- c(rep(1L, nA0), rep(2L, nB0))

## ---- simulate ----
set.seed(135)
z <- matrix(0L, N, k)                # true latent state
y <- matrix(1L, N, k)                # observed event (1 = not seen)
for (i in 1:N) {
  z[i, 1] <- init_state[i]
  y[i, 1] <- if (z[i, 1] == 1L) 2L else 3L    # seen in its state when marked
  for (t in 2:k) {
    z[i, t] <- sample.int(3, 1, prob = G_true[z[i, t - 1], ])
    if (z[i, t] == 1L)      y[i, t] <- sample.int(3, 1, prob = c(1 - pA_t, pA_t, 0))
    else if (z[i, t] == 2L) y[i, t] <- sample.int(3, 1, prob = c(1 - pB_t, 0, pB_t))
    else                    y[i, t] <- 1L
  }
}
n_reseen <- sum(rowSums(y > 1L) > 1)
n_events <- sum(y > 1L)

## ---- likelihood ----
nll <- function(par) {
  phiA <- plogis(par[1]); phiB <- plogis(par[2])
  psiAB <- plogis(par[3]); psiBA <- plogis(par[4])
  pA <- plogis(par[5]); pB <- plogis(par[6])
  G <- Gam(phiA, phiB, psiAB, psiBA)
  Pm <- list(c(1 - pA, 1 - pB, 1),   # event 1: not seen
             c(pA, 0, 0),            # event 2: seen at A
             c(0, pB, 0))            # event 3: seen at B
  ll <- 0
  for (i in 1:N) {
    a <- rep(0, 3); a[init_state[i]] <- 1     # known state at first capture
    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.5), qlogis(0.5), qlogis(0.2), qlogis(0.2), qlogis(0.4), qlogis(0.4))
fit <- optim(start, nll, method = "BFGS", hessian = TRUE, control = list(maxit = 500))
stopifnot(fit$convergence == 0)   # check before inverting the Hessian
est <- plogis(fit$par)
V <- solve(fit$hessian)
se_logit <- sqrt(diag(V))
lo <- plogis(fit$par - 1.96 * se_logit)
hi <- plogis(fit$par + 1.96 * se_logit)
nm <- c("phiA", "phiB", "psiAB", "psiBA", "pA", "pB")
truth <- c(phiA_t, phiB_t, psiAB_t, psiBA_t, pA_t, pB_t)
data.frame(parameter = nm, truth = truth, estimate = round(est, 3),
           lower = round(lo, 3), upper = round(hi, 3),
           covered = truth >= lo & truth <= hi)

## ---- naive ----
nAA <- sum(y[, -k] == 2L & y[, -1] == 2L); nAB <- sum(y[, -k] == 2L & y[, -1] == 3L)
nBA <- sum(y[, -k] == 3L & y[, -1] == 2L); nBB <- sum(y[, -k] == 3L & y[, -1] == 3L)
naive_psiAB <- nAB / (nAA + nAB)
naive_psiBA <- nBA / (nBA + nBB)
c(naive_psiAB = round(naive_psiAB, 3), naive_psiBA = round(naive_psiBA, 3))

# naive apparent return rate, ignoring state (a mix of survival and detection)
ret <- sum(vapply(1:N, function(i)
  sum(vapply(1:(k - 1), function(t) y[i, t] > 1L && any(y[i, (t + 1):k] > 1L), logical(1))),
  numeric(1)))
atrisk <- sum(y[, -k] > 1L)
round(ret / atrisk, 3)

## ---- fig-estimates ----
lab <- c(phiA = "phi[A]", phiB = "phi[B]", psiAB = "psi[AB]",
         psiBA = "psi[BA]", pA = "p[A]", pB = "p[B]")
df <- data.frame(param = factor(nm, levels = rev(nm)), est = est,
                 lo = lo, hi = hi, truth = truth)
naive <- data.frame(param = factor(c("psiAB", "psiBA"), levels = rev(nm)),
                    val = c(naive_psiAB, naive_psiBA))
ggplot(df, aes(y = param)) +
  geom_segment(aes(x = lo, xend = hi, yend = param), colour = forest, linewidth = 1.1) +
  geom_point(aes(x = est), colour = forest, size = 3) +
  geom_point(aes(x = truth), colour = ink, shape = 124, size = 6) +
  geom_point(data = naive, aes(x = val), colour = brick, shape = 4, size = 3, stroke = 1.3) +
  scale_y_discrete(labels = function(x) parse(text = lab[x])) +
  labs(title = "Multi-state estimates and naive apparent transitions",
       subtitle = "Point and 95% CI (green), truth (dark bar), naive apparent transition (red cross)",
       x = "Probability", y = NULL) + theme_te()

## ---- mc ----
simulate_fit <- function(seed) {
  set.seed(seed)
  yy <- matrix(1L, N, k)
  for (i in 1:N) {
    s1 <- init_state[i]; yy[i, 1] <- if (s1 == 1L) 2L else 3L; st <- s1
    for (t in 2:k) {
      st <- sample.int(3, 1, prob = G_true[st, ])
      if (st == 1L)      yy[i, t] <- sample.int(3, 1, prob = c(1 - pA_t, pA_t, 0))
      else if (st == 2L) yy[i, t] <- sample.int(3, 1, prob = c(1 - pB_t, 0, pB_t))
    }
  }
  nll_s <- function(par) {
    phiA <- plogis(par[1]); phiB <- plogis(par[2]); psiAB <- plogis(par[3])
    psiBA <- plogis(par[4]); pA <- plogis(par[5]); pB <- plogis(par[6])
    G <- Gam(phiA, phiB, psiAB, psiBA)
    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[[yy[i, t]]]; sm <- sum(a)
        if (sm <= 0) return(1e10); a <- a / sm; lg <- lg + log(sm) }
      ll <- ll + lg
    }
    -ll
  }
  plogis(optim(start, nll_s, method = "BFGS", control = list(maxit = 500))$par)
}

S <- 40
MC <- t(vapply(1000 + 1:S, simulate_fit, numeric(6)))
colnames(MC) <- nm
round(colMeans(MC) - truth, 4)   # Monte Carlo bias per parameter

## ---- fig-unbiased ----
MCl <- stack(as.data.frame(MC)); names(MCl) <- c("value", "param")
MCl$param <- factor(MCl$param, levels = nm)
tr <- data.frame(param = factor(nm, levels = nm), truth = truth)
ggplot(MCl, aes(x = param, y = value)) +
  geom_boxplot(fill = "#e7e9df", colour = forest, outlier.size = 0.7, width = 0.55) +
  geom_point(data = tr, aes(x = param, y = truth), colour = brick, size = 3, shape = 18) +
  scale_x_discrete(labels = function(x) parse(text = lab[x])) +
  labs(title = "Where the estimates land across 40 replicate simulations",
       subtitle = "Boxplots of estimates across replicate simulations; red diamonds are true values",
       x = NULL, y = "Estimate") + theme_te()
