Visualizing Ordinations with barrel

Introduction

Multivariate ordination methods are widely used in ecology to analyze community structure and environmental gradients. While plotting tools exist in packages such as vegan and ggvegan, they often lack flexibility or require verbose and complex ggplot construction. The barrel package provides a streamlined, modular, and tidyverse-compatible framework for generating informative ordination graphics with minimal code.

Installation

# install.packages("devtools")
devtools::install_github("XXXX/barrel")

Load packages and example data

library(vegan)
library(ggplot2)
library(ggrepel)
library(barrel)

data(dune)
data(dune.env)

Supported ordination methods examples

# NMDS
nmds <- metaMDS(dune, k = 2)

# RDA
rda_res <- rda(dune ~ A1 + Moisture + Management, data = dune.env)

# dbRDA / capscale
dbrda_res <- capscale(dune ~ A1 + Moisture, data = dune.env, distance = "bray")

Quickstart with autoplot()

autoplot() arguments

Argument	Description	Default
`group`	Grouping variable used to compute ellipses and centroids	(required)
`data`	Community matrix used to extract environmental vectors	`NULL`
`kind`	Type of ellipse: `"se"`, `"sd"`, or `"ci"`	`"se"`
`conf`	Confidence level for ellipses	`0.95`
`method`	Covariance method: `"classic"` or `"robust"`	`"classic"`
`geom_type`	Ellipse representation: `"polygon"` or `"path"`	`"polygon"`
`show_arrows`	Whether to plot environmental arrows	`TRUE`
`show_labels`	Whether to label arrows	`TRUE`
`show_centroids`	Whether to draw group centroids	`FALSE`
`show_ellipses`	Whether to draw ellipses	`TRUE`
`p_thresh`	P-value threshold for displaying arrows	`0.05`
`alpha`	Transparency of ellipses	`0.5`

The autoplot() function provides a fast way to visualize ordination results using minimal syntax. It detects the ordination method and automatically adds ellipses, centroids, and environmental vectors if desired. Below we apply it to NMDS, RDA, and dbRDA models using the dune dataset.

ord.ndms <- barrel_prepare(nmds, dune.env)
autoplot(ord.ndms, group = "Management", data = dune)

ord.rda <- barrel_prepare(rda_res, dune.env)
autoplot(ord.rda, group = "Management", data = dune)

ord.dbrda <- barrel_prepare(dbrda_res, dune.env)
autoplot(ord.dbrda, group = "Management", data = dune)

Understanding `kind`: standard error vs. standard deviation

The kind argument in autoplot() and stat_barrel() determines the type of ellipse that is drawn around each group. It affects how dispersion or precision is visualized:

kind	Description
`"se"`	Standard error of group centroids. Shrinks with larger sample size. Useful to show precision. (default)
`"sd"`	Standard deviation of observations. Reflects spread of the group, independent of sample size.
`"ci"`	Confidence interval based on t-distribution. Included for flexibility, but less common.

# Compare ellipse types
autoplot(ord.rda, group = "Management", data = dune, kind = "se")
autoplot(ord.rda, group = "Management", data = dune, kind = "sd")

Customizing autoplot()

You can customize the graphical output of autoplot() by specifying parameters that control ellipse type, confidence level, covariance estimation method, and which components to display. The following examples show how to use these options to adapt the plots to your analysis goals.

autoplot(ord.ndms, group = "Management", data = dune,
         kind = "se", method = "classic", conf = 0.95,
         geom_type = "path",
         show_arrows = FALSE, show_labels = FALSE,
         show_centroids = TRUE, show_ellipses = TRUE)

autoplot(ord.rda, group = "Management", data = dune,
         kind = "se", method = "classic", conf = 0.95,
         geom_type = "polygon",
         show_arrows = FALSE, show_labels = FALSE,
         show_centroids = TRUE, show_ellipses = TRUE,
         p_thresh = 0.05,
         alpha = 0.5)

autoplot(ord.dbrda, group = "Management", data = dune,
         kind = "sd", method = "classic", conf = 0.68,
         geom_type = "polygon",
         show_arrows = TRUE, show_labels = TRUE,
         show_centroids = FALSE, show_ellipses = TRUE,
         alpha = 0.5)

Example: robust method with outliers

Robust methods can improve ordination visualizations when your data contain outliers or strong deviations from multivariate normality. In this example, we simulate two well-separated groups along with an extreme outlier to show how the method = "robust" option changes ellipse estimation and compare with method = "classic".

# Simulated data with outliers and groups
set.seed(123)
sim_data <- matrix(NA, nrow = 15, ncol = 4)

# Group A: 4 normal + 1 strong outlier
sim_data[1:4, ] <- matrix(rnorm(4 * 4, mean = 5), ncol = 4)
sim_data[5, ]   <- rep(30, 4)

# Group B: 5 normal
sim_data[6:10, ] <- matrix(rnorm(5 * 4, mean = 7), ncol = 4)

# Group C: 4 normal + 1 mild outlier
sim_data[11:14, ] <- matrix(rnorm(4 * 4, mean = 6), ncol = 4)
sim_data[15, ]    <- rnorm(4, mean = 12)

# Metadata
metadata <- data.frame(Management = factor(rep(c("A", "B", "C"), each = 5)))

# Labels
colnames(sim_data) <- paste0("Sp", 1:4)
rownames(sim_data) <- paste0("Site", seq_len(nrow(sim_data)))


# Perform PCA
ord_sim <- rda(sim_data, scale = TRUE)
ord_sim <- barrel_prepare(ord_sim, metadata)

