Package 'barrel'

Autoplot method for barrel_ord objects

Description

Generates a ggplot of site scores from a vegan ordination object with optional group ellipses, centroids, and environmental arrows. This method is designed to work with ordination objects prepared using barrel_prepare.

Usage

## S3 method for class 'barrel_ord'
autoplot(object, ...)

Arguments

object

An object of class "barrel_ord" (a vegan ordination object with attached metadata).

...

Additional arguments: group Character. Grouping variable in the metadata. (Required) data Optional species or environmental data for envfit. kind Type of ellipse: "se" or "sd". Default is "se". method Covariance method: "classic" or "robust". Default is "classic". conf Confidence level for ellipses. Default is 0.95. geom_type "polygon" or "path" for ellipse. Default is "polygon". show_arrows Logical; whether to show envfit vectors. Default is TRUE. show_centroids Logical. Default is FALSE. show_ellipses Logical. Default is TRUE. show_labels Logical. Label envfit arrows. Default is TRUE. p_thresh Numeric. Significance threshold for arrows. Default 0.05. alpha Numeric. Transparency of ellipses. Default is 0.5.

Details

If geom_type = "polygon", group colors are mapped to fill for ellipses. If geom_type = "path", group colors are mapped to color. The grouping variable must be present in the metadata provided to barrel_prepare.

Value

A ggplot2 object with ordination scores and optional graphical layers.

See Also

barrel_prepare, stat_barrel, rda, metaMDS

Examples

library(vegan)
data(dune)
data(dune.env)
ord <- rda(dune, scale = TRUE)
ord <- barrel_prepare(ord, dune.env)
ggplot2::autoplot(ord,
  group = "Management", data = dune,
  method = "robust", kind = "sd", geom_type = "polygon", show_arrows = TRUE
)

---

Add Axis Titles with Method Name and Explained Variance

Description

This function creates properly formatted axis titles for ordination plots. It uses the ordination method name (e.g., RDA, dbRDA, NMDS) and, when available, the percentage of variance explained by the first two axes.

Usage

barrel_label_axes(ord)

Arguments

ord	A vegan ordination object, such as from rda(), cca(), capscale(), or metaMDS().

Details

The labels are retrieved using get_ord_axis_labels and returned as a ggplot2::labs() object that can be added to a plot.

Value

A ggplot2::labs() object with x and y axis titles.

See Also

get_ord_axis_labels

Examples

library(vegan)
library(ggplot2)
data(dune)
data(dune.env)

# Example with RDA
ord <- rda(dune)
scores_df <- as.data.frame(scores(ord, display = "sites"))
scores_df$Management <- dune.env$Management

ggplot(scores_df, aes(x = PC1, y = PC2, color = Management)) +
  geom_point() +
  barrel_label_axes(ord) +
  theme_minimal() +
  theme(axis.title = element_text(face = "bold", size = 13))

---

Summary Statistics for Ordination Objects

Description

Computes adjusted R-squared and percentage of variance explained for constrained ordination methods (e.g., rda, cca, capscale, dbrda), or returns the stress value for non-metric multidimensional scaling (metaMDS).

Usage

barrel_ord_summary(ord)

Arguments

ord	An ordination object of class rda, cca, capscale, dbrda, or metaMDS.

Value

A named list with components:

method

Class of the ordination object as a character string.

R2_adj

Adjusted R-squared (percentage) for constrained ordinations; NA for NMDS.

axis_var

Named numeric vector of variance explained by each axis (percentage), if available.

stress

Stress value for NMDS objects.

message

Message explaining output, especially for NMDS or missing R2.

Examples

library(vegan)
data(dune)
data(dune.env)

# PCA (unconstrained ordination)
pca <- rda(dune)
barrel_ord_summary(pca)

# RDA (constrained ordination)
rda_mod <- rda(dune ~ A1 + Moisture, data = dune.env)
barrel_ord_summary(rda_mod)

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

# dbRDA
dbrda_mod <- dbrda(dune ~ A1 + Management, data = dune.env, distance = "bray")
barrel_ord_summary(dbrda_mod)

---

Prepare ordination object for barrel plotting

Description

Attaches sample metadata (e.g., grouping variable) to a vegan ordination object and assigns class 'barrel_ord'.

Usage

barrel_prepare(ord, metadata)

Arguments

ord	A vegan ordination object (e.g., from rda, cca, metaMDS).
metadata	A data frame of sample metadata. Must have same number of rows as ordination site scores.

Value

The ordination object with metadata attached and class "barrel_ord".

Examples

library(vegan)
data(dune)
data(dune.env)
ord <- rda(dune, scale = TRUE)
ord_prepared <- barrel_prepare(ord, dune.env)
class(ord_prepared)

---

Comprehensive Ordination Visualization Layer

Description

Combines ordination ellipses, centroids, environmental arrows, and annotations into a ggplot2 layer.

Usage

