Compute trait-based interaction strengths and resident abundance matrix — compute_interaction

Computes a trait-based pairwise interaction matrix for all species (residents + invaders) using Gower distance (default) or another dissimilarity metric, with options for:

Kernelisation (distance, similarity, gaussian)
Scaling/standardisation
Sparsification (e.g., k-nearest neighbour graph)

Also returns Nstar, a site x resident abundance matrix from predicted values.

Usage

compute_interaction_strength(
  traits,
  predDF,
  method = "gower",
  kernel = c("distance", "similarity", "gaussian"),
  sigma = NULL,
  standardise = FALSE,
  sparsify_k = NULL
)

Arguments

traits: data.frame. Species traits, first column = species name, remaining = traits.
predDF: data.frame. Long table with columns site_id, species, and predicted abundance.
method: character. Distance metric for daisy (default "gower").
kernel: character. One of "distance", "similarity", "gaussian".
sigma: numeric. Gaussian kernel bandwidth; if NULL, set to median non-zero distance.
standardise: logical. If TRUE, scale distances to 0,1 before kernelisation.
sparsify_k: integer. If non-NULL, retain only k-nearest neighbours per species (symmetrised).

Value

A list with components:

g_all: Processed interaction matrix (distance / similarity / Gaussian kernel).
raw_distance: Unscaled pairwise distance matrix (e.g., Gower).
Nstar: Site x resident abundance matrix (rows = residents, cols = sites).
sigma: Bandwidth used when kernel = "gaussian"; otherwise NULL.

Details

The trait-based interaction strength matrix (g_all) is used in community assembly and invasion models to quantify potential biotic effects between species. We recommend Gower distance for mixed traits, as it is scale-free and bounded in 0,1.

The resident abundance matrix (Nstar) summarises equilibrium or expected abundances for resident species at each site, based on predictions from the fitted abundance model.

Kernelisation options:

"distance": return dissimilarities directly (default for transparent interpretation).
"similarity": convert to similarity in 0,1 by 1 - scaled_distance.
"gaussian": Gaussian kernel \(K = exp(-D^2 / (2\sigma^2))\), with automatic \(\sigma\) as the median non-zero distance if not supplied.

Examples

# --- Minimal, reproducible examples ---------------------------------------
set.seed(1)

# Toy trait table: first column is species name (3 residents + 2 invaders)
traits <- data.frame(
  species = c("sp1","sp2","sp3","inv1","inv2"),
  body_size = c(10, 12, 8, 11, 9),                # numeric
  diet      = factor(c("herb","herb","omn","omn","herb")),  # factor
  activity  = c(0.2, 0.8, 0.5, 0.6, 0.4)          # numeric
)

# Long table of predicted resident abundances across 4 sites
sites <- paste0("s", 1:4)
predDF <- expand.grid(site_id = sites, species = traits$species,
                      KEEP.OUT.ATTRS = FALSE, stringsAsFactors = FALSE)
predDF$pred <- rexp(nrow(predDF), rate = 1)

# --- 1) Plain distance (default): Gower dissimilarities --------------------
res_dist <- compute_interaction_strength(
  traits  = traits,
  predDF  = predDF,
  method  = "gower",
  kernel  = "distance"
)
#> Error in predDF %>% dplyr::filter(species %in% residents) %>% dplyr::select(species,     site_id, pred) %>% tidyr::pivot_wider(names_from = site_id,     values_from = pred) %>% tibble::column_to_rownames("species") %>%     as.matrix(): could not find function "%>%"
# Inspect
round(res_dist$raw_distance, 3)
#> Error: object 'res_dist' not found
round(res_dist$g_all, 3)       # same as raw distances for kernel = "distance"
#> Error: object 'res_dist' not found
res_dist$Nstar[, 1:2]          # first two sites (residents x sites)
#> Error: object 'res_dist' not found

# --- 2) Similarity in [0,1] (1 - scaled distance) --------------------------
res_sim <- compute_interaction_strength(
  traits      = traits,
  predDF      = predDF,
  kernel      = "similarity",
  standardise = TRUE            # scale distances to [0,1] before 1 - D
)
#> Error in predDF %>% dplyr::filter(species %in% residents) %>% dplyr::select(species,     site_id, pred) %>% tidyr::pivot_wider(names_from = site_id,     values_from = pred) %>% tibble::column_to_rownames("species") %>%     as.matrix(): could not find function "%>%"
round(res_sim$g_all, 3)        # higher = more similar (stronger interaction)
#> Error: object 'res_sim' not found

# --- 3) Gaussian kernel on distances ---------------------------------------
#      sigma chosen automatically as median non-zero distance
res_gauss <- compute_interaction_strength(
  traits = traits,
  predDF = predDF,
  kernel = "gaussian"          # K = exp(-D^2 / (2*sigma^2))
)
#> Error in predDF %>% dplyr::filter(species %in% residents) %>% dplyr::select(species,     site_id, pred) %>% tidyr::pivot_wider(names_from = site_id,     values_from = pred) %>% tibble::column_to_rownames("species") %>%     as.matrix(): could not find function "%>%"
round(res_gauss$g_all, 3)
#> Error: object 'res_gauss' not found
res_gauss$sigma                # bandwidth actually used
#> Error: object 'res_gauss' not found

# --- 4) Sparsify to a k-NN graph (here k = 2), symmetrised -----------------
res_sparse <- compute_interaction_strength(
  traits     = traits,
  predDF     = predDF,
  kernel     = "similarity",
  standardise = TRUE,
  sparsify_k = 2
)
#> Error in predDF %>% dplyr::filter(species %in% residents) %>% dplyr::select(species,     site_id, pred) %>% tidyr::pivot_wider(names_from = site_id,     values_from = pred) %>% tibble::column_to_rownames("species") %>%     as.matrix(): could not find function "%>%"
round(res_sparse$g_all, 3)     # only each species' 2 strongest links retained
#> Error: object 'res_sparse' not found

# Notes:
# - Residents are inferred as species whose names do NOT start with "inv".
# - For mixed traits, Gower ("gower") is recommended; keep `standardise = TRUE`
#   when converting to similarity or when kernelising.