# Plot with method = "robust"
autoplot(ord_sim, group = "Management",
         kind = "se", method = "robust", conf = 0.95,
         geom_type = "polygon", alpha = 0.3,
         show_centroids = F, show_arrows = FALSE)
         
autoplot(ord_sim, group = "Management",
         kind = "sd", method = "robust", conf = 0.95,
         geom_type = "polygon", alpha = 0.3,
         show_centroids = F, show_arrows = FALSE)

autoplot(ord_sim, group = "Management",
         kind = "se", method = "classic", conf = 0.95,
         geom_type = "polygon", alpha = 0.3,
         show_centroids = F, show_arrows = FALSE)
         
autoplot(ord_sim, group = "Management",
         kind = "sd", method = "classic", conf = 0.95,
         geom_type = "polygon", alpha = 0.3,
         show_centroids = F, show_arrows = FALSE)

Full control with ggplot2 and stat_barrel_*

**stat_barrel_*() family arguments**

Function	Key arguments	Description	Default value(s)
`stat_barrel()`	`kind`, `conf`, `method`, `geom_type`	Draws ellipses around groups	`"se"`, `0.95`, `"classic"`, `"polygon"`
`stat_barrel_centroid()`	`method`, `shape`	Computes and draws group centroids	`"classic"`, `shape = 3`
`stat_barrel_arrows()`	`ord`, `matrix`, `labels`, `p_thresh`	Draws environmental vectors (via `envfit`)	`labels = TRUE`, `p_thresh = 0.05`
`stat_barrel_annotate()`	`ord`, `xpad`, `ypad`	Adds R²/stress annotation in bottom-left corner	`xpad = 0.05`, `ypad = 0.05`

If you want full flexibility over plot appearance and layering, you can use the individual stat_barrel_* functions directly within a ggplot() call. This allows you to customize geometry, color, shape, and statistical layers independently while leveraging the modular logic of the barrel package.

scores_df <- as.data.frame(scores(nmds, display = "sites"))
scores_df$Management <- dune.env$Management

ggplot(scores_df, aes(x = NMDS1, y = NMDS2, group = Management,
                      color = Management, fill = Management,
                      linetype = Management)) +
  geom_point(aes(shape = Management), size = 2) +
  stat_barrel(kind = "se", conf = 0.95, method = "classic",
              geom_type = "polygon", alpha = 0.3, color = "black") +
  stat_barrel_centroid(method = "classic", shape = 4, size = 3) +
  stat_barrel_arrows(ord = nmds, matrix = dune, labels = TRUE,
                     arrow.color = "black",
                     labels.color = "darkblue", labels.fontface = "bold",
                     show.significant = TRUE) +
  stat_barrel_annotate(ord = nmds) +
  labs(title = "NMDS ordination with ellipses, centroids, and arrows") +
  theme_minimal() +
  theme(legend.position = "top")

scores_rda <- as.data.frame(scores(rda_res, display = "sites"))
scores_rda$Management <- dune.env$Management

ggplot(scores_rda, aes(x = RDA1, y = RDA2, group = Management,
                       color = Management, fill = Management,
                       linetype = Management)) +
  geom_point(aes(shape = Management), size = 2) +
  stat_barrel(kind = "se", conf = 0.95, method = "classic",
              geom_type = "polygon",
              alpha = 0.3, color = "black") +
  stat_barrel_centroid(method = "classic", shape = 5, size = 3) +
  stat_barrel_arrows(ord = rda_res, matrix = dune, labels = TRUE,
                     arrow.color = "black",
                     labels.color = "blue", labels.fontface = "italic",
                     show.significant = TRUE) +
  stat_barrel_annotate(ord = rda_res) +
  labs(title = "RDA ordination") +
  theme_minimal() +
  theme(legend.position = "top")

Calculating ellipses, centroids, vectors manually

ellipses_df <- ord_ellipse_groups(scores_df, group_var = "Management",
                                  axis1 = "NMDS1", axis2 = "NMDS2",
                                  kind = "se", conf = 0.95, method = "classic")

centroids_df <- ord_extract_centroids(scores_df, "Management",
"NMDS1", "NMDS2", method = "classic")

env_vectors <- ord_vectors(nmds, dune, p_thresh = 0.05, filter = "significant")

Model summary with barrel_ord_summary()

barrel_ord_summary(nmds)
barrel_ord_summary(rda_res)
barrel_ord_summary(dbrda_res)

Getting help for individual functions

Once the package is installed, you can access help files with:

?ord_vectors
?ord_ellipse_groups
?barrel_ord_summary

Citation

To cite barrel, use:

citation("barrel")

Reproducibility

sessionInfo()

Visualizing Ordinations with barrel

Diego Barranco-Elena

2025-06-01

Introduction

Installation

Load packages and example data

Supported ordination methods examples

Quickstart with autoplot()

autoplot() arguments

Understanding `kind`: standard error vs. standard deviation

Customizing autoplot()

Example: robust method with outliers

Full control with ggplot2 and stat_barrel_*

**stat_barrel_*() family arguments**

Calculating ellipses, centroids, vectors manually

Model summary with barrel_ord_summary()

Getting help for individual functions

Citation

Reproducibility

Visualizing Ordinations with barrel

Diego Barranco-Elena

2025-06-01

Introduction

Installation

Load packages and example data

Supported ordination methods examples

Quickstart with autoplot()

autoplot() arguments

Understanding kind: standard error vs. standard deviation

Customizing autoplot()

Example: robust method with outliers

Full control with ggplot2 and stat_barrel_*

**stat_barrel_*() family arguments**

Calculating ellipses, centroids, vectors manually

Model summary with barrel_ord_summary()

Getting help for individual functions

Citation

Reproducibility

Understanding `kind`: standard error vs. standard deviation