tulpa_simulate: Simulate data from a tulpa model

In tulpa: Templated Unified Library for Posterior Approximation in Bayesian Hierarchical Models

Simulate data from a tulpa model

Description

Generic simulator that dispatches through a tulpa_family's simulate_fn. Given a model spec (formula + family + data) and a parameter vector or a fitted model, generate one or more synthetic response datasets.

Used internally by prior_predict() and exposed for posterior predictive checks, simulation-based calibration, and what-if analyses with fixed parameters.

Usage

tulpa_simulate(
  formula,
  family,
  data,
  theta = NULL,
  n_sims = 1L,
  priors = NULL,
  seed = NULL,
  ...
)

## S3 method for class 'tulpa_simulate'
print(x, ...)

Arguments

formula	A model formula, or list of formulas keyed by process name.
family	A tulpa_family object (see tulpa_family()).
data	Data frame with covariates and grouping factors. The response column may be absent or NA; it is not read.
theta	One of: A named list with beta (numeric or list per process), u (list of RE blocks, one per RE term per process, each an ⁠n_groups x n_coefs⁠ matrix; a vector of length n_groups is accepted for a single-coefficient term), extras (named list of family-specific extras like phi, sigma_y). A tulpa_fit object: each simulation takes one posterior draw of the fixed effects and, paired with it, of the FITTED random effects (read through the same accessor as ranef() and posterior_predict()). The data are therefore simulated conditional on the fitted groups: every level of a grouping variable in data must be one the fit estimated (matched by level), and a fit that carries no random-effect posterior is an error rather than a set of zero effects. To simulate NEW groups, pass theta as a list with u drawn for them. NULL: equivalent to a single prior draw (shortcut).
n_sims	Number of simulated datasets. When theta is a fit, draws are subsampled (or recycled) to n_sims. Default 1.
priors	Used only if theta = NULL; default tulpa_priors().
seed	Optional integer seed.
...	Passed to family$simulate_fn.
x	A tulpa_simulate object.

Value

A tulpa_simulate object: list with y (length-n_sims list of simulated responses), theta (parameters used per sim), linpred, family, n_sims, n_obs.

Examples

fam <- tulpa_family(
  name = "gaussian",
  simulate_fn = function(eta, params, n_obs, ...) {
    rnorm(n_obs, eta[[1]], params$sigma_y)
  },
  extra_params = list(sigma_y = prior_half_normal(1))
)
df <- data.frame(y = rep(0, 20), x = rnorm(20))
theta <- list(
  beta = list(y = c(0.5, 1.0)),
  u = list(y = list()),
  extras = list(sigma_y = 0.5)
)
sim <- tulpa_simulate(y ~ x, fam, df, theta = theta, n_sims = 3, seed = 1)
length(sim$y)  # 3

tulpa documentation built on Oct. 19, 2026, 5:09 p.m.