Skip to contents

Learn sensitivities (αᵢ, βᵢ, θᵢ/γᵢ) and optional site-varying αᵢₛ, Γᵢₛ

Source: R/learn_sensitivities.R
learn_sensitivities.Rd

Fits an auxiliary GLMM on resident data to estimate invader-level sensitivities to crowding and saturation (αᵢ, βᵢ), and abiotic conversion slopes (θᵢ or γᵢ), with optional site-varying random slopes that yield per-site adjustments (αᵢₛ, Γᵢₛ). Results are written into the fit$sensitivities slot of an invasimapr_fit object for downstream invasion-fitness and establishment steps.

Usage

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

Arguments

fit

An object of class invasimapr_fit produced by prepare_inputs() / assemble_matrices(), containing resident matrices (r_js_z, C_js_z, S_js_z), trait-space structures (Q_res, Q_inv), and resident community layout (inputs$comm_res).

use_site_random_slopes

Logical; if TRUE, the auxiliary model is fit with site-level random slopes for the abiotic and crowding terms, enabling estimation of site-varying αᵢₛ and Γᵢₛ when supported by the data. Defaults to TRUE.

lrt

Logical; if TRUE, compute Wald/LRT summaries for key contrasts (e.g., trait-varying vs global slopes) to guide model choice and reporting. Defaults to TRUE.

Value

The input fit (invisibly) with an updated fit$sensitivities list (see Details).

Details

Workflow

  1. Build an auxiliary GLMM on resident responses via fit_auxiliary_residents_glmm(), optionally including random slopes (0 + r_z || site) and (0 + C_z || site) when use_site_random_slopes = TRUE.

  2. Convert GLMM coefficients to sensitivities (αᵢ, βᵢ, θᵢ/γᵢ) with derive_sensitivities(), returning signed/unsigned variants and summary tests (Wald/LRT).

  3. If supported, extract site-varying parameters (αᵢₛ, Γᵢₛ) using site_varying_alpha_beta_gamma(), along with decompositions into invader slopes and site deltas.

Output structure written to fit$sensitivities

  • fit_coeffs, data_used, formula: artefacts from the auxiliary GLMM.

  • alpha_i, beta_i, theta0, theta_i, gamma_i, alpha_signed_i, beta_signed_i: estimated sensitivities.

  • wald_lrt, sens_df, clamp_summary, prior_note: inference and diagnostics from derive_sensitivities().

  • site_alpha_beta_gamma: full list returned by site_varying_alpha_beta_gamma() (if available).

  • alpha_is, Gamma_is: site-varying crowding and abiotic matrices (if available).

  • site_alpha, site_gamma: compact bundles with decompositions and a narrow data frame for inspection/joins.

  • a0..a2, b0..b2: trait-plane slope/intercept components used by calibration steps downstream.

  • abg_df: tidy table of site × invader effects when available.

Robustness notes

  • Performs finite-value checks on resident predictors (r_js_z, C_js_z, S_js_z).

  • Resolves site identifiers from multiple possible locations to ensure compatibility with older and newer assemble_matrices() outputs.

See also

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, lrt = TRUE)
names(fit$sensitivities)
head(fit$sensitivities$sens_df)

# Example: map of site-varying Γ (if present)
if (!is.null(fit$sensitivities$Gamma_is)) {
  Gamma_is <- fit$sensitivities$Gamma_is
  # user mapping code goes here...
}
} # }