A dataset with two gradients

The data is synthetic so the structure is known. Forty sites carry two measured variables, soil moisture and soil nitrogen, drawn independently of each other. Fourteen species each respond to both, peaking at their own point along moisture and at a separate point along nitrogen. Because the two gradients are independent by construction, a good method should pull them apart and credit each with its own share of the pattern.

library(vegan)
library(ggplot2)
library(dplyr)

set.seed(20)
n <- 40
moisture <- round(runif(n, 0, 10), 1)
nitrogen <- round(runif(n, 0, 10), 1)

species <- sprintf("sp%02d", 1:14)
opt_m <- seq(1, 9, length.out = 14)            # moisture optimum per species
opt_n <- sample(seq(1, 9, length.out = 14))    # nitrogen optimum, independent of moisture
w <- 2.3
lambda <- sapply(seq_along(species), function(i)
  12 * exp(-((moisture - opt_m[i])^2 + (nitrogen - opt_n[i])^2) / (2 * w^2)))
comm <- matrix(rpois(length(lambda), as.vector(lambda)), nrow = n)
colnames(comm) <- species
rownames(comm) <- sprintf("S%02d", 1:n)

env <- data.frame(moisture = moisture, nitrogen = nitrogen)
comm[1:5, 1:7]

    sp01 sp02 sp03 sp04 sp05 sp06 sp07
S01    0    0    1    0    0    0    1
S02    0    0    0    3    0    0    0
S03    7    1   12    6    7    8    3
S04    0    1   11    0    5    7    2
S05    0    0    0    0    2    1    2

Building the model

dbrda() takes a formula with the community on the left and the predictors on the right, plus the dissimilarity to use. It computes the Bray-Curtis distances, then finds the axes through that distance space that the predictors can explain, leaving the rest as unconstrained residual structure.

mod <- dbrda(comm ~ moisture + nitrogen, data = env, distance = "bray")
mod

Call: dbrda(formula = comm ~ moisture + nitrogen, data = env, distance =
"bray")

              Inertia Proportion Rank RealDims
Total          9.8765     1.0000              
Constrained    5.5768     0.5647    2        2
Unconstrained  4.2997     0.4353   37       21

Inertia is squared Bray distance

Eigenvalues for constrained axes:
dbRDA1 dbRDA2 
3.1394 2.4374 

Eigenvalues for unconstrained axes:
  MDS1   MDS2   MDS3   MDS4   MDS5   MDS6   MDS7   MDS8 
1.6793 0.5864 0.5176 0.4716 0.2922 0.2687 0.2427 0.2012 
(Showing 8 of 37 unconstrained eigenvalues)

The summary splits the total inertia into a constrained part and an unconstrained part. The constrained rows are the variation that moisture and nitrogen jointly account for; the unconstrained rows are what is left. Here the two predictors carry a little over half of the total, and the constrained side has exactly two axes, one per predictor, named dbRDA1 and dbRDA2.

How much is explained

The constrained proportion is the headline number, but raw proportions climb whenever you add predictors, whether or not they matter. RsquareAdj() corrects for that, the same way adjusted R-squared does in a linear model, and the adjusted figure is the one to quote.

RsquareAdj(mod)

$r.squared
[1] 0.564657

$adj.r.squared
[1] 0.5411249

About 56 percent of the compositional variation is constrained, and the adjusted value stays close to it (near 0.54), because two predictors against forty sites is not a demanding ratio.

Is the model significant?

The proportion tells you the size of the effect; permutation tests tell you whether it beats chance. anova() on a dbrda object reshuffles the data many times and compares. Run it three ways: the whole model, then each term, then each axis.

set.seed(20)
anova(mod, permutations = 999)

Permutation test for dbrda under reduced model
Permutation: free
Number of permutations: 999

Model: dbrda(formula = comm ~ moisture + nitrogen, data = env, distance = "bray")
         Df SumOfSqs      F Pr(>F)    
Model     2   5.5768 23.995  0.001 ***
Residual 37   4.2997                  
---
Signif. codes:  0 '***' 0.001 '**' 0.01 '*' 0.05 '.' 0.1 ' ' 1

set.seed(20)
anova(mod, by = "terms", permutations = 999)

Permutation test for dbrda under reduced model
Terms added sequentially (first to last)
Permutation: free
Number of permutations: 999

Model: dbrda(formula = comm ~ moisture + nitrogen, data = env, distance = "bray")
         Df SumOfSqs      F Pr(>F)    
moisture  1   3.1164 26.818  0.001 ***
nitrogen  1   2.4604 21.172  0.001 ***
Residual 37   4.2997                  
---
Signif. codes:  0 '***' 0.001 '**' 0.01 '*' 0.05 '.' 0.1 ' ' 1

set.seed(20)
anova(mod, by = "axis", permutations = 999)

Permutation test for dbrda under reduced model
Forward tests for axes
Permutation: free
Number of permutations: 999

Model: dbrda(formula = comm ~ moisture + nitrogen, data = env, distance = "bray")
         Df SumOfSqs      F Pr(>F)    
