Simulate responses from an exposure-response model — simulate.erglm

Generates simulated response datasets from a fitted erglm model, propagating uncertainty in the parameter estimates. Useful for simulation-based confidence bands, predictive checks, or bootstrapping downstream analyses. Implements the standard stats::simulate() generic, so it is called as simulate(object, ...) rather than through an erglm-specific function name.

Usage

# S3 method for class 'erglm_model'
simulate(object, nsim = 1, seed = NULL, ...)

Arguments

object: An erglm model, as returned by erglm_model()
nsim: Number of replicates. Must be a single positive whole number.
seed: Used to set the RNG seed. If NULL, a random seed is chosen and reported.
...: Ignored

Value

A tibble with one row per observation per simulated replicate, containing:

dat_id, sim_id: identifiers for the original observation and the simulation replicate
mu: the expected response (response scale) at the sampled parameter vector
val: the simulated response value (mu plus family-appropriate noise)
one coef_* column per model coefficient (e.g. coef_`(Intercept)`, coef_aucss), giving the sampled parameter values used for that replicate – prefixed to avoid colliding with predictor columns of the same name
the model's predictor columns (not including the response)

Details

Samples new parameter values from the multivariate normal distribution implied by the model's variance-covariance matrix (via mvtnorm::rmvnorm()), evaluates the expected response at each sampled parameter vector using erglm_fun(), then draws a simulated response at each prediction using family-appropriate residual noise (the same .erglm_draw_response() mechanism used elsewhere in the package: Bernoulli draws for binomial, Poisson draws for poisson, normal draws for gaussian, gamma draws for Gamma). The dispersion parameter used for that noise is a single point estimate (summary(object)$dispersion), not resampled per replicate. Other glm() families are not currently supported and will raise an informative error.

For a VPC-style plot comparing observed and simulated response rates, see the companion erplots package's er_vpc_plot(), which can build its simulated replicates directly from a fitted model (model = argument) via the same .erglm_draw_response() noise mechanism this method uses, without needing to call simulate() yourself.

Examples

mod <- erglm_model(ae1 ~ aucss + sex, erglm_data, family = binomial())
simulate(mod, nsim = 5, seed = 963)
#> # A tibble: 1,500 × 9
#>    dat_id sim_id    mu   val `coef_(Intercept)` coef_aucss coef_sexMale aucss
#>     <int>  <int> <dbl> <int>              <dbl>      <dbl>        <dbl> <dbl>
#>  1      1      1 0.896     1              -1.77    0.00618       -0.238  673.
#>  2      2      1 1.000     1              -1.77    0.00618       -0.238 2806.
#>  3      3      1 0.146     0              -1.77    0.00618       -0.238    0 
#>  4      4      1 0.996     1              -1.77    0.00618       -0.238 1169.
#>  5      5      1 0.581     1              -1.77    0.00618       -0.238  377.
#>  6      6      1 0.563     1              -1.77    0.00618       -0.238  327.
#>  7      7      1 0.119     0              -1.77    0.00618       -0.238    0 
#>  8      8      1 0.997     1              -1.77    0.00618       -0.238 1208.
#>  9      9      1 0.119     0              -1.77    0.00618       -0.238    0 
#> 10     10      1 0.450     1              -1.77    0.00618       -0.238  254.
#> # ℹ 1,490 more rows
#> # ℹ 1 more variable: sex <fct>