--- title: "An elevational-gradient workflow" output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{An elevational-gradient workflow} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ```{r, include = FALSE} knitr::opts_chunk$set( collapse = TRUE, comment = "#>", dev.args = list(bg = "white"), fig.width = 7, fig.height = 4, eval = requireNamespace("vegan", quietly = TRUE) ) ``` A single elevational transect is the most common design in tropical community ecology: one site per elevation, each surveyed several times. This article walks through a complete analysis of such a transect with tidydiversity, using the frogs of Mt Wilhelm, Papua New Guinea (`png_frogs`: eight sites from 200 to 3,700 m). ## The design decides the statistics The repeated nights or days at a site are repeat visits to **one** site, not replicates of that elevation. The sample size for any test of an elevational pattern is therefore the number of sites (here 8), not the number of nights. Treating nights as replicates inflates the evidence (pseudoreplication; Hurlbert 1984). With so few sites, permutation tests should enumerate every ordering of the sites (8! = 40,320) and report exact p-values; tidydiversity does this with `permutations = "exact"`. ```{r setup, message = FALSE} library(tidydiversity) library(dplyr) set.seed(2026) frogs <- png_frogs sites <- distinct(frogs, site, elevation) ``` ## 1. Richness along the gradient Richness is a count, so model it with a Poisson GLM; a quadratic term tests for a mid-elevation peak. Sites without frogs must be kept as zeros. ```{r richness} rich <- div_hill(frogs, abundance = abundance, q = 0) |> right_join(sites, by = "site") |> mutate(richness = coalesce(diversity, 0)) peak <- model_count(rich, richness ~ elevation + I(elevation^2)) line <- model_count(rich, richness ~ elevation) peak anova(line$fit, peak$fit, test = "LRT") b <- coef(peak$fit) -b[["elevation"]] / (2 * b[["I(elevation^2)"]]) # elevation of the peak (m) ``` **How to read it.** The likelihood-ratio test compares a straight line with a curve. The quadratic term is significant, so richness peaks at mid-elevation rather than declining steadily; the fitted peak lies at about `r round(-b[["elevation"]] / (2 * b[["I(elevation^2)"]]), -1)` m. The dispersion (Pearson chi-square / df) printed with the model should be near 1; much larger values call for a quasi-Poisson or negative binomial model. ## 2. Diversity at equal coverage Raw diversity depends on sampling effort. Standardise every site to the same sample coverage (Chao and Jost 2012). `level = "min_observed"` uses the least complete site as observed and rarefies the others, the most conservative choice; the default, `"max_extrapolation"`, is the rule of iNEXT. The `target` column reports the level used. ```{r standardise} std <- div_standardise(frogs, abundance = abundance, q = 0:2, nboot = 0, level = "min_observed" ) std |> select(site, q, target, coverage, diversity) ``` A site whose coverage curve cannot reach the target (here 3,700 m, with two species) is returned at its highest attainable coverage with a warning: compare `coverage` with `target`. ## 3. Composition: ordination with environmental vectors A PCA of Hellinger-transformed abundances (Legendre and Gallagher 2001) shows the main gradient in composition; elevation is fitted passively. `choices = 1:2` tests it on the two plotted axes, and `permutations = "exact"` gives the exact p-value. ```{r ordination} pca <- ord_fit(frogs, abundance = abundance, method = "pca", formula = ~elevation, permutations = "exact" ) pca$axes pca$envfit ``` Sites are returned in a fixed order and their environmental values are joined by site name, so the arrows are fitted to the right sites however the data are sorted. ```{r biplot, fig.alt = "PCA biplot of frog communities with the elevation vector"} ggplot2::autoplot(pca, colour = elevation, site_labels = TRUE, species = 8) ``` ## 4. Does composition change with elevation? PERMANOVA ```{r permanova} beta_permanova(frogs, abundance = abundance, formula = ~elevation, permutations = "exact" ) ``` Elevation explains a quarter of the variation in composition (R2), and the exact p-value comes from all 40,320 orderings of the eight sites. ## 5. Distance decay: the Mantel test Pairs of sites share sites, so their dissimilarities are not independent and regression p-values on pairs are invalid. Use a Mantel test. ```{r mantel} turn <- beta_dist(beta_pair(frogs), "turnover") elev <- setNames(sites$elevation, sites$site) beta_mantel(turn, elev) ``` For a relationship expected to be negative, such as similarity with distance, use `alternative = "less"`. ## 6. Turnover or nestedness? Adjacent sites ```{r counts} beta_turnover_counts(frogs, abundance = abundance, order_by = elevation) |> select(site_1, site_2, shared, lost, gained, sorensen, turnover, nestedness) beta_multi(frogs) ``` **How to read it.** `lost` and `gained` count the species found only below or only above each step. Sørensen dissimilarity splits into turnover (species replaced) and nestedness (species lost without replacement; Baselga 2010). Up to 2,700 m almost all change is turnover; the step to 3,200 m adds nestedness, as the summit fauna is a subset of the species below. ## 7. Comparing transects: distance-decay slopes Is turnover along one transect faster than along another? Compare the slopes with bootstrap intervals that resample sites, not pairs. ```{r decay} decay <- bind_rows( beta_decay(frogs, elevation) |> mutate(taxon = "frogs"), beta_decay(filter(png_ants, season == "wet"), elevation) |> mutate(taxon = "ants") ) beta_decay_boot(decay, group = taxon, nboot = 499, per = 1000, seed = 2026) ``` Slopes are dissimilarity per 1,000 m. The interval of the difference includes zero, so frogs and ants on Mt Wilhelm turn over at rates that these data cannot tell apart; with five ant sites the intervals are wide. ## References Baselga, A. (2010). Partitioning the turnover and nestedness components of beta diversity. *Global Ecology and Biogeography*, 19, 134-143. Chao, A. and Jost, L. (2012). Coverage-based rarefaction and extrapolation. *Ecology*, 93, 2533-2547. Hurlbert, S. H. (1984). Pseudoreplication and the design of ecological field experiments. *Ecological Monographs*, 54, 187-211. Legendre, P. and Gallagher, E. D. (2001). Ecologically meaningful transformations for ordination of species data. *Oecologia*, 129, 271-280.