# Multi-species occupancy models
# https://tidyecology.com/posts/multi-species-occupancy-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-15

## ---- setup ----
library(ggplot2); library(dplyr); library(tidyr)
logit <- qlogis; expit <- plogis

# brand palette + theme
te_ink<-"#16241d"; te_body<-"#2c3a31"; te_forest<-"#275139"; te_faint<-"#5d6b61"
te_sage<-"#93a87f"; te_paper<-"#f5f4ee"; te_line<-"#dad9ca"; te_brick<-"#b5534e"
theme_te <- function(base_size=12){
  theme_minimal(base_size=base_size) +
    theme(plot.background=element_rect(fill=te_paper,colour=NA),
          panel.background=element_rect(fill="#f5f4ee",colour=NA),
          panel.grid.minor=element_blank(),
          panel.grid.major=element_line(colour=te_line,linewidth=0.3),
          axis.title=element_text(colour=te_body), axis.text=element_text(colour=te_faint),
          plot.title=element_text(colour=te_ink,face="bold"),
          plot.subtitle=element_text(colour=te_faint,size=rel(0.9)),
          legend.text=element_text(colour=te_faint,size=rel(0.8)))
}

## ---- simulate ----
set.seed(143)
S <- 32L; R <- 90L; K <- 4L                 # species, sites, visits
mu_lpsi <- logit(0.40); sd_lpsi <- 1.30     # community occupancy (logit scale)
mu_lp   <- logit(0.27); sd_lp   <- 0.95     # community detection (logit scale)

lpsi_t <- rnorm(S, mu_lpsi, sd_lpsi)        # true species occupancy logits
lp_t   <- rnorm(S, mu_lp,   sd_lp)          # true species detection logits
psi_t  <- expit(lpsi_t); p_t <- expit(lp_t)

z_t <- matrix(rbinom(S*R, 1, psi_t), nrow=S, ncol=R)          # occupancy state
y   <- matrix(rbinom(S*R, K, ifelse(z_t==1, p_t, 0)), S, R)   # detection counts
det_sites <- rowSums(y > 0)                                    # sites each species was seen at

## ---- independent-mle ----
nll_ss <- function(par, yi){
  psi <- expit(par[1]); p <- expit(par[2]); det <- yi > 0
  ll <- sum(log(psi) + dbinom(yi[det], K, p, log=TRUE)) +
        sum((!det) * log(psi*(1-p)^K + (1-psi)))
  -ll
}
nll_psi1 <- function(yi) optimize(function(b) nll_ss(c(30, b), yi), c(-15, 5))  # occupancy fixed at one
ss_psi <- ss_p <- rep(NA_real_, S); boundary <- logical(S)
for (s in 1:S){
  yi <- y[s,]
  st <- list(c(0,0), logit(pmin(pmax(c(mean(yi>0), mean(yi[yi>0])/K), 0.02), 0.98)))  # two starts
  fits <- lapply(st, function(s0) optim(s0, nll_ss, yi=yi, method="BFGS"))
  op <- fits[[which.min(sapply(fits, `[[`, "value"))]]
  ss_psi[s] <- expit(op$par[1]); ss_p[s] <- expit(op$par[2])
  o1 <- nll_psi1(yi)
  if (o1$objective < op$value) { ss_psi[s] <- 1; ss_p[s] <- expit(o1$minimum) }  # maximum at occupancy one
  boundary[s] <- ss_psi[s]>0.995 || ss_psi[s]<0.005 || ss_p[s]>0.995 || ss_p[s]<0.005
}
sum(boundary)   # species whose independent estimate is pinned at a boundary

## ---- community-mcmc ----
ni <- 18000L; nb <- 6000L; nt <- 3L
lpsi <- logit(pmin(pmax((det_sites+0.5)/(R+1), 0.02), 0.98)); lp <- rep(logit(0.3), S)
mps <- 0; sps <- 1; mp <- logit(0.3); sp <- 1               # hyperparameters
t_lpsi<-0.30; t_lp<-0.26; t_mu<-0.14; t_lsd<-0.14           # proposal scales
keep <- seq(nb+1, ni, by=nt); nk <- length(keep)
PSI <- matrix(NA,nk,S); P <- matrix(NA,nk,S); HYP <- matrix(NA,nk,4); kk <- 0L

