[Experimental]

sdmTMB_simulate() (vs. sdmTMB_sim()) (1) uses TMB for simulation and is therefore much faster and more flexible, (2) is set up to take a formula and a data frame and is therefore easier to use if you want different spatial observations (and covariates) for each time slice. sdmTMB_sim() uses pure R for simulation. sdmTMB_simulate() uses TMB for simulation.

simulate.sdmTMB(), on the other hand, takes an existing fit and simulates new observations and optionally new random effects.

sdmTMB_simulate(
  formula,
  data,
  mesh,
  family = gaussian(link = "identity"),
  previous_fit = NULL,
  time = NULL,
  B = NULL,
  range = NULL,
  rho = NULL,
  sigma_O = NULL,
  sigma_E = NULL,
  sigma_Z = NULL,
  phi = NULL,
  tweedie_p = NULL,
  df = NULL,
  fixed_re = list(omega_s = NULL, epsilon_st = NULL, zeta_s = NULL),
  seed = sample.int(1e+06, 1),
  ...
)

Arguments

formula

A one-sided formula describing the fixed-effect structure.

data

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

mesh

Output from make_mesh().

family

Family as in sdmTMB().

previous_fit

(Depreciated; please use simulate.sdmTMB()). An optional previous sdmTMB() fit to pull parameter values. Will be over-ruled by any non-NULL specified parameter arguments.

time

The time column name.

B

A vector of beta values (fixed-effect coefficient values).

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.

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).

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.

fixed_re

A list of optional random effects to fix at specified (e.g., previously estimated) values. Values of NULL will result in the random effects being simulated.

seed

Seed number.

...

Any other arguments to pass to sdmTMB().

Value

A data frame where:

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

  • The 2nd and 3rd columns are the spatial coordinates.

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

  • zeta_s represents the simulated spatial 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

if (inla_installed()) {
  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 <- sdmTMB_simulate(
    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)

  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

  # example supplying previous fit, simulating new random effects,
  # and changing spatial SD (sigma_O) and observation error (phi):
  sim_dat2 <- sdmTMB_simulate(
    previous_fit = fit,
    simulate_re = TRUE, phi = 0.04, sigma_O = 0.4
  )
  head(sim_dat2)
}
#>   year         X           Y     omega_s  epsilon_st         mu        eta
#> 1    1 0.2875775 0.784575267 -0.04561476 -0.05823907  0.4082140  0.4082140
#> 2    1 0.7883051 0.009429905  0.15507417  0.16679538  0.8485037  0.8485037
#> 3    1 0.4089769 0.779065883  0.08432874 -0.04384974  0.6394063  0.6394063
#> 4    1 0.8830174 0.729390652  0.16032985  0.08820729  0.8917992  0.8917992
#> 5    1 0.9404673 0.630131853  0.12563232  0.11785447  0.6473839  0.6473839
#> 6    1 0.0455565 0.480910830 -0.06243127 -0.14724326 -0.1046515 -0.1046515
#>     observed (Intercept)         a1
#> 1  0.4474881           1 -0.7152422
#> 2  0.8669773           1 -0.7526890
#> 3  0.6333489           1 -0.9385387
#> 4  0.8987353           1 -1.0525133
#> 5  0.6796163           1 -0.4371595
#> 6 -0.1051796           1  0.3311792