# Bayesian occupancy with latent-state MCMC
# https://tidyecology.com/posts/bayesian-occupancy-latent-state-mcmc/
#
# 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 ----
knitr::opts_chunk$set(message = FALSE, warning = FALSE,
                      fig.width = 7.5, fig.height = 5.4, dpi = 150)
library(ggplot2)
te <- list(ink="#16241d", body="#2c3a31", forest="#275139", label="#46604a",
           sage="#93a87f", paper="#f5f4ee", line="#dad9ca", faint="#5d6b61",
           gold="#cda23f", mown="#2f8f63", terra="#b5534e")
theme_te <- function(base_size = 13) {
  theme_minimal(base_size = base_size) +
    theme(plot.background = element_rect(fill = te$paper, colour = NA),
          panel.background = element_rect(fill = te$paper, colour = NA),
          panel.grid.major = element_line(colour = te$line, linewidth = 0.3),
          panel.grid.minor = element_blank(),
          axis.text = element_text(colour = te$faint),
          axis.title = element_text(colour = te$body),
          plot.title = element_text(colour = te$ink, face = "bold"),
          plot.subtitle = element_text(colour = te$label),
          legend.text = element_text(colour = te$body),
          plot.caption = element_text(colour = te$faint, size = base_size * 0.75))
}

## ---- sim ----
set.seed(2)
n <- 200; K <- 4; psi <- 0.6; p <- 0.3
z_t <- rbinom(n, 1, psi)                                   # true latent occupancy
Y   <- matrix(rbinom(n * K, 1, rep(z_t, K) * p), n, K)     # detection histories
det <- rowSums(Y); detected <- det > 0
naive <- mean(detected)                                    # naive detected fraction
c(detected_sites = sum(detected), all_zero = sum(!detected), naive = round(naive, 3))

## ---- gibbs ----
gibbs_occ <- function(iter = 15000, warm = 3000, seed = 1) {
  set.seed(seed)
  z <- as.integer(detected)                               # detected => occupied
  psi_s <- 0.5; p_s <- 0.5; q0 <- which(!detected)
  keep <- matrix(NA_real_, iter, 2, dimnames = list(NULL, c("psi", "p")))
  for (t in seq_len(iter)) {
    # occupied-but-undetected probability for all-zero sites, then sample z
    r <- psi_s * (1 - p_s)^K / (psi_s * (1 - p_s)^K + (1 - psi_s))
    z[q0] <- rbinom(length(q0), 1, r)
    sz <- sum(z)
    # psi | z  and  p | z, Y   are conjugate Beta draws
    psi_s <- rbeta(1, 1 + sz, 1 + n - sz)
    tot_det <- sum(det[z == 1]); tot_trials <- K * sz
    p_s <- rbeta(1, 1 + tot_det, 1 + tot_trials - tot_det)
    keep[t, ] <- c(psi_s, p_s)
  }
  keep[(warm + 1):iter, ]
}
post <- gibbs_occ(seed = 5)
psi_ci <- quantile(post[, "psi"], c(.025, .975))
p_ci   <- quantile(post[, "p"],   c(.025, .975))
round(c(psi_med = median(post[, "psi"]), psi_lo = psi_ci[1], psi_hi = psi_ci[2],
        p_med = median(post[, "p"]), p_lo = p_ci[1], p_hi = p_ci[2]), 3)

## ---- fig-psi ----
ggplot(data.frame(psi = post[, "psi"]), aes(psi)) +
  geom_density(fill = te$forest, colour = te$forest, alpha = 0.18, linewidth = 1) +
  geom_vline(xintercept = naive, colour = te$terra, linetype = "dashed", linewidth = 0.9) +
  geom_vline(xintercept = psi, colour = te$sage, linetype = "dashed", linewidth = 0.9) +
  annotate("text", x = naive, y = Inf, label = "naive detected  ", hjust = 1, vjust = 1.6,
           colour = te$terra, size = 3.6) +
  annotate("text", x = psi, y = Inf, label = "  true psi", hjust = 0, vjust = 1.6,
           colour = te$label, size = 3.6) +
  labs(x = "occupancy probability psi", y = "posterior density",
       title = "The occupancy model recovers what detection hides",
       subtitle = "naive detected occupancy is biased low; the posterior sits at the truth") +
  theme_te()

## ---- ppc ----
set.seed(99)
tab_obs <- tabulate(det + 1, K + 1)          # sites detected on 0, 1, ..., K visits
chisq_tab <- function(tab, ps, pp) {         # discrepancy from the expected table
  ex <- n * c(ps * (1 - pp)^K + 1 - ps, ps * dbinom(1:K, K, pp))
  sum((tab - ex)^2 / ex)
}
ppc <- t(sapply(sample(nrow(post), 2000), function(i) {
  zz <- rbinom(n, 1, post[i, "psi"])
  d_rep <- rowSums(matrix(rbinom(n * K, 1, rep(zz, K) * post[i, "p"]), n, K))
  c(zero = sum(d_rep == 0),
    T_obs = chisq_tab(tab_obs, post[i, "psi"], post[i, "p"]),
    T_rep = chisq_tab(tabulate(d_rep + 1, K + 1), post[i, "psi"], post[i, "p"]))
}))
ppp_tab <- mean(ppc[, "T_rep"] >= ppc[, "T_obs"])
c(observed_zero = sum(!detected), predicted_zero_median = median(ppc[, "zero"]),
  ppp_table = round(ppp_tab, 3))

## ---- fig-effort ----
Kseq <- 1:8
band <- sapply(Kseq, function(k) quantile(post[, "psi"] * (1 - (1 - post[, "p"])^k),
                                          c(.05, .5, .95)))
dfk <- data.frame(K = Kseq, lo = band["5%", ], med = band["50%", ], hi = band["95%", ])
ggplot(dfk, aes(K, med)) +
  geom_ribbon(aes(ymin = lo, ymax = hi), fill = te$forest, alpha = 0.15) +
  geom_line(colour = te$forest, linewidth = 1.1) +
  geom_hline(yintercept = median(post[, "psi"]), colour = te$gold, linetype = "dashed") +
  geom_point(data = data.frame(K = K, naive = naive), aes(K, naive),
             colour = te$terra, size = 3) +
  annotate("text", x = 8, y = median(post[, "psi"]) + 0.02, hjust = 1, colour = te$gold,
           size = 3.5, label = "inferred occupancy ceiling") +
  annotate("text", x = K + 0.15, y = naive - 0.03, hjust = 0, colour = te$terra,
           size = 3.5, label = "observed at K = 4") +
  coord_cartesian(ylim = c(0, 0.7)) + scale_x_continuous(breaks = Kseq) +
  labs(x = "number of repeat visits K", y = "expected fraction of sites with a detection",
       title = "Why more visits shrink the bias, and what the model infers",
       subtitle = "detection saturates slowly with effort; the model reads off the ceiling") +
  theme_te()