dbRDA1    1   3.1394 27.015  0.001 ***
dbRDA2    1   2.4374 21.542  0.001 ***
Residual 37   4.2997                  
---
Signif. codes:  0 '***' 0.001 '**' 0.01 '*' 0.05 '.' 0.1 ' ' 1

The whole model is significant (pseudo-F around 24, p = 0.001). Split by term, moisture and nitrogen are each highly significant on their own, with similar F values, which fits the way they were built as two real and independent drivers. Split by axis, both constrained axes carry signal worth keeping, so a two-dimensional plot is justified rather than just convenient.

The biplot

A constrained ordination is read as a biplot: site points placed on the constrained axes, and the predictors drawn as arrows pointing in the direction each one increases. Colouring the points by moisture and sizing them by nitrogen lets you check the arrows against the raw values.

scl <- 2
site_sc <- as.data.frame(scores(mod, display = "sites", scaling = scl, choices = 1:2))
bp      <- as.data.frame(scores(mod, display = "bp",    scaling = scl, choices = 1:2))
names(site_sc) <- c("AX1", "AX2")
names(bp)      <- c("AX1", "AX2")
site_sc$moisture <- moisture
site_sc$nitrogen <- nitrogen

# scale the predictor arrows to sit over the site cloud
mul <- 0.9 * max(abs(as.matrix(site_sc[, 1:2]))) / max(sqrt(rowSums(bp^2)))
bp$lab <- rownames(bp)
bp$x <- bp$AX1 * mul
bp$y <- bp$AX2 * mul

eig <- mod$CCA$eig
lab1 <- sprintf("dbRDA1 (%.0f%% of fitted)", 100 * eig[1] / sum(eig))
lab2 <- sprintf("dbRDA2 (%.0f%% of fitted)", 100 * eig[2] / sum(eig))

ggplot(site_sc, aes(AX1, AX2)) +
  geom_hline(yintercept = 0, color = "#e2e1d4") +
  geom_vline(xintercept = 0, color = "#e2e1d4") +
  geom_point(aes(color = moisture, size = nitrogen)) +
  geom_segment(data = bp, aes(x = 0, y = 0, xend = x, yend = y), inherit.aes = FALSE,
               arrow = arrow(length = unit(0.2, "cm")), color = "#16241d", linewidth = 0.9) +
  geom_text(data = bp, aes(x = x, y = y, label = lab), inherit.aes = FALSE,
            color = "#16241d", fontface = "bold", vjust = -0.6, size = 3.6) +
  scale_color_gradient(low = "#c9b458", high = "#1d5b4e", name = "Moisture") +
  scale_size_continuous(range = c(1.3, 5), name = "Nitrogen") +
  labs(x = lab1, y = lab2) +
  coord_equal() +
  theme_minimal(base_size = 12)

The first axis lines up with moisture: dry gold sites on one side, wet green ones on the other. The second axis lines up with nitrogen, and the point sizes grow along it. The two arrows meet at close to a right angle, the visual signature of predictors that vary independently. If moisture and nitrogen had been correlated in the field, the arrows would have drawn together, and the constrained axes would have struggled to separate their effects.

How this differs from NMDS and PERMANOVA

The three approaches answer different questions about the same kind of data. NMDS is unconstrained: it shows the full compositional structure and asks nothing of the environment until you overlay it with envfit(), which makes it the tool for exploring what is there. PERMANOVA tests whether named predictors explain composition but returns no map. Distance-based RDA does both at once: the anova() output is the test, and the biplot is the picture, but the picture shows only the slice of variation the predictors govern, not everything in the data. Reach for NMDS when you want to see all the structure and form hypotheses, and for dbrda() when you already have the predictors and want to model, measure, and display their effect directly.

Where to go next

capscale() is the close sibling of dbrda(), also distance-based, differing mainly in how each treats the negative eigenvalues that non-Euclidean distances can produce. A Condition() term partials out covariates you want to control for rather than test, and varpart() splits the explained variation among several predictor sets to show how much each contributes alone and how much they share. All of them build on the same move made here: let the predictors define the ordination, then test what they are worth.

Occurrence records

The data is synthetic so the pattern is known up front. It holds occurrence records for twelve species across a study region, each record a species name and a longitude and latitude. Two gradients are built in. One runs east to west and decides which species occur where, so composition turns over across the region. The other runs south to north and sets how many species a place can support, standing in for something like productivity. The result should be a richness map that rises toward the north and thins at the dry and wet edges of the compositional gradient.

library(sf)
library(dplyr)
library(ggplot2)

set.seed(7)
lon_range <- c(23.40, 23.72)
lat_range <- c(46.62, 46.90)

n_pts <- 900
pool <- data.frame(lon = runif(n_pts, lon_range[1], lon_range[2]),
                   lat = runif(n_pts, lat_range[1], lat_range[2]))

# east-west gradient drives which species occur; south-north drives how many
pool$env  <- 10 * (pool$lon - lon_range[1]) / diff(lon_range)
pool$prod <- (pool$lat - lat_range[1]) / diff(lat_range)   # 0 south .. 1 north

