# Dynamic occupancy: colonisation and extinction
# https://tidyecology.com/posts/dynamic-occupancy-colonisation-extinction/
#
# 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-08

## ---- sim ----
set.seed(139)
R <- 250; Tn <- 6; K <- 4
psi1 <- 0.55; gamma <- 0.20; eps <- 0.30; p <- 0.35

z <- matrix(0L, R, Tn)               # latent occupancy state
z[, 1] <- rbinom(R, 1, psi1)
for (t in 2:Tn) z[, t] <- rbinom(R, 1, ifelse(z[, t - 1] == 1, 1 - eps, gamma))

d <- matrix(0L, R, Tn)               # detections per season (out of K)
for (t in 1:Tn) d[, t] <- rbinom(R, K, z[, t] * p)

round(gamma / (gamma + eps), 3)      # equilibrium occupancy

## ---- likelihood ----
emit <- function(dt, p, K) c(as.numeric(dt == 0), p^dt * (1 - p)^(K - dt))

site_ll <- function(dv, init, Phi, p, K) {
  a <- init * emit(dv[1], p, K); s <- sum(a); ll <- log(s); a <- a / s
  for (t in 2:length(dv)) {
    a <- as.vector(a %*% Phi) * emit(dv[t], p, K)
    s <- sum(a); ll <- ll + log(s); a <- a / s
  }
  ll
}

nll <- function(par) {
  ps <- plogis(par[1]); ga <- plogis(par[2]); ep <- plogis(par[3]); pp <- plogis(par[4])
  Phi <- matrix(c(1 - ga, ga, ep, 1 - ep), 2, 2, byrow = TRUE)
  -sum(apply(d, 1, site_ll, init = c(1 - ps, ps), Phi = Phi, p = pp, K = K))
}

fit <- optim(c(0, qlogis(0.2), qlogis(0.2), qlogis(0.3)), nll,
             method = "BFGS", hessian = TRUE)
stopifnot(fit$convergence == 0)   # check before inverting the Hessian
est <- plogis(fit$par); names(est) <- c("psi1", "gamma", "eps", "p")
se  <- sqrt(diag(solve(fit$hessian))) * est * (1 - est)   # delta-method SE
round(rbind(estimate = est, se = se), 3)

## ---- naive-turnover ----
obs <- (d > 0) * 1L
cn <- cd <- en <- ed <- 0
for (t in 2:Tn) {
  u0 <- obs[, t - 1] == 0; o1 <- obs[, t - 1] == 1
  cd <- cd + sum(u0); cn <- cn + sum(u0 & obs[, t] == 1)
  ed <- ed + sum(o1); en <- en + sum(o1 & obs[, t] == 0)
}
c(naive_colonisation = round(cn / cd, 3), naive_extinction = round(en / ed, 3))

## ---- fig-trajectory ----
suppressMessages({library(ggplot2); library(dplyr)})
theme_te <- function(bs = 12) theme_minimal(base_size = bs) + theme(
  plot.background = element_rect(fill = "#f5f4ee", colour = NA),
  panel.background = element_rect(fill = "#f5f4ee", colour = NA),
  panel.grid.major = element_line(colour = "#dad9ca", linewidth = 0.3),
  panel.grid.minor = element_blank(),
  axis.text = element_text(colour = "#2c3a31"), axis.title = element_text(colour = "#16241d"),
  plot.title = element_text(colour = "#16241d", face = "bold"),
  plot.subtitle = element_text(colour = "#46604a"),
  legend.text = element_text(colour = "#2c3a31"), legend.position = "top",
  legend.key = element_rect(fill = "#f5f4ee", colour = NA))

psit <- numeric(Tn); psit[1] <- est["psi1"]
for (t in 2:Tn) psit[t] <- psit[t - 1] * (1 - est["eps"]) + (1 - psit[t - 1]) * est["gamma"]
psi_eq <- unname(est["gamma"] / (est["gamma"] + est["eps"]))

traj <- bind_rows(
  data.frame(season = 1:Tn, occ = colMeans(z),     series = "Realised occupancy (truth)"),
  data.frame(season = 1:Tn, occ = psit,            series = "Modelled occupancy"),
  data.frame(season = 1:Tn, occ = colMeans(d > 0), series = "Naive observed occupancy"))
traj$series <- factor(traj$series,
  levels = c("Realised occupancy (truth)", "Modelled occupancy", "Naive observed occupancy"))

ggplot(traj, aes(season, occ, colour = series, shape = series)) +
  geom_hline(yintercept = psi_eq, linetype = "dashed", colour = "#1d5b4e", linewidth = 0.5) +
  annotate("text", x = 1.2, y = psi_eq + 0.018, label = "equilibrium",
           colour = "#1d5b4e", size = 3, hjust = 0, family = "mono") +
  geom_line(linewidth = 0.8) + geom_point(size = 2.6) +
  scale_colour_manual(values = c("Realised occupancy (truth)" = "#275139",
    "Modelled occupancy" = "#b5534e", "Naive observed occupancy" = "#cda23f")) +
  scale_shape_manual(values = c("Realised occupancy (truth)" = 16,
    "Modelled occupancy" = 17, "Naive observed occupancy" = 15)) +
  scale_x_continuous(breaks = 1:Tn) + coord_cartesian(ylim = c(0.25, 0.65)) +
  labs(x = "Primary period (season)", y = "Proportion of sites occupied",
       colour = NULL, shape = NULL) +
  theme_te() + guides(colour = guide_legend(nrow = 1))

## ---- fig-turnover ----
tr <- data.frame(
  rate = rep(c("Colonisation", "Extinction"), 3),
  source = rep(c("Naive apparent", "Model estimate", "Truth"), each = 2),
  value = c(cn / cd, en / ed, est["gamma"], est["eps"], gamma, eps))
tr$source <- factor(tr$source, levels = c("Naive apparent", "Model estimate", "Truth"))

ggplot(tr, aes(rate, value, fill = source)) +
  geom_col(position = position_dodge(0.7), width = 0.62) +
  scale_fill_manual(values = c("Naive apparent" = "#cda23f",
    "Model estimate" = "#275139", "Truth" = "#b5534e")) +
  geom_text(aes(label = sprintf("%.2f", value)), position = position_dodge(0.7),
            vjust = -0.4, size = 3, colour = "#2c3a31") +
  coord_cartesian(ylim = c(0, 0.55)) +
  labs(x = NULL, y = "Per-season rate", fill = NULL) +
  theme_te()
