Predict site-level responses for residents and simulated invaders

Builds a complete site × species prediction grid by crossing a species-trait table (residents + simulated invaders) with a site-environment table, then calls the fitted model’s predict() to obtain expected responses (e.g., abundance). The function is robust to factor level issues and mirrors a typical expand_grid() + left-join workflow.

Usage

predict_invader_response(
  model,
  species_traits,
  site_env,
  species_col = "species",
  site_col = "site_id",
  response_type = "response",
  include_random = FALSE,
  site_aug = NULL,
  species_aug = NULL
)

Arguments

model: Fitted model object (glmmTMB, lme4, mgcv, or base stats).
species_traits: data.frame. Species traits (one row per species) containing species_col and all trait variables referenced in the model’s fixed effects.
site_env: data.frame. Site predictors (one row per site) containing site_col and all environmental variables referenced in the model’s fixed effects.
species_col: character. Species ID column in species_traits. Default "species".
site_col: character. Site ID column in site_env. Default "site_id".
response_type: character. Prediction scale for predict() where applicable (e.g., "response" or "link"). Default "response".
include_random: logical. If FALSE (default), compute population-level predictions (exclude random effects). If TRUE, compute conditional predictions (include random effects; allow new levels where supported).
site_aug: NULL or data.frame. Optional site-level augmentation table (must contain site_col) to be left-joined into site_env before prediction.
species_aug: NULL or data.frame. Optional species-level augmentation table (must contain species_col) to be left-joined into species_traits.

Value

A list with:

newdata: the site × species table used in predict().
predictions: long table with columns site_col, species_col, and pred.
prediction_matrix: wide matrix (sites × species) of predicted values (rows ordered by site ID, columns by species ID).

Details

Model classes supported

glmmTMB: uses type and re.form. Population-level predictions set re.form = ~ 0 (default, include_random = FALSE); conditional predictions use re.form = NULL with allow.new.levels = TRUE.
lme4::merMod (lmer/glmer): population-level uses re.form = NA; conditional uses re.form = NULL with allow.new.levels = TRUE.
mgcv::gam: passes type through (e.g., "response").
stats::glm / stats::lm: standard predict(); type for GLM, none for LM.

Why population-level predictions by default? For novel invaders, random-effect levels (e.g., species/site intercepts) are unknown. Excluding random effects yields fixed-effects expectations driven by traits, environments, and their interactions — appropriate for invasion screening and ranking.

Augmentation inputs. site_aug and/or species_aug let you add extra predictors (e.g., obs_sum, spp_rich) prior to prediction, replicating the common left_join() pattern used in analysis notebooks.

Examples

if (FALSE) { # \dontrun{
# Residents + invaders (traits), sites (env), fitted Tweedie glmmTMB model:
all_traits <- rbind(spp_trait, inv_traits)
out <- predict_invader_response(
  model          = mod,
  species_traits = all_traits,
  site_env       = site_env,
  species_col    = "species",
  site_col       = "site_id",
  response_type  = "response",
  include_random = FALSE, # population-level
  site_aug       = dplyr::select(spp_rich_obs, site_id, obs_sum, spp_rich)
)
head(out$predictions)
dim(out$prediction_matrix)
} # }