Model residents and build standardized predictors ($r_{js}^{(z)}, C_{js}^{(z)}, S_{js}^{(z)}$)

Fits the residents-only GLMM and constructs site-standardised predictors used to learn sensitivities and to project invaders. Specifically: (i) builds a design using environment and resident traits, (ii) optionally dummy-expands factors and performs PCA compression with stored centering/scale metadata for reproducible projection, (iii) fits a glmmTMB model on resident abundance, (iv) predicts linear predictors $r_{js}$ then applies row-wise z-scoring to obtain $r_{js}^{(z)}$, and (v) row-z-standardises resident crowding $C_{js}$ and computes site saturation summaries $S_s$, $S_{s}^{(z)}$, $S_{js}^{(z)}$.

Usage

model_residents(
  fit,
  family = glmmTMB::tweedie(link = "log"),
  include_env_trait_interactions = TRUE,
  saturation_mode = c("evenness_deficit", "opportunity_penalty", "modelled_dominance"),
  robust_r = TRUE,
  robust_c = TRUE,
  fit_model = TRUE,
  max_dense_gb = 8,
  reduce_strategy = c("auto", "none", "no_interactions", "pca"),
  pca_env_k = 5,
  pca_trait_k = 5,
  verbose = TRUE
)

Arguments

fit: An invasimapr_fit returned by prepare_trait_space(); must contain inputs$comm_res, inputs$env_df, inputs$traits_res, and crowding$C_js (raw, not z-scored).
family: A glmmTMB family (default glmmTMB::tweedie(link = "log")).
include_env_trait_interactions: Logical; whether to include environment × trait interactions in the fixed effects (when not reduced).
saturation_mode: One of c("evenness_deficit","opportunity_penalty","modelled_dominance"); forwarded to compute_site_saturation().
robust_r, robust_c: Logical; use robust row-wise z-scoring for $r_{js}$ and $C_{js}$ respectively.
fit_model: Logical; if FALSE, preflight only (build design/estimate memory footprint) and return without fitting.
max_dense_gb: Numeric; maximum allowed dense fixed-effects design size (in GB) for preflight in "auto" mode.
reduce_strategy: One of c("auto","none","no_interactions","pca").
pca_env_k, pca_trait_k: Integers; number of PCs to retain for the environment and trait blocks under PCA reduction.
verbose: Logical; emit progress/messages.

Value

The input invasimapr_fit with updated components:

model: Lists of standardised inputs (env_df_z, traits_res_glmm), means/SDs, and—if PCA used—*_pca, *_pca_vars, *_pca_center, *_pca_scale, and *_pca_info needed for invader projection.
residents: GLMM fit (fit_r), model frame (dat_r), grid for predictions, raw linear predictor matrix r_js, mean scale mu_js, and row-z outputs r_js_z with per-site means/SDs; similarly C_js_z and saturation summaries (S_s, S_s_z, S_js_z).
model$pca_used: Flags and counts recording whether PCA was used and the retained dimensionality.

Details

Design construction The base frames env_df_z and traits_res_glmm are created by robust standardisation. Characters are coerced to factors to ensure stable dummy-expansion. In "pca" reduction, each block undergoes: model.matrix one-hot encoding (no intercept) → per-column standardisation → prcomp() with stored centring/scales and rotation rownames. This metadata supports lossless, future projection of invaders (see predict_invaders()).

Preflight memory check A rough dense design GB estimate is computed on the fixed-effects portion (random terms stripped). "auto" reduction iteratively lowers complexity to meet max_dense_gb.

Z-standardisation Row-wise z-scoring uses .row_z() (robust if requested) and stores site-wise means/SDs for later use in mapping probabilities and fitness.

Reduction strategies

Use reduce_strategy to control the fixed-effects size/complexity.

"auto": preflights a dense design estimate; if memory budget exceeded, falls back to "no_interactions", then "pca", then "pca+no_interactions".
"no_interactions": drops all env × trait interactions.
"pca": dummy-expand → standardise → prcomp() on the design blocks (environment and traits) and use the first pca_env_k/pca_trait_k PCs.
"none": keep full model as requested by include_env_trait_interactions.

Examples

if (FALSE) { # \dontrun{
fit <- prepare_inputs(sites = site_df, residents = resident_df,
                      invaders = invader_df, traits = trait_df)
fit <- prepare_trait_space(fit, traits_inv)
fit <- model_residents(fit, reduce_strategy = "auto", verbose = TRUE)

# Inspect z-standardised predictors for residents
dim(fit$residents$r_js_z); dim(fit$residents$C_js_z)
fit$residents$messages
} # }

Model residents and build standardized predictors (\(r_{js}^{(z)}, C_{js}^{(z)}, S_{js}^{(z)}\))