Skip to contents

simulate_new() uses TMB to simulate new data given specified parameter values. simulate.sdmTMB(), on the other hand, takes an existing model fit and simulates new observations and optionally new random effects. Note: sdmTMB_simulate() is retained as a synonym for backward compatibility. We recommend using simulate_new() because it more clearly conveys the function's purpose. sdmTMB_simulate() may eventually be deprecated.

Usage

simulate_new(
  formula,
  data,
  mesh,
  family = gaussian(link = "identity"),
  time = NULL,
  B = NULL,
  range = NULL,
  rho = NULL,
  sigma_O = NULL,
  sigma_E = NULL,
  sigma_Z = NULL,
  phi = NULL,
  tweedie_p = NULL,
  df = NULL,
  sigma_smooth = NULL,
  threshold_coefs = NULL,
  fixed_re = list(omega_s = NULL, epsilon_st = NULL, zeta_s = NULL),
  seed = sample.int(1e+06, 1),
  time_varying = NULL,
  time_varying_type = c("rw", "rw0", "ar1"),
  sigma_V = NULL,
  rho_time = NULL,
  nonlocal_formula = NULL,
  lags_kappaS = NULL,
  lags_rhoT = NULL,
  rho_sar = NULL,
  alpha_car = NULL,
  ...
)

sdmTMB_simulate(
  formula,
  data,
  mesh,
  family = gaussian(link = "identity"),
  time = NULL,
  B = NULL,
  range = NULL,
  rho = NULL,
  sigma_O = NULL,
  sigma_E = NULL,
  sigma_Z = NULL,
  phi = NULL,
  tweedie_p = NULL,
  df = NULL,
  sigma_smooth = NULL,
  threshold_coefs = NULL,
  fixed_re = list(omega_s = NULL, epsilon_st = NULL, zeta_s = NULL),
  seed = sample.int(1e+06, 1),
  time_varying = NULL,
  time_varying_type = c("rw", "rw0", "ar1"),
  sigma_V = NULL,
  rho_time = NULL,
  nonlocal_formula = NULL,
  lags_kappaS = NULL,
  lags_rhoT = NULL,
  rho_sar = NULL,
  alpha_car = NULL,
  ...
)

Arguments

formula

A one-sided formula describing the fixed-effect structure. Random intercepts are not (yet) supported. Fixed effects should match the corresponding B argument vector of coefficient values.

data

A data frame containing the predictors described in formula and the time column if time is specified.

mesh

Output from make_mesh() or, for areal SAR/CAR models, make_areal_domain() (with spatial_model = "sar" or "car" passed via ...).

family

Family as in sdmTMB(). Delta families are not supported. Instead, simulate the two component models separately and combine.

time

The time column name.

B

A vector of beta values (fixed-effect coefficient values). If nonlocal_formula is used, include regular fixed-effect coefficients followed by transformed-covariate coefficients in operator order. Same-covariate diffusion() and time_lag() wrappers contribute one joint coefficient. If formula includes smoothers (s()), append the coefficients of their linear (unpenalized) parts, in the order tidy.sdmTMB() lists them (e.g., sx).

range

Parameter that controls the decay of spatial correlation. If a vector of length 2, share_range will be set to FALSE and the spatial and spatiotemporal ranges will be unique. Not used for areal models.

rho

Spatiotemporal correlation between years; should be between -1 and 1.

sigma_O

SD of spatial process (Omega).

sigma_E

SD of spatiotemporal process (Epsilon). A single value.

sigma_Z

SD of spatially varying coefficient field (Zeta).

phi

Observation error scale parameter (e.g., SD in Gaussian).

tweedie_p

Tweedie p (power) parameter; between 1 and 2.

df

Student-t degrees of freedom (must be > 1). Overrides any df supplied to student(). If neither is given, df = 3.

sigma_smooth

SD(s) of the penalized (wiggly) smoother coefficients if formula includes s(): a single value or one per smoother. If NULL (the default), these coefficients are 0 and each smoother reduces to its linear part set through B. Otherwise they are drawn as random effects with this SD on the scale of the mgcv basis, giving a random nonlinear shape.

threshold_coefs

An optional vector of threshold coefficient values if the formula includes breakpt() or logistic(). If breakpt(), these are slope and cut values (with breakpt(positive = TRUE), the slope itself, which must be positive). If logistic(), these are the threshold at which the function is 50% of the maximum, the threshold at which the function is 95% of the maximum, and the maximum. See the model description vignette for details.

fixed_re

A list of optional random effects to fix at specified (e.g., previously estimated) values. NULL values indicate that the corresponding random effects should be simulated.

seed

Seed number. Simulated values for a given seed differ from those of the removed C++ TMB backend, the default before sdmTMB 1.2.0.

