Run a complete spesim simulation (recommended)

spesim_run() is the main public entry point for the package.

It supports both:

File-driven workflows: pass a path to an init file (KEY = value)
Programmatic workflows: pass an in-memory parameter list P

Internally, spesim_run() orchestrates a full run by:

resolving configuration (and optional seed override),
creating (or accepting) a sampling domain,
resolving interspecific interactions (file pointer / inline rules),
calling the pure simulation engine, and
optionally writing an output bundle (CSVs, figures, report).

Compared to run_spatial_simulation(), this function returns a stable S3 object (spesim_result) and keeps filesystem I/O optional.

Usage

spesim_run(
  config,
  domain = NULL,
  interactions_file = NULL,
  output_prefix = NULL,
  write_outputs = FALSE,
  seed = NULL,
  quiet = FALSE,
  interactions_validate = TRUE,
  interactions_strict = TRUE,
  interactions_print = TRUE,
  interactions_top_n = 20,
  report_include_audit = TRUE,
  report_audit_top_n = 6,
  ...
)

Arguments

config: Either a path to an init file (character scalar), or an in-memory parameter list P (typically from load_config()).
domain: Optional sf polygon study area (see create_sampling_domain()). If NULL, a default domain is created.
interactions_file: Optional path to an interactions config file. If NULL, the function will look for INTERACTIONS_FILE or INTERACTIONS_EDGELIST in config/P.
output_prefix: Base output prefix (timestamp is appended) when write_outputs = TRUE.
write_outputs: Logical; write CSVs/figures/report to disk? Default FALSE for a smoother interactive experience.
seed: Optional integer. If supplied, it (i) overrides P$SEED for the simulation, and (ii) is also used to generate a reproducible default domain when domain = NULL.
quiet: Logical; suppress most messages.
interactions_validate: Logical; validate resolved interactions.
interactions_strict: Logical; if validation finds problems, stop (TRUE) or warn (FALSE).
interactions_print: Logical; pretty-print a compact interactions summary.
interactions_top_n: Integer; cap the number of non-1.0 entries shown.
report_include_audit: Logical; include the conceptual audit section in the written report (when write_outputs = TRUE).
report_audit_top_n: Integer; rows to show in the audit section.
...: Reserved for future extensions. Currently unused.

Value

An object of class spesim_result (a named list) with components:

P: resolved parameters
domain: study area (sf)
species_dist: simulated individuals (sf points)
quadrats: sampling quadrats (sf polygons; class spesim_quadrats)
env_gradients: environmental grid
abund_matrix: site × species abundances
site_env: per-quadrat mean environment
site_coords: quadrat centroids
files (optional): written file paths (when write_outputs = TRUE)

Run a complete spesim simulation (recommended)

Usage

Arguments

Value

See also