Compute invasion fitness ($\lambda$) and optional establishment probability ($P$)

Wraps compute_invasion_fitness() to generate invader-by-site invasion fitness $\lambda_{is}$ under model Options A–E, and (optionally) maps $\lambda$ to probabilities via compute_establishment_probability(). Supports calibration of $\kappa$ so that resident mean $\lambda$ is approximately zero, and can overlay an sf boundary on map-like plots.

Usage

predict_establishment(
  fit,
  option = c("A", "B", "C", "D", "E"),
  calibrate_kappa = FALSE,
  prob_method = c(NULL, "probit", "logit", "hard"),
  prob_args = list(),
  method = NULL,
  prob_scale = NULL,
  boundary_sf = NULL,
  boundary_params = list(inherit.aes = FALSE, fill = NA, color = "black", size = 0.3)
)

Arguments

fit

An invasimapr_fit from predict_invaders(), containing invaders$r_is_z/C_is_z/S_is_z, resident summaries, and learned sensitivities.

option

Character, one of c("A","B","C","D","E") selecting the invasion-fitness specification:

A: Baseline: $=r^(z)- C^(z)- S^(z)$.
B: Global abiotic scaling $_0 r^(z)$.
C: Trait-varying abiotic scaling $_i r^(z)$.
D: Site-varying abiotic and crowding $_is, _is$.
E: Signed saturation effect (facilitation allowed via signed $_i$).

calibrate_kappa

Logical; if TRUE, set  so mean resident $ 0$ (scale alignment for communication/comparison).

prob_method

(legacy) NULL or one of c("probit","logit","hard"); preserved for backward compatibility.

prob_args

(legacy) List of arguments passed to compute_establishment_probability() (e.g., sigma, tau, predictive, sigma_mat, site_df, return_long, make_plots).

method

Alias of prob_method (preferred in user code).

prob_scale

Alias of prob_args (preferred in user code).

boundary_sf

Optional sf object to overlay on map-like probability plots.

boundary_params

Named list for ggplot2::geom_sf() aesthetics; default list(inherit.aes=FALSE, fill=NA, color="black", size=0.3).

Value

The input fit with:

$fitness: List returned by compute_invasion_fitness() (including lambda_is, lambda_long, option, and any plots/maps).
$prob: If requested, list returned by compute_establishment_probability() with probability tables and plots (with boundary overlay applied when provided).

Details

What this wrapper does

Chooses the appropriate sensitivity inputs for the requested option (e.g., theta_i for C, Gamma_is/alpha_is for D).
Calls compute_invasion_fitness() with site-standardised inputs $(r^(z), C^(z), S^(z))$ held in fit.
(Optional) Converts  to probability $\,P\,$ via probit, logit, or a hard threshold, forwarding prob_* settings.
(Optional) If boundary_sf is supplied and plots are available, overlays the boundary on map-like plots using geom_sf().

Calibration (calibrate_kappa = TRUE) Aligns invader–resident scales by shifting  so that the resident mean is ~0, using resident moments and trait-plane slopes stored in fit.

Examples

if (FALSE) { # \dontrun{
fit <- fit |>
  predict_invaders(traits_inv) |>
  predict_establishment(option = "C", calibrate_kappa = TRUE,
                        method = "probit", prob_scale = list(sigma = 1))

# Overlay a boundary on probability maps
fit <- predict_establishment(fit, option = "D", method = "logit",
                             prob_scale = list(tau = 1),
                             boundary_sf = rsa_boundary)
} # }

Compute invasion fitness (\(\lambda\)) and optional establishment probability (\(P\))

Usage

Arguments

Value

Details

See also

Examples