species <- sprintf("sp%02d", 1:12)
opt <- seq(1, 9, length.out = length(species))   # each species peaks at its own point
w   <- 1.6
occ <- do.call(rbind, lapply(seq_along(species), function(i) {
  prob <- (0.2 + 0.8 * pool$prod) * exp(-((pool$env - opt[i])^2) / (2 * w^2))
  hit  <- runif(n_pts) < prob
  if (!any(hit)) return(NULL)
  data.frame(species = species[i], lon = pool$lon[hit], lat = pool$lat[hit])
}))

nrow(occ)

[1] 2325

head(occ)

  species      lon      lat
1    sp01 23.43702 46.89398
2    sp01 23.47800 46.68298
3    sp01 23.45307 46.86184
4    sp01 23.43082 46.79905
5    sp01 23.42710 46.88506
6    sp01 23.40279 46.65932

From a data frame to spatial points

Right now occ is an ordinary data frame with two columns that happen to hold coordinates. st_as_sf() turns it into a spatial object by naming those columns and stating their coordinate reference system. The records are longitude and latitude in degrees, which is the system EPSG code 4326, also called WGS84.

pts <- st_as_sf(occ, coords = c("lon", "lat"), crs = 4326)
pts

Simple feature collection with 2325 features and 1 field
Geometry type: POINT
Dimension:     XY
Bounding box:  xmin: 23.40047 ymin: 46.62073 xmax: 23.71754 ymax: 46.89957
Geodetic CRS:  WGS 84
First 10 features:
   species                  geometry
1     sp01 POINT (23.43702 46.89398)
2     sp01   POINT (23.478 46.68298)
3     sp01 POINT (23.45307 46.86184)
4     sp01 POINT (23.43082 46.79905)
5     sp01  POINT (23.4271 46.88506)
6     sp01 POINT (23.40279 46.65932)
7     sp01 POINT (23.50131 46.83239)
8     sp01 POINT (23.45943 46.69458)
9     sp01 POINT (23.50225 46.74057)
10    sp01 POINT (23.45209 46.73221)

The print now shows a geometry column and a header describing the CRS and the bounding box. Each row is still one occurrence, but the position is a real point that sf can measure and join against.

Projecting before measuring

Degrees are fine for storing where something is, but poor for measuring. A degree of longitude covers a different ground distance at the equator than near the poles, so a grid built in degrees would have cells of unequal area. The fix is to project the points onto a flat system whose units are metres. This region sits in UTM zone 34 north, EPSG code 32634, so a grid built there is honest about distance.

pts_utm <- st_transform(pts, 32634)
st_crs(pts_utm)$epsg

[1] 32634

A grid, and species per cell

st_make_grid() lays a regular net over the extent of the points. A two kilometre cell is a reasonable resolution for this region. Wrapping the result with st_sf() and a cell_id makes it a proper layer that can carry attributes.

grid <- st_make_grid(pts_utm, cellsize = 2000, square = TRUE)
grid <- st_sf(cell_id = seq_along(grid), geometry = grid)
nrow(grid)

[1] 208

st_join() attaches to every point the cell it falls in (the default test is st_intersects). After that, richness per cell is a plain grouped count of distinct species. Cells that caught no records drop out, so the map shows only the surveyed area.

grid_rich <- st_join(pts_utm, grid) |>
  st_drop_geometry() |>
  group_by(cell_id) |>
  summarise(richness = n_distinct(species), n_records = n(), .groups = "drop") |>
  right_join(grid, by = "cell_id") |>
  st_as_sf() |>
  filter(!is.na(richness))

range(grid_rich$richness)

[1]  1 11

The map

geom_sf() reads the geometry directly, so the grid and the points need no x and y aesthetics. Filling the cells by richness and dropping the raw points on top shows both the pattern and the sampling behind it.

ggplot() +
  geom_sf(data = grid_rich, aes(fill = richness), color = "white", linewidth = 0.25) +
  geom_sf(data = pts_utm, size = 0.3, color = "#16241d", alpha = 0.22) +
  scale_fill_gradient(low = "#f5f4ee", high = "#275139", name = "Species\nrichness") +
  labs(x = NULL, y = NULL) +
  theme_minimal(base_size = 12)

The map reads the way the data was built. The north holds the richest cells, the south is thinner, and within any band the middle of the region carries more species than the far east or west, because the edge species of the compositional gradient drop out there. The graticule still shows degrees even though the data is now in metres, because geom_sf() reprojects the grid lines for display.

Handing off to QGIS

R is good at the analysis; QGIS is often where the final cartography happens. A GeoPackage moves the result across cleanly. It is a single open file that QGIS opens natively, and st_write() produces it. The same call works for the points, so both layers travel together.

st_write(grid_rich, "richness_grid.gpkg", delete_dsn = TRUE)
st_write(pts_utm,   "occurrences.gpkg",   delete_dsn = TRUE)

Open richness_grid.gpkg in QGIS and the cells arrive with the richness field ready to style, project, and lay out as a finished figure.

Where to go next