stat_barrel(
  mapping = NULL,
  data = NULL,
  geom = "path",
  position = "identity",
  kind = "se",
  conf = 0.95,
  method = c("robust", "classic"),
  show.legend = NA,
  inherit.aes = TRUE,
  geom_type = c("path", "polygon"),
  ...
)

stat_barrel_centroid(
  mapping = NULL,
  data = NULL,
  geom = "point",
  position = "identity",
  method = c("classic", "robust"),
  show.legend = NA,
  inherit.aes = TRUE,
  shape = 3,
  ...
)

stat_barrel_arrows(
  mapping = NULL,
  data = NULL,
  ord,
  matrix,
  geom = "segment",
  position = "identity",
  labels = TRUE,
  labels.color = "black",
  labels.size = 3,
  labels.fontface = "plain",
  show.significant = FALSE,
  p_thresh = 0.05,
  arrow = grid::arrow(length = grid::unit(0.25, "cm")),
  arrow.color = "grey10",
  arrow.linetype = "solid",
  arrow.size = 0.3,
  labels.max.overlaps = Inf,
  show.legend = NA,
  inherit.aes = TRUE,
  ...
)

compute_envfit_vectors(ord, matrix, p_thresh = 0.05, show.significant = FALSE)

stat_barrel_annotate(
  mapping = NULL,
  data = NULL,
  ord,
  position = "identity",
  show.legend = FALSE,
  inherit.aes = TRUE,
  xpad = 0.05,
  ypad = 0.05,
  hjust = 0,
  vjust = 1,
  ...
)

Arguments

mapping	Set of aesthetic mappings created by aes().
data	Data frame used for plotting.
geom	Character; geometric object to use for ellipses, either "path" or "polygon".
position	Position adjustment for ggplot2 layers (default "identity").
kind	Character; type of ellipse: "se" (standard error), "sd" (dispersion), or "ci" (confidence interval).
conf	Numeric; confidence level for ellipses (default 0.95).
method	Character; covariance estimation method: "classic" or "robust".
show.legend	Logical; whether to show legends (default NA).
inherit.aes	Logical; whether to inherit aesthetics (default TRUE).
geom_type	Character; geometric object to use for ellipses, either "path" or "polygon".
...	Additional parameters passed to underlying geoms or stats.
shape	Integer; shape code for centroid points (default 3).
ord	Ordination object from vegan, e.g. rda, cca, dbrda, or metaMDS.
matrix	Optional data frame of environmental variables for arrows.
labels	Logical; whether to show labels on environmental arrows (default TRUE).
labels.color	Color of arrow labels (default "black").
labels.size	Numeric size of arrow labels (default 3).
labels.fontface	Font face of arrow labels (default "plain").
show.significant	Logical; whether to show only significant arrows (default FALSE).
p_thresh	Numeric; p-value threshold for significance filtering (default 0.05).
arrow	A grid arrow object controlling arrow appearance (default created by grid::arrow()).
arrow.color	Color of arrows (default "grey10").
arrow.linetype	Line type of arrows (default "solid").
arrow.size	Numeric line width of arrows (default 0.3).
labels.max.overlaps	Maximum number of labels in the same space (default "Inf").
xpad	Numeric; horizontal padding for annotation text relative to x-axis range (default 0.05).
ypad	Numeric; vertical padding for annotation text relative to y-axis range (default 0.05).
hjust	Numeric; horizontal justification of annotation text (default 0).
vjust	Numeric; vertical justification of annotation text (default 1).

Details

Comprehensive Ordination Visualization Layer

This set of ggplot2 stats draws ellipses around groups, centroids, environmental arrows, and adds adjusted R^2 or stress annotation for ordination objects from vegan.

Value

A ggplot2 layer combining ellipses, centroids, arrows, and annotations.

Examples

library(ggplot2)
library(vegan)
library(robustbase)
data(dune)
data(dune.env)

pca <- vegan::rda(dune, scale = TRUE)
scores <- as.data.frame(vegan::scores(pca, display = "sites"))
scores$Management <- dune.env$Management

ggplot(scores, aes(PC1, PC2, group = Management, fill = Management)) +
  stat_barrel(
    method = "classic", kind = "se", conf = 0.95, geom_type = "polygon",
    alpha = 0.4, color = "black"
  ) +
  stat_barrel_centroid(method = "classic", shape = 3) +
  stat_barrel_arrows(
    ord = pca, matrix = dune,
    labels = TRUE, labels.color = "blue",
    arrow.color = "darkred", arrow.linetype = "solid",
    labels.fontface = "bold", show.significant = TRUE,
    labels.overlaps = Inf,
  ) +
  stat_barrel_annotate(ord = pca, xpad = 0.05, ypad = 0.05) +
  geom_point(aes(color = Management)) +
  theme_minimal()

---

Internal function to get axis labels for vegan ordination objects

Description

This function infers the ordination method used and returns proper axis labels including percentage of explained variance when applicable.

Usage

get_ord_axis_labels(ord)

Arguments

ord	A vegan ordination object.

Value

A list with one element label, a character vector for axis labels. #' @examples library(vegan) data(dune) data(dune.env) ord_pca <- rda(dune) get_ord_axis_labels(ord_pca)

