Skip to contents

Validation and sanity checks

Source: vignettes/spesim-validation.Rmd
spesim-validation.Rmd

This article is a confidence-building checklist. It shows simple checks that help you confirm that a spesim run is producing the patterns you think you asked for.

1) Species–abundance distribution (SAD)

The rank–abundance plot compares realised counts to the target Fisher log-series settings.

library(spesim)

P <- load_config(system.file("examples/spesim_init_basic.txt", package = "spesim"))
res <- spesim_run(P, write_outputs = FALSE, seed = 77)

ra <- calculate_rank_abundance(res$species_dist)
plot_rank_abundance(ra)

What to look for:

  • Realised counts are close to the theoretical curve (on log-scale) when sample sizes are large.
  • Big departures usually indicate strong filtering / strong interactions / very small sample sizes.

2) Quadrat placement geometry

Always sanity-check the design visually.

plot_quadrats(res$domain, res$quadrats, title = "Quadrat layout")

3) Distance–decay behaves sensibly 

dd <- calculate_distance_decay(res$abund_matrix, res$site_coords)
plot_distance_decay(dd)

What to look for:

  • With strong gradients or dispersal limitation-like structure, dissimilarity should generally increase with distance.
  • Under CSR + no filtering, distance–decay should be weak.

4) Optional: point-process diagnostics with spatstat

spesim aims to stay lightweight, but if you have spatstat installed you can use it to validate clustering/inhibition patterns (e.g., Ripley’s K, pair correlation g(r)g(r)).

If spatstat.geom and spatstat.explore are available, spesim_audit() can compute edge-corrected summaries inside the true irregular window:

a <- spesim_audit(res, diagnostics = c("nn", "spatstat"))
print(a)

B) Manual workflow (power users) 

if (requireNamespace("spatstat.geom", quietly = TRUE) &&
    requireNamespace("spatstat.explore", quietly = TRUE)) {

  library(spatstat.geom)
  library(spatstat.explore)

  # Example: diagnose the dominant species pattern
  dom <- res$species_dist[res$species_dist$species == "A", ]

  # Convert to spatstat ppp in the true irregular window
  win <- as.owin(sf::st_as_sf(sf::st_union(res$domain)))
  xy <- sf::st_coordinates(dom)
  X <- ppp(xy[,1], xy[,2], window = win)

  plot(Kest(X, correction = "border"), main = "Ripley's K (border): dominant species")
  plot(pcf(X, correction = "Ripley"), main = "Pair correlation g(r): dominant species")
}

5) Reproducibility note (vegan)

Some summaries (e.g., vegan::specaccum(method = "random")) use internal random permutations.

  • If you want deterministic repeats, set a seed immediately beforehand:
set.seed(res$P$SEED)
# then regenerate SAR/rarefaction plots