sf is the backbone for vector work in R: points, lines, and polygons, with joins, buffers, and distance calculations on top. From here, the same grid can be joined to polygons such as protected areas or administrative units to summarise richness within them, st_buffer() and st_distance() answer proximity questions, and the terra package covers the raster side when the environment comes as continuous surfaces rather than points. With the GeoPackage written, the rest of the map can move to QGIS whenever that is the better tool for the layout.

A grassland survey

The dataset is a constructed one again, so that we know the right answer in advance. Thirty grassland plots fall into three management regimes, ten plots each: grazed, mown, and abandoned. For every plot we have soil moisture, soil pH, and counts for fourteen plant species. Moisture drives a turnover of specialists from dry to wet ground. Management acts on top of that: grazing favours low ruderal species and suppresses tall ones, abandonment does the reverse, and mowing sits in between. Soil pH was measured too, but it was scattered at random across the plots, so it should turn out to explain nothing. That last point matters, because a method worth using has to be able to return a clear negative.

library(vegan)
library(ggplot2)
library(dplyr)

set.seed(42)

n_per <- 10
mgmt  <- factor(rep(c("Grazed", "Mown", "Abandoned"), each = n_per),
                levels = c("Grazed", "Mown", "Abandoned"))
n <- length(mgmt)

moisture <- round(runif(n, 1, 9), 1)     # structuring gradient
pH       <- round(runif(n, 5.2, 7.3), 1) # measured, but random by design

species <- c("Thymus", "Sedum", "Festuca", "Briza", "Trifolium", "Plantago",
             "Lotus", "Filipendula", "Juncus", "Carex", "Taraxacum", "Poa",
             "Achillea", "Urtica")
peaks <- seq(0.5, 9.5, length.out = length(species))
base  <- outer(moisture, peaks, function(m, p) 8 * exp(-((m - p)^2) / (2 * 1.8^2)))
colnames(base) <- species

# management shifts the balance of ruderal and tall competitor species
ruderal    <- c("Taraxacum", "Poa", "Trifolium", "Plantago", "Lotus")
competitor <- c("Filipendula", "Urtica", "Carex")
mult <- matrix(1, n, length(species), dimnames = list(NULL, species))
mult[mgmt == "Grazed",    ruderal]    <- 2.4
mult[mgmt == "Grazed",    competitor] <- 0.35
mult[mgmt == "Abandoned", ruderal]    <- 0.4
mult[mgmt == "Abandoned", competitor] <- 2.4

comm <- matrix(rpois(length(base * mult), as.vector(base * mult)), nrow = n)
colnames(comm) <- species
rownames(comm) <- sprintf("S%02d", 1:n)

env <- data.frame(moisture = moisture, pH = pH, mgmt = mgmt)
table(mgmt)

mgmt
   Grazed      Mown Abandoned 
       10        10        10 

comm[1:5, 1:7]

    Thymus Sedum Festuca Briza Trifolium Plantago Lotus
S01      0     0       0     0         1        2     5
S02      0     0       0     0         1        1     1
S03      3     2       6     9        17       16    11
S04      0     0       0     0         2        5     1
S05      0     1       1     2         9        9    17

The ordination, briefly

The ordination itself is the same recipe as last time: Bray-Curtis dissimilarities, then metaMDS(). The earlier post covers what the arguments mean and how to read the stress.

set.seed(42)
ord <- metaMDS(comm, distance = "bray", k = 2, trymax = 100,
               autotransform = FALSE, trace = FALSE)
ord$stress

[1] 0.0715636

A stress around 0.07 is a good fit, so the map is worth interpreting. Everything below works from this ord object and the matching env table.

envfit: which variables line up with the map?

envfit() takes the ordination and a table of environmental variables and asks, for each variable, how well it aligns with the arrangement of sites. A continuous variable is fitted as a vector: the direction across the plot along which it increases fastest, with an r-squared for how tightly the sites follow that direction and a permutation p-value for whether the alignment beats chance. A factor is fitted as a set of centroids, one mean position per group, with its own r-squared and test.

set.seed(42)
fit <- envfit(ord, env, permutations = 999)
fit

***VECTORS

            NMDS1    NMDS2     r2 Pr(>r)    
moisture -0.97781 -0.20950 0.9756  0.001 ***
pH       -0.55593 -0.83123 0.0361  0.624    
---
Signif. codes:  0 '***' 0.001 '**' 0.01 '*' 0.05 '.' 0.1 ' ' 1
Permutation: free
Number of permutations: 999

***FACTORS:

Centroids:
                NMDS1   NMDS2
mgmtGrazed     0.0525 -0.5261
mgmtMown       0.0208  0.0242
mgmtAbandoned -0.0733  0.5019

Goodness of fit:
         r2 Pr(>r)  
mgmt 0.2189  0.017 *
---
Signif. codes:  0 '***' 0.001 '**' 0.01 '*' 0.05 '.' 0.1 ' ' 1
Permutation: free
Number of permutations: 999

