Skip to contents

Assemble site- and species-specific competition/impact matrices

Source: R/assemble_matrices.R
assemble_matrices.Rd

Builds a 3D array of per-site interaction terms by combining: (1) invader and resident abundances, (2) trait-based competition coefficients \(a_{ij}\), and (3) environmental matching between each site and residents. The result is a tensor I_raw[invader, resident, site] suitable for summarising total competitive pressure on each invader at each site.

Usage

assemble_matrices(
  a_ij,
  Nstar,
  invader_pred_wide = NULL,
  predictions = NULL,
  env_dist,
  sigma_e = NULL,
  K_env = NULL
)

Arguments

a_ij

numeric matrix (invaders × residents). Trait-based competition coefficients (e.g., from compute_competition()). Row names = invader IDs; column names = resident IDs.

Nstar

numeric matrix (residents × sites). Resident abundances by site (e.g., from compute_interaction_strength()). Row names = resident IDs; column names = site IDs.

invader_pred_wide

numeric matrix (sites × invaders) or NULL. Site × invader abundances on the response scale. If NULL, supply predictions instead.

predictions

data.frame or NULL. Long table with columns species, site_id, pred. Used only if invader_pred_wide is NULL.

env_dist

numeric matrix (sites × residents). Site-resident environmental distance (e.g., from compute_environment_kernel()). Row names = site IDs; column names = resident IDs.

sigma_e

numeric or NULL. Bandwidth for the Gaussian environmental kernel; if NULL, compute the kernel upstream (e.g., compute_environment_kernel(..., kernel = "gaussian")) and pass it via K_env.

K_env

numeric matrix (sites × residents) or NULL. Optional precomputed environmental kernel (similarity) for residents by site. If supplied, env_dist and sigma_e are ignored.

Value

A list with:

  • I_raw: 3D array (invaders × residents × sites) of per-pair impact terms.

  • pressure_inv_site: matrix (invaders × sites) with total pressure on each invader at each site (sum over residents).

  • meta: list with matched IDs and dimensions.

Details

For site \(s\), invader \(i\), resident \(j\): $$I_{i j s} = r_{i s}\, r_{j s}\, a_{i j}\, K^{(env)}_{j s},$$ where \(r_{i s}\) and \(r_{j s}\) are predicted (or expected) abundances, \(a_{i j} = \exp\!\big(-d_{i j}^2/(2\,\sigma_t^2)\big)\) is the trait-based competition coefficient, and \(K^{(env)}_{j s}\) is an environmental matching kernel for resident \(j\) at site \(s\).

Examples

# Minimal, self-contained toy example
set.seed(1)
inv <- paste0("inv", 1:2)
res <- paste0("sp", 1:3)
sites <- paste0("s", 1:4)

# invader × resident Gaussian kernel (a_ij)
a_ij <- matrix(runif(length(inv) * length(res), 0.1, 0.9),
  nrow = length(inv), dimnames = list(inv, res)
)

# residents × sites abundances (Nstar)
Nstar <- matrix(abs(rnorm(length(res) * length(sites), 5, 2)),
  nrow = length(res), dimnames = list(res, sites)
)

# site × resident environmental kernel (K_env)
K_env <- matrix(runif(length(sites) * length(res), 0.3, 1),
  nrow = length(sites), dimnames = list(sites, res)
)

# long predictions data.frame (pred) with r_is
predictions <- expand.grid(site_id = sites, species = inv)
predictions$pred <- rlnorm(nrow(predictions), 0, 0.4)

am <- assemble_matrices(
  a_ij = a_ij, Nstar = Nstar,
  K_env = K_env, predictions = predictions
)
str(am)
#> List of 3
#>  $ I_raw            : num [1:2, 1:3, 1:4] 2.23 2.03 3.798 4.021 0.968 ...
#>   ..- attr(*, "dimnames")=List of 3
#>   .. ..$ : chr [1:2] "inv1" "inv2"
#>   .. ..$ : chr [1:3] "sp1" "sp2" "sp3"
#>   .. ..$ : chr [1:4] "s1" "s2" "s3" "s4"
#>  $ pressure_inv_site: num [1:2, 1:4] 7 8.22 5.22 8.25 2.73 ...
#>   ..- attr(*, "dimnames")=List of 2
#>   .. ..$ : chr [1:2] "inv1" "inv2"
#>   .. ..$ : chr [1:4] "s1" "s2" "s3" "s4"
#>  $ meta             :List of 6
#>   ..$ n_inv    : int 2
#>   ..$ n_res    : int 3
#>   ..$ n_sites  : int 4
#>   ..$ invaders : chr [1:2] "inv1" "inv2"
#>   ..$ residents: chr [1:3] "sp1" "sp2" "sp3"
#>   ..$ sites    : chr [1:4] "s1" "s2" "s3" "s4"