for (it in 1:ni){
  psi <- expit(lpsi); p <- expit(lp)
  # sum of occupied sites, drawing the latent state at undetected sites (Gibbs)
  pz <- psi*(1-p)^K / (psi*(1-p)^K + (1-psi))
  z  <- ifelse(y==0, matrix(rbinom(S*R,1,pz),S,R), 1L); sumz <- rowSums(z)
  # species occupancy logits (Metropolis)
  prop <- lpsi + rnorm(S,0,t_lpsi); psip <- expit(prop)
  a <- sumz*log(psip)+(R-sumz)*log(1-psip)+dnorm(prop,mps,sps,log=TRUE) -
       (sumz*log(psi)+(R-sumz)*log(1-psi)+dnorm(lpsi,mps,sps,log=TRUE))
  au <- log(runif(S)) < a; lpsi[au] <- prop[au]
  # species detection logits (Metropolis), over occupied sites
  p <- expit(lp); occ <- z==1; Sy <- rowSums(y*occ); SKy <- rowSums((K-y)*occ)
  prop <- lp + rnorm(S,0,t_lp); pp <- expit(prop)
  a <- Sy*log(pp)+SKy*log(1-pp)+dnorm(prop,mp,sp,log=TRUE) -
       (Sy*log(p)+SKy*log(1-p)+dnorm(lp,mp,sp,log=TRUE))
  au <- log(runif(S)) < a; lp[au] <- prop[au]
  # community means and spreads (Metropolis; half-normal prior on the spreads)
  pr <- mps+rnorm(1,0,t_mu)
  if (log(runif(1)) < sum(dnorm(lpsi,pr,sps,log=TRUE))-sum(dnorm(lpsi,mps,sps,log=TRUE))) mps <- pr
  pr <- exp(log(sps)+rnorm(1,0,t_lsd))
  if (log(runif(1)) < sum(dnorm(lpsi,mps,pr,log=TRUE))+dnorm(pr,0,2.5,log=TRUE)+log(pr)-
                      sum(dnorm(lpsi,mps,sps,log=TRUE))-dnorm(sps,0,2.5,log=TRUE)-log(sps)) sps <- pr
  pr <- mp+rnorm(1,0,t_mu)
  if (log(runif(1)) < sum(dnorm(lp,pr,sp,log=TRUE))-sum(dnorm(lp,mp,sp,log=TRUE))) mp <- pr
  pr <- exp(log(sp)+rnorm(1,0,t_lsd))
  if (log(runif(1)) < sum(dnorm(lp,mp,pr,log=TRUE))+dnorm(pr,0,2.5,log=TRUE)+log(pr)-
                      sum(dnorm(lp,mp,sp,log=TRUE))-dnorm(sp,0,2.5,log=TRUE)-log(sp)) sp <- pr
  if (it>nb && ((it-nb) %% nt == 0)){ kk<-kk+1L
    PSI[kk,]<-expit(lpsi); P[kk,]<-expit(lp); HYP[kk,]<-c(mps,sps,mp,sp) }
}
comm_psi <- colMeans(PSI); hyp <- colMeans(HYP)
c(community_occupancy = round(expit(hyp[1]),3), community_detection = round(expit(hyp[3]),3))

## ---- fig-shrinkage ----
comm_mean <- expit(hyp[1])
df  <- data.frame(det=det_sites, ind=ss_psi, comm=comm_psi)
seg <- data.frame(det=df$det, y1=df$ind, y2=df$comm)
ggplot() +
  geom_hline(yintercept=comm_mean, linetype="dashed", colour=te_faint) +
  geom_segment(data=seg, aes(det, y1, xend=det, yend=y2), colour=te_sage, linewidth=0.4) +
  geom_point(data=df, aes(det, ind, shape="Independent (per species)"), colour=te_brick, size=2) +
  geom_point(data=df, aes(det, comm, shape="Community (pooled)"), colour=te_forest, size=2) +
  scale_shape_manual(NULL, values=c("Independent (per species)"=1,"Community (pooled)"=16)) +
  scale_x_continuous(transform="sqrt", breaks=c(2,5,10,20,40,80)) +
  labs(x="sites where the species was detected (sqrt scale)", y="occupancy estimate (psi)",
       title="Pooling mostly moves the estimates pinned at a boundary",
       subtitle="dashed line: community mean; segments join the two estimates for each species") +
  theme_te() + theme(legend.position = "inside", legend.position.inside = c(0.75,0.15),
                     legend.background=element_rect(fill="#ffffff",colour=te_line))

## ---- fig-distribution ----
xx <- seq(-6, 5, length=400)
dens <- data.frame(psi=expit(xx)); lp_ax <- logit(dens$psi)
dens$dp <- dnorm(lp_ax, hyp[1], hyp[2]) / (dens$psi*(1-dens$psi))    # change of variable to psi scale
sp <- data.frame(psi=comm_psi)
ggplot() +
  geom_area(data=subset(dens, psi>1e-3 & psi<0.999), aes(psi, dp), fill=te_sage, alpha=0.35) +
  geom_line(data=subset(dens, psi>1e-3 & psi<0.999), aes(psi, dp), colour=te_forest, linewidth=0.7) +
  geom_rug(data=sp, aes(psi), colour=te_brick, length=unit(0.05,"npc")) +
  geom_point(data=sp, aes(psi, y=0), colour=te_brick, size=1.6, alpha=0.8) +
  labs(x="species occupancy (psi)", y="community density",
       title="The estimated distribution of species occupancy",
       subtitle="curve: fitted community (logit-normal); ticks: per-species posterior means") +
  theme_te()