The reading is clean. Moisture aligns almost perfectly with the ordination (r-squared near 0.98) and is highly significant. Management separates its three centroids and is significant as well, though it accounts for less. Soil pH, exactly as built, lands near zero and is not significant, so we have our negative control back. On the plot we draw only the vector that earned its place.

mgmt_cols <- c(Grazed = "#cda23f", Mown = "#2f8f63", Abandoned = "#b5534e")
site_sc <- as.data.frame(scores(ord, "sites"))
site_sc$mgmt <- mgmt

# scale the significant vector by hand so its length reflects strength
arr    <- scores(fit, "vectors")
radius <- max(abs(as.matrix(site_sc[, 1:2])))
mul    <- 0.78 * radius / max(sqrt(rowSums(arr^2)))
moist  <- as.data.frame(arr["moisture", , drop = FALSE] * mul)

ggplot(site_sc, aes(NMDS1, NMDS2)) +
  geom_hline(yintercept = 0, color = "#e2e1d4") +
  geom_vline(xintercept = 0, color = "#e2e1d4") +
  stat_ellipse(aes(color = mgmt), linewidth = 0.6, level = 0.95) +
  geom_point(aes(color = mgmt, fill = mgmt), size = 3.4, shape = 21, stroke = 0.3) +
  geom_segment(data = moist, aes(x = 0, y = 0, xend = NMDS1, yend = NMDS2),
               arrow = arrow(length = unit(0.18, "cm")),
               color = "#16241d", linewidth = 0.8) +
  annotate("text", x = moist$NMDS1 * 1.05, y = moist$NMDS2 * 1.05 - 0.07,
           label = "moisture", hjust = 1, color = "#16241d",
           fontface = "italic", size = 3.3) +
  scale_color_manual(values = mgmt_cols, name = "Management") +
  scale_fill_manual(values = mgmt_cols, name = "Management") +
  coord_equal(xlim = c(-2.3, 1.8), ylim = c(-0.9, 0.9)) +
  theme_minimal(base_size = 12)

Two things are worth keeping in mind about envfit. A vector arrow assumes the variable changes smoothly and roughly linearly across the ordination plane. When a variable instead peaks in the middle and falls off at both ends, a straight arrow misrepresents it, and ordisurf() is the better tool: it drapes a fitted smooth surface over the ordination instead of a single direction. And a significant envfit result describes alignment with an existing picture, not a formal model of composition. For the latter, the next function is the one you want.

PERMANOVA with adonis2: do the groups really differ?

Seeing three ellipses stack up is suggestive, but eyes find groups in noise. adonis2() runs PERMANOVA, which partitions the dissimilarity matrix among the predictors and asks, by reshuffling group labels many times, whether each predictor explains more of the total composition than random labelling would.

set.seed(42)
adonis2(vegdist(comm, "bray") ~ mgmt + moisture + pH,
        data = env, permutations = 999, by = "terms")

Permutation test for adonis under reduced model
Terms added sequentially (first to last)
Permutation: free
Number of permutations: 999

adonis2(formula = vegdist(comm, "bray") ~ mgmt + moisture + pH, data = env, permutations = 999, by = "terms")
         Df SumOfSqs      R2       F Pr(>F)    
mgmt      2   1.4106 0.22436  9.0308  0.001 ***
moisture  1   2.8622 0.45524 36.6484  0.001 ***
pH        1   0.0620 0.00986  0.7940  0.501    
Residual 25   1.9525 0.31054                   
Total    29   6.2874 1.00000                   
---
Signif. codes:  0 '***' 0.001 '**' 0.01 '*' 0.05 '.' 0.1 ' ' 1

Each row carries a pseudo-F, an R-squared, and a permutation p-value. The R-squared is the share of the total multivariate variation that the term accounts for. Moisture takes the largest share, management a solid further chunk, and pH almost nothing, with a p-value that confirms it. The residual line is the variation left unexplained.

One detail decides how you read the table. by = "terms" adds the predictors in order, so each is tested on what is left after the ones above it. by = "margin" instead tests each predictor with all the others already accounted for. When predictors are independent, as moisture and management are here by construction, the two versions agree closely. When predictors are correlated, they can disagree sharply, and the order you wrote the formula in starts to change the story. Reaching for by = "margin" is the safer habit whenever you are unsure.

betadisper: is the difference real, or just uneven spread?

PERMANOVA has a trap that catches a lot of published work. It can return a significant result not because the group centroids sit in different places, but because the groups differ in how spread out they are internally. A tight cluster and a diffuse cloud can test as significantly different even with the same centre. betadisper() measures each plot’s distance to its own group centroid and tests whether that spread differs between groups.

bd <- betadisper(vegdist(comm, "bray"), mgmt)
set.seed(42)
permutest(bd, permutations = 999)

Permutation test for homogeneity of multivariate dispersions
Permutation: free
Number of permutations: 999

Response: Distances
          Df  Sum Sq  Mean Sq      F N.Perm Pr(>F)
Groups     2 0.05701 0.028504 0.9162    999  0.401
Residuals 27 0.84001 0.031112                     

