# Nestedness, NODF, and null models in R
# https://tidyecology.com/posts/nestedness-nodf/
#
# 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 ----
library(vegan)
library(ggplot2)

theme_te <- function(base_size = 12) {
  theme_minimal(base_size = base_size) +
    theme(
      plot.background  = element_rect(fill = "#f5f4ee", colour = NA),
      panel.background = element_rect(fill = "#f5f4ee", colour = NA),
      panel.grid.major = element_line(colour = "#dad9ca", linewidth = 0.3),
      panel.grid.minor = element_blank(),
      axis.text   = element_text(colour = "#46604a"),
      axis.title  = element_text(colour = "#2c3a31"),
      plot.title  = element_text(colour = "#16241d", face = "bold"),
      plot.subtitle = element_text(colour = "#5d6b61"),
      strip.text  = element_text(colour = "#16241d", face = "bold"),
      legend.position = "none"
    )
}
forest <- "#275139"; red <- "#b5534e"; faint <- "#5d6b61"
paper  <- "#f5f4ee"; line <- "#dad9ca"

tile_df <- function(M, label) {
  d <- as.data.frame(as.table(M))
  names(d) <- c("site", "species", "pa")
  d$site    <- as.integer(d$site)
  d$species <- as.integer(d$species)
  d$pa      <- factor(d$pa, levels = c(0, 1))
  d$panel   <- label
  d
}
mat_theme <- theme_te() +
  theme(panel.grid = element_blank(), axis.text = element_blank(),
        axis.ticks = element_blank())

## ---- fig-concept ----
ns <- 20; np <- 30
Rn <- round(seq(np * 0.92, np * 0.12, length.out = ns))
Mn <- matrix(0, ns, np); for (i in seq_len(ns)) Mn[i, seq_len(Rn[i])] <- 1
Mt <- matrix(0, ns, np); bw <- 4
for (j in seq_len(np)) {
  c0 <- (j - 1) / (np - 1) * (ns - 1) + 1
  rr <- round(c0) + (-bw:bw); rr <- rr[rr >= 1 & rr <= ns]
  Mt[rr, j] <- 1
}
d_concept <- rbind(tile_df(Mn, "nested: poorer sites hold subsets"),
                   tile_df(Mt, "turnover: sites hold different species"))

ggplot(d_concept, aes(species, site, fill = pa)) +
  geom_tile(colour = paper, linewidth = 0.25) +
  facet_wrap(~panel) +
  scale_fill_manual(values = c("0" = line, "1" = forest)) +
  scale_y_reverse() + coord_equal() +
  labs(x = "species", y = "site",
       title = "Two ways a community can be structured",
       subtitle = "nestedness is subset structure, not species replacement") +
  mat_theme

## ---- simulate ----
set.seed(41)
n_site <- 25; n_sp <- 50
site_q <- seq(2.6, -2.6, length.out = n_site)   # site suitability, rich to poor
sp_c   <- seq(2.6, -2.6, length.out = n_sp)     # species commonness, common to rare
P      <- outer(site_q, sp_c, function(a, b) plogis(a + b))
comm   <- matrix(rbinom(n_site * n_sp, 1, P), n_site, n_sp)
comm   <- comm[rowSums(comm) > 0, colSums(comm) > 0]
dim(comm)

## ---- nodf ----
nd <- nestednodf(comm)
nodf_val <- nd$statistic[["NODF"]]
round(c(N.columns = nd$statistic[["N.columns"]],
        N.rows    = nd$statistic[["N.rows"]],
        NODF      = nd$statistic[["NODF"]]), 1)

## ---- fig-matrix ----
ro <- order(rowSums(comm), decreasing = TRUE)
co <- order(colSums(comm), decreasing = TRUE)
d_mat <- tile_df(comm[ro, co], "sorted")

ggplot(d_mat, aes(species, site, fill = pa)) +
  geom_tile(colour = paper, linewidth = 0.15) +
  scale_fill_manual(values = c("0" = line, "1" = forest)) +
  scale_y_reverse() + coord_equal() +
  labs(x = "species (common to rare)", y = "site (rich to poor)",
       title = paste0("A simulated community with NODF = ", sprintf("%.0f", nodf_val)),
       subtitle = "rows and columns sorted by total: presence packs to the upper left") +
  mat_theme

## ---- null-fixed ----
set.seed(7)
os_ff <- oecosimu(comm, nestednodf, method = "quasiswap",
                  nsimul = 999, alternative = "greater")
z_ff   <- os_ff$oecosimu$z[["NODF"]]
p_ff   <- os_ff$oecosimu$pval[3]
sim_ff <- os_ff$oecosimu$simulated[3, ]
round(c(observed = nodf_val, null_mean = mean(sim_ff), z = z_ff, p = p_ff), 3)

## ---- null-equi ----
set.seed(9)
os_r0 <- oecosimu(comm, nestednodf, method = "r00",
                  nsimul = 999, alternative = "greater")
z_r0   <- os_r0$oecosimu$z[["NODF"]]
p_r0   <- os_r0$oecosimu$pval[3]
sim_r0 <- os_r0$oecosimu$simulated[3, ]
round(c(observed = nodf_val, null_mean = mean(sim_r0), z = z_r0, p = p_r0), 3)

## ---- fig-nulls ----
dd <- rbind(data.frame(nodf = sim_r0, model = "equiprobable null (r00)"),
            data.frame(nodf = sim_ff, model = "fixed-margin null (quasiswap)"))
dd$model <- factor(dd$model,
                   levels = c("equiprobable null (r00)", "fixed-margin null (quasiswap)"))

ggplot(dd, aes(nodf, fill = model)) +
  geom_histogram(bins = 45, colour = NA, alpha = 0.85, position = "identity") +
  geom_vline(xintercept = nodf_val, colour = "#16241d", linewidth = 0.7) +
  annotate("text", x = nodf_val - 1.6, y = 560,
           label = paste0("observed NODF = ", sprintf("%.0f", nodf_val)),
           hjust = 1, colour = "#16241d", size = 3.5) +
  annotate("text", x = nodf_val - 1.6, y = 500,
           label = paste0("fixed-margin z = ", sprintf("%.1f", z_ff)),
           hjust = 1, colour = forest, size = 3.4) +
  annotate("text", x = mean(sim_r0), y = 340,
           label = paste0("z = ", sprintf("%.1f", z_r0)), colour = red, size = 3.5) +
  scale_fill_manual(values = c("equiprobable null (r00)" = red,
                               "fixed-margin null (quasiswap)" = forest)) +
  scale_y_continuous(expand = expansion(mult = c(0, 0.08))) +
  labs(x = "NODF of null-model matrices", y = "count",
       title = "Same matrix, same statistic, opposite verdicts",
       subtitle = "the equiprobable null calls it nested; the fixed-margin null does not") +
  theme_te() +
  theme(legend.position = "top", legend.title = element_blank(),
        legend.text = element_text(colour = "#2c3a31"))