time_varying

An optional one-sided formula describing time-varying covariates passed through to sdmTMB() for building a time-varying random effect design matrix.

time_varying_type

Type of temporal process applied to time_varying. Must be one of 'rw', 'rw0', or 'ar1'.

sigma_V

SD(s) of the time-varying process. Provide a single value or a vector matching the number of time-varying coefficients.

rho_time

Autoregressive correlation(s) for time-varying parameters when time_varying_type = "ar1". Values must lie between -1 and 1 and may be supplied as a single value or a vector the same length as sigma_V.

nonlocal_formula

An optional one-sided formula describing covariate-diffusion terms to pass to sdmTMB(). Supported wrappers are diffusion() and time_lag(). Same-covariate wrappers select one joint operator and coefficient.

lags_kappaS

Spatial diffusion scale for diffusion() terms. Must be positive and finite. Supply a single value or one value per covariate needing a spatial scale.

lags_rhoT

Temporal diffusion persistence for time_lag() terms. Must satisfy 0 < rhoT < 1. Supply a single value or one value per covariate needing temporal diffusion.

rho_sar

Spatial dependence parameter for spatial_model = "sar"; between -1 and 1.

alpha_car

Spatial dependence parameter for spatial_model = "car"; between 0 and 1.

...

Any other arguments to pass to sdmTMB().

Value

A data frame where:

  • The first column is the time variable (if present).

  • The second and third columns are the spatial coordinates (or, for areal models, a single column of areal unit IDs).

  • omega_s represents the simulated spatial random effects (only if present).

  • zeta_s represents the simulated spatially varying covariate field (only if present).

  • epsilon_st represents the simulated spatiotemporal random effects (only if present).

  • eta is the true value in link space.

  • mu is the true value in inverse link space.

  • observed represents the simulated process with observation error.

  • The remaining columns are the fixed-effect model matrix.

Examples

set.seed(123)

# make fake predictor(s) (a1) and sampling locations:
predictor_dat <- data.frame(
  X = runif(300), Y = runif(300),
  a1 = rnorm(300), year = rep(1:6, each = 50)
)
mesh <- make_mesh(predictor_dat, xy_cols = c("X", "Y"), cutoff = 0.1)

sim_dat <- simulate_new(
  formula = ~ 1 + a1,
  data = predictor_dat,
  time = "year",
  mesh = mesh,
  family = gaussian(),
  range = 0.5,
  sigma_E = 0.1,
  phi = 0.1,
  sigma_O = 0.2,
  seed = 42,
  B = c(0.2, -0.4) # B0 = intercept, B1 = a1 slope
)
head(sim_dat)
#>   year         X           Y     omega_s  epsilon_st         mu        eta
#> 1    1 0.2875775 0.784575267  0.13770158 -0.00436240  0.6194361  0.6194361
#> 2    1 0.7883051 0.009429905 -0.46425377  0.02830728  0.0651291  0.0651291
#> 3    1 0.4089769 0.779065883  0.14210120  0.13220620  0.8497229  0.8497229
#> 4    1 0.8830174 0.729390652 -0.32262187 -0.03612523  0.2622582  0.2622582
#> 5    1 0.9404673 0.630131853  0.04231036 -0.02905862  0.3881156  0.3881156
#> 6    1 0.0455565 0.480910830 -0.10825765 -0.10529657 -0.1460259 -0.1460259
#>     observed (Intercept)         a1
#> 1  0.6000790           1 -0.7152422
#> 2  0.0648955           1 -0.7526890
#> 3  0.8484399           1 -0.9385387
#> 4  0.2774529           1 -1.0525133
#> 5  0.4479667           1 -0.4371595
#> 6 -0.1586471           1  0.3311792

if (require("ggplot2", quietly = TRUE)) {
  ggplot(sim_dat, aes(X, Y, colour = observed)) +
    geom_point() +
    facet_wrap(~year) +
    scale_color_gradient2()
}


# fit to the simulated data:
fit <- sdmTMB(observed ~ a1, data = sim_dat, mesh = mesh, time = "year")
fit
#> Spatiotemporal model fit by ML ['sdmTMB']
#> Formula: observed ~ a1
#> Mesh: mesh (isotropic covariance)
#> Time column: year
#> Data: sim_dat
#> Family: gaussian(link = 'identity')
#>  
#> Conditional model:
#>             coef.est coef.se
#> (Intercept)     0.15    0.05
#> a1             -0.39    0.01
#> 
#> Dispersion parameter: 0.09
#> Matérn range: 0.28
#> Spatial SD: 0.16
#> Spatiotemporal IID SD: 0.12
#> ML criterion at convergence: -163.418
#> 
#> See ?tidy.sdmTMB to extract these values as a data frame.