data.frame(mgmt = mgmt, dist = bd$distances) %>%
  ggplot(aes(mgmt, dist, fill = mgmt)) +
  geom_boxplot(width = 0.55, outlier.shape = NA, alpha = 0.85) +
  geom_jitter(width = 0.12, size = 1.6, color = "#2c3a31") +
  scale_fill_manual(values = mgmt_cols, guide = "none") +
  labs(x = NULL, y = "Distance to group centroid") +
  theme_minimal(base_size = 12)

The test comes back non-significant (p around 0.4), and the box plot agrees: the three groups scatter to a similar degree around their centres. That clears the PERMANOVA. The significant management effect is a genuine difference in where the groups sit in composition space, not an artefact of one regime being more variable than another. Had betadisper() been significant, the PERMANOVA p-value would have been unsafe to read as a centroid difference, and you would say so rather than quietly report the F-test. Running the two together, and reporting both, is the honest minimum.

Where to go next

The three functions form a small workflow: envfit() to see which gradients align with the map, adonis2() to test whether groupings explain composition, and betadisper() to make sure that test means what you think. From here, a pairwise PERMANOVA tells you which specific managements differ rather than just that some do; ordisurf() handles variables whose response curves bend; and constrained methods such as distance-based RDA (capscale() and dbrda()) let you model composition directly against predictors instead of fitting them onto an unconstrained map after the fact.

What ordination is for

A community dataset is wide. One row per site, one column per species, counts in the cells. Past three species you can no longer plot the sites directly, because every species is its own axis. Ordination compresses those many axes down to two or three that you can look at, while keeping similar sites close together and different sites far apart. The input is not the raw table but a matrix of pairwise dissimilarities between sites, so the first real decision is how to measure dissimilarity.

A dataset with a known answer

Survey data never arrives with a key, so for learning it helps to build a table whose answer you already know. Below are sixteen sites along a moisture gradient, running from a dry ridge to a wet hollow. Nine specialist species each peak at a different point on that gradient, and three generalists turn up across the whole transect at low numbers. The counts are deliberately small, so every cell carries some sampling noise, the way real plots do.

library(vegan)
library(ggplot2)
library(dplyr)
library(tidyr)

set.seed(1)

n_sites  <- 16
gradient <- seq(0, 10, length.out = n_sites)   # true moisture, dry to wet

# nine specialists, each peaking at a different point on the gradient
specialists <- c("Thymus", "Sedum", "Festuca", "Briza", "Trifolium",
                 "Plantago", "Filipendula", "Juncus", "Carex")
peaks  <- seq(0.5, 9.5, length.out = length(specialists))
lambda <- outer(gradient, peaks, function(g, p) 7 * exp(-((g - p)^2) / (2 * 1.5^2)))
spec_counts <- matrix(rpois(length(lambda), as.vector(lambda)), nrow = n_sites)

# three generalists present across the whole transect at low numbers
generalists <- matrix(rpois(n_sites * 3, lambda = 4), nrow = n_sites)

comm <- as.data.frame(cbind(spec_counts, generalists))
colnames(comm) <- c(specialists, "Taraxacum", "Poa", "Achillea")
rownames(comm) <- sprintf("Site%02d", seq_len(n_sites))

comm[1:6, 1:7]

       Thymus Sedum Festuca Briza Trifolium Plantago Filipendula
Site01      5     5       1     0         0        0           0
Site02      6    12       1     1         0        0           0
Site03      6     6       6     1         0        0           0
Site04      7     9       7     5         2        0           0
Site05      1     9       9     5         0        1           0
Site06      3     2       3     5         6        0           0

A picture of the whole table makes the structure obvious.

sp_levels <- c(specialists, "Taraxacum", "Poa", "Achillea")
long <- comm %>%
  mutate(Site = rownames(comm)) %>%
  pivot_longer(-Site, names_to = "Species", values_to = "Abundance") %>%
  mutate(Species = factor(Species, levels = sp_levels),
         Site    = factor(Site, levels = rev(rownames(comm))))

ggplot(long, aes(Species, Site, fill = Abundance)) +
  geom_tile(color = "white", linewidth = 0.4) +
  scale_fill_gradient(low = "#f5f4ee", high = "#275139") +
  labs(x = NULL, y = NULL, fill = "Count") +
  theme_minimal(base_size = 11) +
  theme(axis.text.x = element_text(angle = 45, hjust = 1))

Reading down any specialist column, the species rises and falls as you move along the transect; the generalists stay flat. This staircase of overlapping peaks is the signal NMDS has to recover. It also explains why we do not simply run PCA on the raw counts. Species do not track a gradient in straight lines: they appear, peak, and drop out again. A method that assumes linear relationships distorts that badly. NMDS avoids the problem by working only from the rank order of dissimilarities, so the exact shape of each response curve stops mattering.

Measuring dissimilarity first

vegdist() turns the site-by-species table into pairwise dissimilarities. Bray-Curtis is the usual choice for abundance data. It runs from 0 (identical composition) to 1 (no shared species), and it ignores shared absences, so two sites are not counted as alike merely because the same rare species is missing from both.

