# Integrated species distribution models in R
# https://tidyecology.com/posts/integrated-species-distribution-model/
#
# 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 ----
knitr::opts_chunk$set(echo = TRUE, message = FALSE, warning = FALSE,
                      fig.width = 7.5, fig.height = 4.6, dpi = 150, dev = "png")
library(ggplot2)
te <- list(ink="#16241d", body="#2c3a31", forest="#275139", label="#46604a",
           sage="#93a87f", paper="#f5f4ee", line="#dad9ca", card="#ffffff",
           faint="#5d6b61", grazed="#cda23f", mown="#2f8f63", abandoned="#b5534e",
           grad_low="#c9b458", grad_high="#1d5b4e")
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=base_size+1),
          plot.subtitle=element_text(colour=te$faint, size=base_size-1),
          axis.title=element_text(colour=te$label),
          axis.text=element_text(colour=te$faint, size=base_size-2),
          panel.grid.major=element_line(colour=te$line, linewidth=0.3),
          panel.grid.minor=element_blank(),
          panel.background=element_rect(fill=te$paper, colour=NA),
          plot.background=element_rect(fill=te$paper, colour=NA),
          legend.title=element_text(colour=te$label, size=base_size-2),
          legend.text=element_text(colour=te$faint, size=base_size-2),
          strip.text=element_text(colour=te$ink, face="bold", size=base_size-1),
          strip.background=element_rect(fill=te$paper, colour=NA),
          plot.margin=margin(10,12,10,10))
}

## ---- smooth-field ----
# a smooth spatial field on a g x g grid, standardised
smooth_field <- function(g, l, seed) {
  set.seed(seed)
  u <- (seq_len(g) - 0.5) / g
  D <- outer(u, u, function(a, b) exp(-(a - b)^2 / (2 * l^2)))
  Sm <- D / rowSums(D)
  as.numeric(scale(as.numeric(Sm %*% matrix(rnorm(g * g), g, g) %*% t(Sm))))
}

g     <- 50                 # grid resolution
Acell <- 1 / (g * g)        # area of one grid cell (unit square)
x     <- smooth_field(g, 0.18, 4711)                 # environmental covariate
raw   <- smooth_field(g, 0.18, 9001)
acc   <- as.numeric(scale(0.6 * x + sqrt(1 - 0.36) * raw))  # accessibility, rho ~ 0.6

b1_true <- 1.0              # true environmental response
a1_true <- 1.6             # effort effect on detection of records
p_true  <- 0.40            # per-visit detection in the survey
Asite   <- 0.0004          # area of one survey site
EN      <- 4000            # expected number of individuals
b0_true <- log(EN / (Acell * sum(exp(b1_true * x))))
round(c(cor_x_acc = cor(x, acc), b0_true = b0_true), 3)

## ---- simulate ----
set.seed(1)
lambda <- exp(b0_true + b1_true * x)                 # true intensity surface
N      <- rpois(1, Acell * sum(lambda))
cell   <- sample(length(x), N, replace = TRUE, prob = lambda / sum(lambda))
bias   <- exp(a1_true * acc)                          # effort-driven thinning
keep   <- rbinom(N, 1, pmin(1, bias[cell] / max(bias)))
po     <- tabulate(cell[keep == 1], nbins = length(x))  # presence-only counts per cell

nsite  <- 300
ssite  <- sample(length(x), nsite)                    # structured survey sites
K      <- 4                                            # repeat visits
psi    <- 1 - exp(-Asite * exp(b0_true + b1_true * x[ssite]))  # cloglog occupancy
z      <- rbinom(nsite, 1, psi)
y      <- rbinom(nsite, K, z * p_true)
c(records = sum(po), sites_detected = sum(y > 0), true_occupancy = round(mean(psi), 3))

