Simulate a COS Example Dataset — cos_simulate

Simulates observed-support responses from the supported tapered COS model for small examples, validation checks, and reproducible package data.

Usage

cos_simulate_data(X_rast, forest_sf, n_B = 36L, plot_radius, gamma,
  beta, tau_B_sq, sigma_sq, phi, taper_code = 1L,
  design_seed = NULL, sim_seed = NULL, n_threads = 1L,
  verbose = FALSE)

Arguments

X_rast: A raster RasterLayer, RasterStack, or RasterBrick containing fine-support covariates. Supply an intercept layer explicitly if the simulation model should include one.
forest_sf: An sf polygon object defining the simulation boundary. It must use the same projected CRS as X_rast.
n_B: Target number of observed-support plot centers. Centers are generated by sf::st_sample() with type = "regular".
plot_radius: Radius for circular observed-support plots, in CRS units. Plots are clipped to forest_sf.
gamma: Positive taper distance in CRS units.
beta: Named vector of regression coefficients. Names must match raster layer names after any intercept layer is added.
tau_B_sq: Average observed-support nugget variance. The simulator converts this to tau_sq = tau_B_sq / mean(diag(D_h)).
sigma_sq: Spatial process variance.
phi: Exponential covariance decay parameter. The effective range is 3 / phi.
taper_code: Integer taper code: 1L for Wendland or 2L for spherical.
design_seed: Optional seed used for generating systematic plot centers.
sim_seed: Optional seed used for drawing the spatial process and nugget errors.
n_threads: Number of OpenMP threads used by compiled covariance code.
verbose: Logical; if TRUE, print progress from cos_prepare.

Details

The simulator keeps the design model-based: observed supports are fixed after generation, and no design-based inclusion-probability adjustment is applied. Circular plot polygons are clipped to forest_sf; the resulting polygons are passed to cos_prepare, which constructs the support weights H_BA, nugget matrix D_h, and tapered observed-support covariance.

The response is generated as $$y_B = X_B \beta + \omega_B + e_B,$$ $$\omega_B \sim N(0, \sigma^2 C_B), \qquad e_B \sim N(0, \tau^2 D_h),$$ where X_B = H_BA X and tau_sq = tau_B_sq / mean(diag(D_h)).

The bundled files documented in cosTapered-example-data were generated with this simulator using the same model settings shown in the example below.

Value

A list with class "cos_simulation" containing:

X_rast: covariate raster stack used for simulation, including any intercept layer supplied by the user.
forest_sf: cleaned forest boundary.
B_sf: observed-support polygons with simulated y_B, eta_B_true, omega_B_true, and eps_B_true.
truth: known simulation settings and parameter values.
prep: the "cos_prep" object used for simulation.

Examples

if (FALSE) { # \dontrun{
library(sf)
library(raster)
library(ggplot2)

chm <- raster(system.file("extdata", "example_chm.tif", package = "cosTapered"))
names(chm) <- "chm"
forest <- st_read(system.file("extdata", "example_forest.gpkg",
                              package = "cosTapered"))

intercept <- chm
intercept[] <- ifelse(is.na(getValues(chm)), NA_real_, 1)
names(intercept) <- "intercept"
X_rast <- stack(intercept, chm)
names(X_rast) <- c("intercept", "chm")

sim <- cos_simulate_data(
  X_rast = X_rast,
  forest_sf = forest,
  n_B = 36,
  plot_radius = 15,
  gamma = 350,
  beta = c(intercept = 45, chm = 1.25),
  tau_B_sq = 8,
  sigma_sq = 35,
  phi = 3 / 250,
  design_seed = 1,
  sim_seed = 1
)

chm_df <- as.data.frame(chm, xy = TRUE, na.rm = TRUE)
names(chm_df) <- c("x", "y", "chm")

ggplot() +
  geom_raster(data = chm_df, aes(x = x, y = y, fill = chm)) +
  geom_sf(data = sim$forest_sf, fill = NA, color = "black") +
  geom_sf(data = sim$B_sf, fill = NA, color = "red") +
  coord_sf(expand = FALSE) +
  scale_fill_viridis_c() +
  theme_bw()

ggplot() +
  geom_sf(data = sim$forest_sf, fill = "grey95", color = "grey60") +
  geom_sf(data = sim$B_sf, aes(fill = y_B), color = "black") +
  coord_sf(expand = FALSE) +
  scale_fill_viridis_c(option = "magma") +
  theme_bw()
} # }