---

Compute coordinates for an ordination ellipse

Description

Calculates ellipse coordinates based on a covariance matrix and center. Supports confidence ellipses (standard error, "se") or dispersion ellipses ("sd").

Usage

ord_compute_ellipse(
  cov,
  center = c(0, 0),
  kind = "se",
  conf = 0.95,
  npoints = 100,
  n = NULL
)

Arguments

cov	Numeric matrix (2x2) covariance matrix.
center	Numeric vector of length 2 specifying the ellipse center coordinates.
kind	Character string specifying the type of ellipse: either "se" for standard error/confidence ellipse or "sd" for standard deviation dispersion ellipse.
conf	Numeric confidence level or coverage (default 0.95).
npoints	Integer number of points to generate along ellipse perimeter (default 100).
n	Numeric sample size; required if kind = "se".

Value

A numeric matrix with two columns representing x and y coordinates of the ellipse.

Examples

cov_mat <- matrix(c(1, 0, 0, 1), 2, 2)
center <- c(0, 0)
ell_coords <- ord_compute_ellipse(cov_mat, center, kind = "se", conf = 0.95, n = 10)
plot(ell_coords, type = "l")

---

Compute Ellipse Coordinates for a Single Group

Description

Calculates ellipse coordinates for one group in ordination scores with robust or classic covariance.

Usage

ord_ellipse_group(
  scores,
  group_var,
  group_name,
  axis1,
  axis2,
  kind = "se",
  conf = 0.95,
  method = "classic"
)

Arguments

scores	Data frame of ordination scores.
group_var	Name of grouping column.
group_name	Name of the group to calculate ellipse.
axis1	Name of first axis column.
axis2	Name of second axis column.
kind	Type of ellipse: "se" or "sd".
conf	Confidence level.
method	Covariance method: "classic" or "robust".

Details

Compute ellipse coordinates for a specific group in ordination scores

Calculates ellipse coordinates for one group from ordination scores, supporting classical or robust covariance estimation.

Value

Data frame of ellipse coordinates with group label.

A data frame with ellipse coordinates and group label.

Examples

library(vegan)
data(dune)
data(dune.env)
pca <- rda(dune, scale = TRUE)
scores <- as.data.frame(scores(pca, display = "sites"))
scores$Group <- dune.env$Management
ell <- ord_ellipse_group(scores, "Group", "BF", "PC1", "PC2", kind = "se", method = "classic")
plot(ell$PC1, ell$PC2, type = "l")

---

Compute Ellipse Coordinates for All Groups

Description

Calculates ellipse coordinates for all groups in ordination scores.

Usage

ord_ellipse_groups(
  scores,
  group_var,
  axis1,
  axis2,
  kind = "se",
  conf = 0.95,
  method = "classic"
)

Arguments

scores	Data frame of ordination scores.
group_var	Name of grouping column.
axis1	Name of first axis column.
axis2	Name of second axis column.
kind	Type of ellipse: "se" or "sd".
conf	Confidence level.
method	Covariance method: "classic" or "robust".

Details

Compute ellipse coordinates for all groups in ordination scores

Calculates ellipse coordinates for all groups in ordination scores, supports classic and robust covariance estimation.

Value

Data frame of ellipse coordinates with group labels.

---

Extract Group Centroids from Ordination Scores

Description

Computes centroids per group using classic mean or robust methods.

Usage

ord_extract_centroids(
  scores,
  group_var,
  axis1,
  axis2,
  method = c("classic", "robust")
)

Arguments

scores	Data frame of ordination scores.
group_var	Name of grouping column.
axis1	Name of first axis column.
axis2	Name of second axis column.
method	Centroid method: "classic" or "robust".

Details

Extract centroids of groups from ordination scores with classic or robust method

Computes the centroid coordinates for each group using either the classical mean or robust minimum covariance determinant.

Value

Data frame with group centroids.

---

Extract covariance matrix from ordination scores with optional robust estimation

Description

Computes the covariance matrix of ordination scores, optionally using robust estimation.

Usage

ord_extract_cov(
  scores,
  axis1,
  axis2,
  weights = NULL,
  method = c("classic", "robust")
)

Arguments

scores	Data frame of ordination scores.
axis1	Name of first axis column.
axis2	Name of second axis column.
weights	Optional numeric vector of weights.
method	Covariance method: "classic" or "robust".

Value

2x2 covariance matrix.

---

Extract significant environmental vectors from vegan ordination object

Description

Performs an envfit analysis and returns environmental vectors with p-values, filtered by significance or unfiltered.

Usage

ord_vectors(
  ord,
  data,
  p_thresh = 0.05,
  filter = c("significant", "nonsignificant", "all")
)

Arguments

ord	Vegan ordination object (e.g., rda, cca).
data	Environmental variables data frame used for envfit.
p_thresh	P-value threshold to determine significance (default 0.05).
filter	Character; one of "significant" (default), "nonsignificant", or "all".

Value

Data frame of vectors with scores, p-values, and labels.

---