## ---- fits ----
# presence-only point process likelihood on the grid
nll_po <- function(par, use_acc) {
  b1 <- par[1]; s0 <- par[2]
  lp <- s0 + b1 * x
  if (use_acc) lp <- lp + par[3] * acc
  mu <- exp(lp)
  -(sum(po * log(mu)) - Acell * sum(mu))
}
fit_po_naive  <- optim(c(1, 0),    nll_po, use_acc = FALSE, method = "BFGS", hessian = TRUE)
fit_po_effort <- optim(c(1, 0, 0), nll_po, use_acc = TRUE,  method = "BFGS", hessian = TRUE)

# survey-only occupancy, marginalising the latent state
nll_occ <- function(par) {
  b0 <- par[1]; b1 <- par[2]; p <- plogis(par[3])
  ps <- 1 - exp(-Asite * exp(b0 + b1 * x[ssite]))
  -sum(log(ps * dbinom(y, K, p) + (1 - ps) * (y == 0)))
}
fit_occ <- optim(c(b0_true, 1, 0), nll_occ, method = "BFGS", hessian = TRUE)

# integrated: shared b0, b1; the records add their own intercept and effort slope
nll_joint <- function(par) {
  b0 <- par[1]; b1 <- par[2]; a0 <- par[3]; p <- plogis(par[4]); a1 <- par[5]
  mu <- exp(b0 + b1 * x + a0 + a1 * acc)
  ll_po  <- sum(po * log(mu)) - Acell * sum(mu)
  ps     <- 1 - exp(-Asite * exp(b0 + b1 * x[ssite]))
  ll_occ <- sum(log(ps * dbinom(y, K, p) + (1 - ps) * (y == 0)))
  -(ll_po + ll_occ)
}
fit_joint <- optim(c(b0_true, 1, -3, 0, 0), nll_joint, method = "BFGS", hessian = TRUE)

se <- function(f, i) sqrt(diag(solve(f$hessian)))[i]
b1_naive  <- fit_po_naive$par[1]
b1_effort <- fit_po_effort$par[1]
b1_occ    <- fit_occ$par[2];   se_occ   <- se(fit_occ, 2)
b1_joint  <- fit_joint$par[2]; se_joint <- se(fit_joint, 2)
round(c(naive = b1_naive, effort = b1_effort, occupancy = b1_occ, integrated = b1_joint), 3)

## ---- fig-response ----
xg <- seq(-2.5, 2.5, length.out = 100)
rel <- function(b1) b1 * xg - b1 * mean(xg)
dl <- rbind(
  data.frame(x = xg, y = rel(b1_true),  who = "truth"),
  data.frame(x = xg, y = rel(b1_naive), who = "naive presence-only"),
  data.frame(x = xg, y = rel(b1_occ),   who = "survey only"),
  data.frame(x = xg, y = rel(b1_joint), who = "integrated"))
ggplot(dl, aes(x, y, colour = who, linetype = who)) +
  geom_line(linewidth = 0.9) +
  scale_colour_manual(values = c("truth" = te$abandoned, "naive presence-only" = te$grazed,
                                 "survey only" = te$sage, "integrated" = te$forest)) +
  scale_linetype_manual(values = c("truth" = "dashed", "naive presence-only" = "solid",
                                   "survey only" = "solid", "integrated" = "solid")) +
  labs(x = "environmental covariate", y = "relative log-intensity",
       title = "Fitted relative log-intensity: naive, survey only and integrated",
       subtitle = "Each solid line is drawn at its estimator's fitted slope; the dashed line is the truth",
       colour = NULL, linetype = NULL) +
  theme_te() + theme(legend.position = "inside", legend.position.inside = c(0.28, 0.8))

