# Imperfect detection and occupancy bias in R
# https://tidyecology.com/posts/imperfect-detection-occupancy/
#
# 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-05-11

## ---- setup ----
suppressMessages({library(ggplot2); library(dplyr); library(tidyr)})
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(2026)
R <- 200L; K <- 4L
psi_true <- 0.55; p_true <- 0.30
z <- rbinom(R, 1, psi_true)                                   # true occupancy state
y <- matrix(rbinom(R * K, 1, z * p_true), nrow = R, ncol = K) # detection histories
detected <- rowSums(y)                                        # detections per site (0..4)

sum(z)              # sites truly occupied
mean(z)             # realised occupancy
mean(detected >= 1) # naive occupancy: sites detected at least once

## ---- fig-hist ----
hd <- as.data.frame(table(factor(detected, levels = 0:4)))
names(hd) <- c("det", "n")
ggplot(hd, aes(det, n)) +
  geom_col(fill = te_forest, width = 0.75) +
  geom_text(aes(label = n), vjust = -0.4, colour = te_ink, size = 3.5) +
  labs(title = "Detections per site (200 sites, 4 visits)",
       subtitle = "121 sites truly occupied; only 96 detected at least once",
       x = "Times detected out of 4 visits", y = "Number of sites") +
  theme_te(12)

## ---- expected ----
cum_det <- 1 - (1 - p_true)^K          # detection at an occupied site
cum_det                                # about 0.76
psi_true * cum_det                     # expected naive occupancy

## ---- fig-erosion ----
K_seq <- 1:8; ps <- c(0.2, 0.3, 0.4, 0.5)
erosion <- expand.grid(K = K_seq, p = ps) |>
  mutate(ratio = 1 - (1 - p)^K, plab = factor(sprintf("p = %.1f", p)))
ggplot(erosion, aes(K, ratio, colour = plab)) +
  geom_hline(yintercept = 1, colour = te_line, linewidth = 0.4) +
  geom_line(linewidth = 0.9) + geom_point(size = 1.7) +
  scale_colour_manual(values = c("p = 0.2"=te_gold, "p = 0.3"=te_green,
                                 "p = 0.4"=te_forest, "p = 0.5"=te_deep), name = NULL) +
  scale_x_continuous(breaks = 1:8) +
  scale_y_continuous(limits = c(0, 1), labels = scales::percent_format(1)) +
  labs(title = "A non-detection is not an absence",
       subtitle = "Share of occupied sites detected at least once, by number of visits",
       x = "Visits per site (K)", y = "Detected at least once") +
  theme_te(13)

## ---- phat-naive ----
det_sites <- detected[detected >= 1]
mean(det_sites) / K   # naive detection rate among detected sites