bray <- vegdist(comm, method = "bray")
round(as.matrix(bray)[1:5, 1:5], 2)

       Site01 Site02 Site03 Site04 Site05
Site01   0.00   0.23   0.25   0.32   0.50
Site02   0.23   0.00   0.26   0.25   0.36
Site03   0.25   0.26   0.00   0.24   0.29
Site04   0.32   0.25   0.24   0.00   0.23
Site05   0.50   0.36   0.29   0.23   0.00

Neighbouring sites sit near zero; sites from opposite ends of the transect climb toward one. That ordering is the only thing NMDS will use.

Running the NMDS

metaMDS() does the work. It computes the dissimilarities, drops the sites onto the plane at random, then shifts them around until the map distances line up with the dissimilarity ranks as closely as possible, repeating the whole thing from many random starts so a single unlucky start cannot decide the outcome.

set.seed(1)
ord <- metaMDS(comm, distance = "bray", k = 2, trymax = 100,
               autotransform = FALSE, trace = FALSE)
ord

Call:
metaMDS(comm = comm, distance = "bray", k = 2, trymax = 100,      autotransform = FALSE, trace = FALSE) 

global Multidimensional Scaling using monoMDS

Data:     comm 
Distance: bray 

Dimensions: 2 
Stress:     0.08219387 
Stress type 1, weak ties
Best solution was repeated 11 times in 20 tries
The best solution was from try 7 (random start)
Scaling: centring, PC rotation, halfchange scaling 
Species: expanded scores based on 'comm' 

Each argument earns its place. k = 2 asks for a two-dimensional map. trymax = 100 caps how many random starts are allowed. autotransform = FALSE is worth a note: left on its default, metaMDS() will square-root the counts and apply a standardisation before measuring distance, which is sensible for messy field data but would no longer match the Bray-Curtis matrix we just inspected. Turning it off keeps the steps aligned. set.seed() matters because the starting positions are random, so the run only reproduces if the seed is fixed. trace = FALSE simply silences the per-iteration log.

The printed summary reports the stress (here about 0.08) and a line such as Best solution was repeated 11 times in 20 tries, which says how many of the random starts agreed on the same answer. Those two figures drive the next two sections.

Stress: does the map fit?

Stress measures how much the flat map has to distort the original dissimilarity ranks to fit them into two dimensions. Zero would be a perfect rank match; larger values mean the map is forcing relationships that the data do not support. Clarke’s much-quoted rule of thumb runs roughly: under 0.05 is excellent, under 0.1 is good, under 0.2 is usable but needs a second look, and over 0.3 is barely better than random. A stress near 0.08 sits in the good band, so the picture is worth reading.

To see the fit rather than summarise it, stressplot(ord) draws the Shepard diagram: observed dissimilarities against the map distances, with a step line for the fitted monotonic regression. Points hugging that line are what you want.

How many dimensions?

Two dimensions was a choice, not a rule. One way to test it is to refit the same NMDS across a range of dimensions and watch where the stress stops falling sharply.

stress_k <- sapply(1:4, function(k) {
  set.seed(1)
  metaMDS(comm, distance = "bray", k = k, trymax = 100,
          autotransform = FALSE, trace = FALSE)$stress
})
round(stress_k, 3)

[1] 0.177 0.082 0.049 0.027

ggplot(data.frame(k = 1:4, stress = stress_k), aes(k, stress)) +
  geom_hline(yintercept = 0.1, linetype = "dashed", color = "#b9534e") +
  geom_line(color = "#93a87f", linewidth = 0.9) +
  geom_point(color = "#275139", size = 3.2) +
  scale_x_continuous(breaks = 1:4) +
  labs(x = "Dimensions (k)", y = "Stress") +
  theme_minimal(base_size = 12)

The big improvement from one dimension to two tells us a single axis is too cramped for this data. The small gains after two tell us that further dimensions would mostly be fitting noise. Two is also the number you can actually plot, which is why it is so often where people stop.

Convergence: did it settle?

Because every run starts from random coordinates, one NMDS could land on a poor arrangement by chance. metaMDS() guards against that by repeating the fit and checking whether the best arrangement keeps coming back. A summary line like Best solution was repeated 11 times in 20 tries is the reassurance: when most of the starts reach the same configuration, the result is unlikely to be a quirk of one random seed. If instead you see no convergent solutions, or a best solution found only once, raise trymax and treat the result as provisional until it stabilises.

Reading the map

site_sc <- as.data.frame(scores(ord, display = "sites"))
site_sc$moisture <- gradient
spec_sc <- as.data.frame(scores(ord, display = "species"))
spec_sc$species <- rownames(spec_sc)

ggplot(site_sc, aes(NMDS1, NMDS2)) +
  geom_hline(yintercept = 0, color = "#dad9ca") +
  geom_vline(xintercept = 0, color = "#dad9ca") +
  geom_text(data = spec_sc, aes(label = species),
            color = "#9a6a2f", fontface = "italic", size = 3.2) +
  geom_point(aes(color = moisture), size = 5) +
  geom_text(aes(label = sub("Site", "", rownames(site_sc))),
            color = "white", size = 2.6, fontface = "bold") +
  scale_color_gradient(low = "#c9b458", high = "#1d5b4e", name = "Moisture") +
  coord_equal() +
  theme_minimal(base_size = 12)

