# Occupancy and detection covariates in R
# https://tidyecology.com/posts/occupancy-detection-covariates/
#
# 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

## ---- setup ----
suppressMessages({library(ggplot2)})
te_ink<-"#16241d"; te_body<-"#2c3a31"; te_forest<-"#275139"; te_paper<-"#f5f4ee"
te_line<-"#dad9ca"; te_faint<-"#5d6b61"; te_gold<-"#c9b458"; te_deep<-"#1d5b4e"
te_red<-"#b5534e"; te_sage<-"#93a87f"; te_green<-"#2f8f63"
theme_te <- function(base_size = 12) {
  theme_minimal(base_size = base_size) +
    theme(text=element_text(colour=te_body),
      plot.title=element_text(colour=te_ink, face="bold", size=rel(1.05)),
      plot.subtitle=element_text(colour=te_faint, size=rel(0.9)),
      axis.title=element_text(colour=te_ink), axis.text=element_text(colour=te_body),
      panel.grid.minor=element_blank(),
      panel.grid.major=element_line(colour=te_line, linewidth=0.3),
      plot.background=element_rect(fill=te_paper, colour=NA),
      panel.background=element_rect(fill=te_paper, colour=NA),
      legend.key=element_blank(), legend.position="bottom",
      plot.margin=margin(10,12,10,10))
}

## ---- simulate ----
set.seed(101)
R <- 300L; K <- 5L
habitat <- as.numeric(scale(rnorm(R)))
effort  <- as.numeric(scale(runif(R, 1, 5)))
a_true <- c(-0.3, 1.4)          # occupancy intercept and habitat slope
b_true <- c(-0.2, 0.7)          # detection intercept and effort slope
psi_i <- plogis(a_true[1] + a_true[2] * habitat)
p_i   <- plogis(b_true[1] + b_true[2] * effort)
z <- rbinom(R, 1, psi_i)
y <- matrix(rbinom(R * K, 1, rep(z, K) * rep(p_i, K)), R, K)
d <- rowSums(y)
c(realised_occ = round(mean(z), 3), naive_detrate = round(mean(d >= 1), 3))

## ---- fit ----
X <- cbind(1, habitat)          # occupancy design matrix
W <- cbind(1, effort)           # detection design matrix
nll <- function(par, y, K, X, W) {
  a <- par[1:ncol(X)]
  b <- par[(ncol(X) + 1):(ncol(X) + ncol(W))]
  psi <- plogis(as.vector(X %*% a))
  p   <- plogis(as.vector(W %*% b))
  d <- rowSums(y)
  lik <- ifelse(d > 0, psi * p^d * (1 - p)^(K - d), psi * (1 - p)^K + (1 - psi))
  -sum(log(lik))
}
fit <- optim(rep(0, 4), nll, y = y, K = K, X = X, W = W, method = "BFGS", hessian = TRUE)
stopifnot(fit$convergence == 0)   # check before inverting the Hessian
V <- solve(fit$hessian); se <- sqrt(diag(V)); est <- fit$par
res <- data.frame(term = c("psi_int", "psi_habitat", "p_int", "p_effort"),
                  estimate = round(est, 3), se = round(se, 3), truth = c(a_true, b_true))
res

## ---- naive-glm ----
naive_glm <- glm((d >= 1) ~ habitat, family = binomial)
round(coef(naive_glm)[["habitat"]], 3)

## ---- fig-habitat ----
hx <- seq(min(habitat), max(habitat), length.out = 100)
Xg <- cbind(1, hx); Va <- V[1:2, 1:2]
eta <- as.vector(Xg %*% est[1:2])
se_eta <- sqrt(rowSums((Xg %*% Va) * Xg))          # delta-method SE on the logit scale
band <- data.frame(hx = hx, psi = plogis(eta),
                   lo = plogis(eta - 1.96 * se_eta),
                   hi = plogis(eta + 1.96 * se_eta))
rug <- data.frame(habitat = habitat, det = ifelse(d >= 1, 1, 0))
ggplot(band, aes(hx, psi)) +
  geom_ribbon(aes(ymin = lo, ymax = hi), fill = te_forest, alpha = 0.18) +
  geom_line(colour = te_forest, linewidth = 1) +
  geom_rug(data = subset(rug, det == 1), aes(x = habitat), inherit.aes = FALSE,
           sides = "t", colour = te_deep, alpha = 0.5, length = unit(0.03, "npc")) +
  geom_rug(data = subset(rug, det == 0), aes(x = habitat), inherit.aes = FALSE,
           sides = "b", colour = te_gold, alpha = 0.5, length = unit(0.03, "npc")) +
  scale_y_continuous(limits = c(0, 1), labels = scales::percent_format(1)) +
  labs(title = "Occupancy rises along the habitat gradient",
       subtitle = "Fitted psi with 95% interval; top rug detected, bottom rug never detected",
       x = "Habitat covariate (standardised)", y = "Occupancy probability") +
  theme_te(13)

## ---- psi-points ----
round(plogis(est[1] + est[2] * c(-2, 0, 2)), 3)   # psi at habitat -2, 0, +2
i0 <- which.min(abs(hx))
round((band$hi[i0] - band$lo[i0]) / 2, 3)          # CI half-width at mean habitat

## ---- fig-effort ----
ex <- seq(min(effort), max(effort), length.out = 100)
pdet <- data.frame(ex = ex, p = plogis(est[3] + est[4] * ex))
ggplot(pdet, aes(ex, p)) +
  geom_line(colour = te_deep, linewidth = 1) +
  geom_rug(data = data.frame(effort = effort), aes(x = effort), inherit.aes = FALSE,
           sides = "b", colour = te_faint, alpha = 0.4) +
  scale_y_continuous(limits = c(0, 1), labels = scales::percent_format(1)) +
  labs(title = "Detection probability increases with survey effort",
       subtitle = "More effort per visit means fewer missed occupied sites",
       x = "Survey effort (standardised)", y = "Detection probability p") +
  theme_te(12)

## ---- p-points ----
round(plogis(est[3] + est[4] * c(-1.5, 1.5)), 3)   # p at effort -1.5, +1.5
