Learn sensitivities (alpha_i, beta_i, theta_i/gamma_i) and optional site-varying alpha_is, Gamma_is

Fits an auxiliary GLMM on resident data to estimate invader-level sensitivities to crowding and saturation ($\alpha_i$, $\beta_i$), and abiotic conversion slopes ($\theta_i$ or $\gamma_i$). When supported by the data, optional site-level random slopes yield site-varying adjustments ($\alpha_{is}$, $\Gamma_{is}$).

Results are written into the fit$sensitivities slot of an new_invasimapr_fit object for downstream invasion-fitness and establishment calculations.

Usage

learn_sensitivities(fit, use_site_random_slopes = TRUE, lrt = TRUE)

Arguments

fit: An object produced by prepare_inputs and assemble_matrices, containing resident predictor matrices (r_js_z, C_js_z, S_js_z), trait-space structures (Q_res, Q_inv), and the resident community layout (inputs$comm_res).
use_site_random_slopes: Logical; if TRUE, the auxiliary model includes site-level random slopes for abiotic and crowding terms, enabling estimation of site-varying $\alpha_{is}$ and $\Gamma_{is}$ when supported by the data. Defaults to TRUE.
lrt: Logical; if TRUE, compute Wald or likelihood-ratio tests for key contrasts (e.g., trait-varying versus global slopes). Defaults to TRUE.

Value

The input fit object (invisibly), with an updated fit$sensitivities list.

Details

Fits an auxiliary GLMM on resident data to estimate invader-level sensitivities to crowding and saturation (alpha_i, beta_i), and abiotic conversion slopes (theta_i or gamma_i), with optional site-varying random slopes that yield per-site adjustments (alpha_is, Gamma_is). Results are written into the fit$sensitivities slot of an invasimapr_fit object for downstream invasion-fitness and establishment steps.

Workflow

Fit an auxiliary GLMM on resident responses using fit_auxiliary_residents_glmm, optionally including site-level random slopes for $r_z$ and $C_z$.
Convert GLMM coefficients to sensitivities ($\alpha_i$, $\beta_i$, $\theta_i$ or $\gamma_i$) using derive_sensitivities, returning signed and unsigned variants plus inference summaries.
When supported, extract site-varying effects ($\alpha_{is}$, $\Gamma_{is}$) via site_varying_alpha_beta_gamma.

The resulting components are stored in fit$sensitivities, including:

global and trait-varying sensitivities;
inference diagnostics and clamping summaries;
optional site-varying matrices and compact decomposition tables.

Examples

if (FALSE) { # \dontrun{
fit <- prepare_inputs(
  sites = site_df,
  residents = resident_df,
  invaders = invader_df,
  traits = trait_df
)

fit <- learn_sensitivities(fit, use_site_random_slopes = TRUE)
names(fit$sensitivities)
} # }