## ---- mc ----
run_one <- function(seed) {
  set.seed(seed)
  lam  <- exp(b0_true + b1_true * x)
  Nn   <- rpois(1, Acell * sum(lam))
  cl   <- sample(length(x), Nn, replace = TRUE, prob = lam / sum(lam))
  bi   <- exp(a1_true * acc)
  kp   <- rbinom(Nn, 1, pmin(1, bi[cl] / max(bi)))
  po2  <- tabulate(cl[kp == 1], nbins = length(x))
  ss   <- sample(length(x), nsite)
  ps   <- 1 - exp(-Asite * exp(b0_true + b1_true * x[ss]))
  zz   <- rbinom(nsite, 1, ps); yy <- rbinom(nsite, K, zz * p_true)
  nll_o <- function(par) { b0<-par[1];b1<-par[2];p<-plogis(par[3])
    q<-1-exp(-Asite*exp(b0+b1*x[ss])); -sum(log(q*dbinom(yy,K,p)+(1-q)*(yy==0))) }
  nll_j <- function(par) { b0<-par[1];b1<-par[2];a0<-par[3];p<-plogis(par[4]);a1<-par[5]
    mu<-exp(b0+b1*x+a0+a1*acc); lpo<-sum(po2*log(mu))-Acell*sum(mu)
    q<-1-exp(-Asite*exp(b0+b1*x[ss])); lo<-sum(log(q*dbinom(yy,K,p)+(1-q)*(yy==0))); -(lpo+lo) }
  fo <- tryCatch(optim(c(b0_true,1,0), nll_o, method="BFGS", hessian=TRUE), error=function(e) NULL)
  fj <- tryCatch(optim(c(b0_true,1,-3,0,0), nll_j, method="BFGS", hessian=TRUE), error=function(e) NULL)
  if (is.null(fo) || is.null(fj)) return(rep(NA, 4))
  so <- sqrt(diag(solve(fo$hessian)))[2]; sj <- sqrt(diag(solve(fj$hessian)))[2]
  c(fo$par[2], so, fj$par[2], sj)
}
M  <- 100
mc <- t(sapply(1:M, function(m) run_one(1000 + m)))
mc <- mc[stats::complete.cases(mc), ]
cover <- function(est, s) mean(abs(est - b1_true) <= 1.96 * s)
occ_sd <- sd(mc[, 1]); joint_sd <- sd(mc[, 3])
round(c(occ_mean = mean(mc[, 1]), joint_mean = mean(mc[, 3]),
        occ_sd = occ_sd, joint_sd = joint_sd,
        sd_ratio = joint_sd / occ_sd,
        joint_coverage = cover(mc[, 3], mc[, 4])), 3)

## ---- fig-forest ----
est <- data.frame(
  method = factor(c("naive\npresence-only", "presence-only\n+ effort", "survey\nonly", "integrated"),
                  levels = c("naive\npresence-only", "presence-only\n+ effort", "survey\nonly", "integrated")),
  b1 = c(b1_naive, b1_effort, b1_occ, b1_joint),
  se = c(se(fit_po_naive, 1), se(fit_po_effort, 1), se_occ, se_joint))
p_forest <- ggplot(est, aes(method, b1)) +
  geom_hline(yintercept = b1_true, colour = te$abandoned, linetype = "dashed") +
  geom_errorbar(aes(ymin = b1 - 1.96 * se, ymax = b1 + 1.96 * se), width = 0.16,
                colour = te$forest, linewidth = 0.7) +
  geom_point(size = 2.8, colour = te$forest) +
  labs(x = NULL, y = "environmental response (b1)",
       title = "Slope and 95 per cent interval from each estimator",
       subtitle = "Dashed line is the true response") +
  theme_te()
p_forest

## ---- thumb ----
thumb_title <- paste(strwrap("Slope and interval from four estimators", 46),
                     collapse = "\n")
ggsave("thumbnail.png",
       p_forest + labs(title = thumb_title) +
         theme(plot.title = element_text(size = 13, face = "bold"),
               plot.subtitle = element_text(size = 9.5),
               plot.margin = margin(8, 14, 8, 8)),
       width = 7.5, height = 5.4, dpi = 100, bg = te$paper)