The sites are coloured by their true position on the moisture gradient, the one piece of information NMDS never saw. They line up almost cleanly along the first axis, dry gold on the left, wet green on the right. We can attach a number to that:

abs(cor(site_sc$NMDS1, site_sc$moisture))

[1] 0.9305619

A correlation around 0.93 between the first axis and the real gradient, recovered from nothing but the species counts. The sign of an NMDS axis is arbitrary, so left versus right carries no meaning beyond the ordering itself. The species labels say the same thing from the other direction: the dry-ground plants (Thymus, Sedum) sit at one end, the sedges and rushes (Carex, Juncus) at the other, and the three generalists fall near the centre, because turning up everywhere is much the same as preferring nowhere.

Where to go next

NMDS hands you the picture; the natural follow-ups put statistics on it. envfit() overlays measured environmental variables as arrows, so you can ask which of them align with the ordination axes. adonis2() runs PERMANOVA, testing whether groups of sites differ in composition more than chance would allow, which is the formal counterpart to seeing clusters by eye. Both work from the same dissimilarity matrix you already built here.

A community matrix

vegan expects a community matrix: one row per site (or sample), one column per species, cells holding abundances (counts or cover). Here’s a small worked example, with counts of five plant species across four meadow plots:

library(vegan)
library(dplyr)
library(ggplot2)

community <- data.frame(
  row.names = c("Plot_A", "Plot_B", "Plot_C", "Plot_D"),
  Festuca   = c(10,  0, 25,  4),
  Trifolium = c( 8, 12,  2,  5),
  Plantago  = c( 5,  3,  1,  6),
  Achillea  = c( 2,  9,  0,  5),
  Lotus     = c( 0, 15,  0,  4)
)

community

       Festuca Trifolium Plantago Achillea Lotus
Plot_A      10         8        5        2     0
Plot_B       0        12        3        9    15
Plot_C      25         2        1        0     0
Plot_D       4         5        6        5     4

Each row is a plot; each column a species. Plot_C is dominated by Festuca, while Plot_D spreads its individuals evenly across all five species.

The three indices

vegan gives you each of these in a single call:

richness <- specnumber(community)                 # number of species present
shannon  <- diversity(community, index = "shannon")
simpson  <- diversity(community, index = "simpson")

richness

Plot_A Plot_B Plot_C Plot_D 
     4      4      3      5 

shannon

   Plot_A    Plot_B    Plot_C    Plot_D 
1.2550811 1.2658568 0.4086977 1.5974167 

simpson

   Plot_A    Plot_B    Plot_C    Plot_D 
0.6912000 0.6982249 0.1964286 0.7951389 

A few things worth knowing:

• specnumber() simply counts the non-zero species. It’s the most basic measure, and blind to abundance.
• Shannon (H′) rises with both richness and evenness; for real communities it usually falls between about 1.5 and 3.5.
• Simpson is returned here as 1 − D: the probability that two individuals drawn at random belong to different species. It runs from 0 to 1 and is less sensitive to rare species than Shannon.

A tidy results table

Let’s pull everything into one data frame, rounded for reading:

diversity_summary <- tibble(
  plot     = rownames(community),
  richness = richness,
  shannon  = round(shannon, 2),
  simpson  = round(simpson, 2)
) |>
  arrange(desc(shannon))

diversity_summary

# A tibble: 4 × 4
  plot   richness shannon simpson
  <chr>     <int>   <dbl>   <dbl>
1 Plot_D        5    1.6     0.8 
2 Plot_B        4    1.27    0.7 
3 Plot_A        4    1.26    0.69
4 Plot_C        3    0.41    0.2 

Plot_D comes out most diverse. It carries all five species at similar abundances, so its evenness is high. Plot_A and Plot_B land in the middle and almost tie (1.26 vs 1.27), despite very different species makeups. Plot_C, dominated by a single grass, scores lowest even though three species are present. That gap between richness and Shannon is the evenness effect at work.

A plot

Finally, the bit you’ll actually paste into a report: Shannon diversity per plot.

ggplot(diversity_summary, aes(x = reorder(plot, shannon), y = shannon)) +
  geom_col(fill = "#2f6b3e", width = 0.7) +
  geom_text(aes(label = shannon), hjust = -0.2, size = 3.5) +
  coord_flip() +
  labs(x = NULL, y = "Shannon diversity (H′)") +
  ylim(0, max(diversity_summary$shannon) * 1.15) +
  theme_minimal(base_size = 12)

Where to go next

This is the foundation. Realistic next steps:

• swap the toy matrix for your own data, read in with read.csv() into the same site-by-species shape;
• add Pielou’s evenness (shannon / log(richness)) to separate richness from evenness explicitly;
• once you have many sites, move from alpha to beta diversity and ordination (vegdist(), metaMDS()).

Ordination is the next post. If you hit a snag adapting this to your own data, let me know.