Summaries of invasion fitness: species invasiveness, trait effects, and site invasibility — summarise_invasiveness

Invasion fitness $\lambda_{is}$ integrates structure in trait space (distances, overlaps, convex hull, cloud centroid) with abiotic suitability (alignment to environment), niche crowding (overlap with residents weighted by composition), and resident competition (site saturation). summarise_invasiveness_invasibility() collapses the site × invader surface into species, trait, and site summaries that are actionable and map-readyeither using a probabilistic measure $P(F>0)$ or a hard rule $I\{\lambda>0\}$.

Species invasiveness (per invader) summarises breadth of establishment across sites: $$V_i = |S|^{-1}\sum_s \mathbb{I}\{\lambda_{is}>0\}\quad \text{or}\quad \tilde V_i = |S|^{-1}\sum_s P(F>0\mid i,s).$$

Site invasibility (per site) quantifies openness to newcomers: $$V_s = |I|^{-1}\sum_i \mathbb{I}\{\lambda_{is}>0\}\quad \text{or}\quad \tilde V_s = |I|^{-1}\sum_i P(F>0\mid i,s).$$

Trait invasiveness scores which invader traits explain variation in $V_i$, via standardized slopes for continuous traits and ANOVA $R^2$ for categorical traits.

Usage

summarise_invasiveness_invasibility(
  lambda_is = NULL,
  p_is = NULL,
  use_probabilistic = FALSE,
  prob_threshold = 0.5,
  site_df = NULL,
  traits_inv = NULL,
  comm_res = NULL,
  return_long = TRUE,
  make_plots = TRUE,
  label = NULL
)

Arguments

lambda_is: Matrix $S\times I$ of invasion fitness (rows = sites, cols = invaders). If NULL, you must supply p_is. Provide row/column names.
p_is: Optional matrix $S\times I$ of establishment probabilities (e.g., from compute_establishment_probability()).
use_probabilistic: Logical. If TRUE, summaries use p_is (expected values). If FALSE, summaries use the hard rule $I\{\lambda>0\}$.
prob_threshold: Numeric in (0,1). If use_probabilistic=TRUE and you still want a binary view for selected outputs/maps, cells with p_is >= prob_threshold count as 1.
site_df: Optional data frame with columns site, x, y for mapping. If missing, maps are omitted but tabular summaries are still returned.
traits_inv: Optional data frame of invader traits for trait summaries; rownames must be invader IDs (matching colnames(lambda_is) or colnames(p_is)). May contain numeric and factor columns; non‐trait columns can be present.
comm_res: Optional site × resident matrix for relative metrics; used to compute per-site resident richness for extra normalization (optional).
return_long: Logical. If TRUE, include a tidy long table for the site×invader surface.
make_plots: Logical. If TRUE, return ggplot objects for maps/bars/heatmaps.
label: Optional character label used in plot titles and output metadata.

Value

A list with:

species: data frame with species-level invasiveness metrics (probabilistic and/or hard).
site: data frame with site-level invasibility metrics (probabilistic and/or hard + map coords if provided).
trait_effects: data frame of trait effect sizes (|β| for continuous; ANOVA $R^2$ for categorical).
establish_long: tidy long table of the working surface (val = probability or 0/1; includes lambda if available).
plots: list of ggplot objects (may be NULL if make_plots=FALSE or ggplot2 not installed), including: site_map, invader_rank, heatmap, trait_effects.
meta: list with mode ("probabilistic" or "hard"), threshold, and label.

Details

Summarize invasion fitness into species, trait, and site metrics (with plots)

Working surface. If use_probabilistic=TRUE, the core surface is p_is (expected establishments). If FALSE, it is the binary matrix $I\{\lambda>0\}$. If both p_is and lambda_is are supplied, both are used: the probabilistic summaries use p_is, the hard-rule summaries come from lambda_is.

Trait effects. For each numeric trait $T_k$, we fit a simple regression $$\tilde V_i \sim T_{ik}$$ and report the standardized slope $|\beta_k|$. For each factor trait, we report ANOVA $R^2$ from a one-way model. These are quick effect sizes to rank traits; more elaborate models can be layered later.

Examples

set.seed(42)
S = 8; I = 5
sites = paste0("s", 1:S)
inv   = paste0("i", 1:I)

# Fake fitness and probabilities
lambda_is = matrix(rnorm(S*I, sd=1), S, I, dimnames=list(sites, inv))
p_is      = pnorm(lambda_is)  # crude probit just for the example

# Minimal site coordinates for plotting (optional)
site_df = data.frame(site = sites,
                      x = rep(1:4, each=2)[1:S],
                      y = rep(1:2, times=4)[1:S])

# Minimal trait table for invaders (one numeric, one factor)
traits_inv = data.frame(trait_size = runif(I, 0, 1),
                         trait_type = factor(sample(c("A","B"), I, TRUE)),
                         row.names = inv)

# 1) Probabilistic summaries (use p_is)
outP = summarise_invasiveness_invasibility(
  lambda_is = lambda_is,
  p_is      = p_is,
  use_probabilistic = TRUE,
  site_df   = site_df,
  traits_inv = traits_inv,
  make_plots = FALSE
)
names(outP)
#> [1] "species"        "site"           "trait_effects"  "establish_long"
#> [5] "plots"          "meta"          
head(outP$species)
#> # A tibble: 5 × 5
#>   invader   V_i n_sites V_i_hard n_hard
#>   <chr>   <dbl>   <int>    <dbl>  <dbl>
#> 1 i1      0.636       8    0.625      5
#> 2 i2      0.625       8    0.5        4
#> 3 i3      0.380       8    0.25       2
#> 4 i4      0.514       8    0.5        4
#> 5 i5      0.349       8    0.375      3

# 2) Hard rule summaries (use I{lambda>0})
outH = summarise_invasiveness_invasibility(
  lambda_is = lambda_is,
  use_probabilistic = FALSE,
  site_df = site_df,
  traits_inv = traits_inv,
  make_plots = FALSE
)
head(outH$site)
#> # A tibble: 6 × 9
#>   site    V_s n_inv total_expected     x     y V_s_hard n_est n_fail
#>   <chr> <dbl> <int>          <dbl> <int> <int>    <dbl> <dbl>  <dbl>
#> 1 s1      0.8     5              4     1     1      0.8     4      1
#> 2 s2      0       5              0     1     2      0       0      5
#> 3 s3      0.6     5              3     2     1      0.6     3      2
#> 4 s4      0.6     5              3     2     2      0.6     3      2
#> 5 s5      0.4     5              2     3     1      0.4     2      3
#> 6 s6      0       5              0     3     2      0       0      5