Skip to contents

Compute Trait Space: per-trait similarity + community dispersion

Source: R/compute_trait_space.R
compute_trait_space.Rd

A unified workflow that (1) computes within-trait similarity (numeric + categorical) and (2) computes community-level dispersion in trait space (Gower → clustering → PCoA → density → metrics).

Usage

compute_trait_space(
  trait_df,
  species_col = 1,
  do_similarity = TRUE,
  similarity_cols = NULL,
  do_dispersion = TRUE,
  k = 4,
  pcoa_dims = 2,
  abundance = NULL,
  kde_n = 100,
  viridis_option = "D",
  show_density_plot = TRUE,
  show_plots = FALSE,
  seed = NULL
)

Arguments

trait_df

data.frame. One row per species (or unit); mixed types allowed.

species_col

integer or character (default = 1). Column indicating the species ID; excluded from distances.

do_similarity

logical (default = TRUE). If TRUE, compute per-trait similarity.

similarity_cols

NULL, character, or integer. Which columns to use for similarity; default = all columns except species_col.

do_dispersion

logical (default = TRUE). If TRUE, run the dispersion pipeline.

k

integer (default = 4). Number of clusters for dendrogram.

pcoa_dims

integer (default = 2). Number of PCoA axes retained (≥ 2).

abundance

numeric vector or NULL. Optional species weights; normalized internally.

kde_n

integer (default = 100). KDE grid resolution for density.

viridis_option

character (default = "D"). Palette for viridisLite::viridis().

show_density_plot

logical (default = TRUE). Also emit a base filled.contour.

show_plots

logical (default = FALSE). If TRUE, prints a patchwork of ggplots.

seed

integer or NULL. Optional RNG seed.

Value

A list with (present elements depend on flags):

  • similarity: data.frame with columns Trait, Similarity (0-100).

  • dispersion: list containing distance_matrix, hc, pcoa, scores, centroid, metrics_df, and plots (ggplots: $dend, $density_gg, $centrality_hist, $metrics_bar).

Examples

# Simulate a small mixed-type table
set.seed(123)
n <- 20
trait_df <- data.frame(
  species = paste0("sp_", seq_len(n)),
  height = rnorm(n),
  mass = runif(n, -1, 1),
  rank = factor(sample(1:3, n, TRUE), ordered = TRUE),
  bin = factor(sample(c(0, 1), n, TRUE)),
  cat = factor(sample(LETTERS[1:4], n, TRUE)),
  check.names = FALSE
)
abundance <- rexp(n)

out <- compute_trait_space(trait_df,
  species_col = "species", abundance = abundance,
  k = 3, pcoa_dims = 2, show_density_plot = FALSE
)
out$similarity
#>    Trait Similarity
#> 1 height   70.29966
#> 2   mass   64.59100
#> 3   rank   30.00000
#> 4    bin   47.36842
#> 5    cat   23.15789
out$dispersion$metrics_df
#>   Metric     Value
#> 1   FDis 0.3150657
#> 2   FRic 0.3730231
#> 3   RaoQ 0.1981680