Skip to contents

Summarise invasiveness / invasibility (tables, maps, rankings)

Source: R/summarise_results.R
summarise_results.Rd

Thin wrapper around summarise_invasiveness_invasibility() that pulls inputs from an invasimapr_fit container, forwards optional arguments, and (optionally) overlays a boundary layer on the site map. Designed as a drop-in reporting step after computing invasion fitness and/or establishment probabilities.

Usage

summarise_results(
  fit,
  boundary_sf = NULL,
  boundary_params = list(inherit.aes = FALSE, fill = NA, color = "black", size = 0.3),
  traits_inv = NULL,
  ...
)

Arguments

fit

An object of class invasimapr_fit containing fitness and/or prob components produced by upstream steps (see See also).

boundary_sf

Optional sf object to overlay on the site map (e.g., national/park boundary).

boundary_params

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

traits_inv

Optional override of the invader trait table used in summaries. If NULL, falls back to fit$invaders$traits_inv_raw, then fit$invaders$traits_inv_glmm when available.

...

Additional arguments forwarded to summarise_invasiveness_invasibility().

Value

The input fit with an added/updated fit$summary list containing summary tables and plots. Invisibly returns fit to support piping.

Details

Behaviour

  1. Extracts lambda_is and/or p_is from fit; errors if neither is found.

  2. Chooses site_df from fit$inputs$site_df when present.

  3. Selects an effective trait table for invader-ranked summaries in the order: user-supplied traits_inv → fit$invaders$traits_inv_raw → fit$invaders$traits_inv_glmm.

  4. Calls summarise_invasiveness_invasibility() to construct tidy summaries and ggplots (site maps, rankings, heatmaps).

  5. If boundary_sf is supplied and plots are available, overlays the boundary with geom_sf() using boundary_params.

Output layout The returned fit gains a summary element mirroring the structure from summarise_invasiveness_invasibility() (e.g., tables, plots, args_used).

What it uses from fit

  • fit$fitness$lambda_is (optional): site × invader invasion fitness matrix.

  • fit$prob$p_is (optional): site × invader establishment probability matrix.

  • fit$inputs$site_df (optional): site metadata with site, x, y.

  • fit$inputs$comm_res (optional): resident community matrix for context stats.

  • fit$invaders$traits_inv_raw or fit$invaders$traits_inv_glmm (optional): invader traits used for invader-ranked summaries.

At least one of lambda_is or p_is must be available; otherwise an error is thrown.

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)
fit <- predict_invaders(fit, traits_inv = invader_traits)

# Optionally compute lambda and/or probability
fit$fitness <- compute_invasion_fitness_from_fit(fit)   # hypothetical helper
fit$prob    <- compute_establishment_probability_from_fit(fit)  # idem

# Overlay a boundary (sf) on the site map
fit <- summarise_results(fit, boundary_sf = rsa_boundary)
fit$summary$plots$site_map
} # }