sim_er_new_exp_marg: Calculate marginal expected response for specified exposure...

In BayesERtools: Bayesian Exposure-Response Analysis Tools

Calculate marginal expected response for specified exposure values

Description

Responses at specified exposure values are calculated for n_subj_sim subjects with different covariates (sampled from newdata), and the predicted responses are "marginalized" (averaged), resulting in marginal expected response on the population of interest.

Usage

sim_er_new_exp_marg(
  ermod,
  exposure_to_sim_vec = NULL,
  data_cov = extract_data(ermod),
  n_subj_sim = 100,
  n_draws_sim = 500,
  seed_sample_draws = NULL,
  output_type = c("draws", "median_qi"),
  qi_width = 0.95
)

sim_er_curve_marg(
  ermod,
  exposure_range = NULL,
  num_exposures = 51,
  data_cov = extract_data(ermod),
  n_subj_sim = 100,
  n_draws_sim = 500,
  seed_sample_draws = NULL,
  output_type = c("draws", "median_qi"),
  qi_width = 0.95
)

Arguments

ermod	An object of class ermod
exposure_to_sim_vec	Vector of exposure values to simulate.
data_cov	Data frame containing covariates to use for simulation. Different from sim_er_new_exp(), data_cov can be large as long as n_subj_sim is set to a reasonable number. Default is set to extract_data(ermod) which is the full data used to fit the model.
n_subj_sim	Maximum number of subjects to simulate. Default of 100 should be sufficient in many cases, as it's only used for marginal response calculation. Set to NULL to use all subjects in data_cov without resampling; in this case, be mindful of the computation time.
n_draws_sim	Number of draws for simulation. Default is set to 500 to reduce computation time for marginal response calculation.
seed_sample_draws	Seed for sampling draws. Default is NULL.
output_type	Type of output. "draws" returns the raw draws from the simulation, and "median_qi" returns the median and quantile interval.
qi_width	Width of the quantile interval. Default is 0.95. Only used when output_type = "median_qi".
exposure_range	Range of exposure values to simulate. If NULL (default), it is set to the range of the exposure variable in the original data for model development.
num_exposures	Number of exposure values to simulate.

Details

sim_er_new_exp_marg() returns a tibble with the marginal expected response for each exposure value in exposure_to_sim_vec.

sim_er_curve_marg() is a wrapper function for sim_er_new_exp_marg() that use a range of exposure values to simulate the marginal expected responses. Particularly useful for plotting the exposure-response curve.

Value

ersim_marg object, which is a tibble with the simulated marginal expected response with some additional information in object attributes. In case of output_type = "median_qi", it returns ersim_marg_med_qi object.

See Also

calc_ersim_med_qi() for calculating median and quantile interval from ersim_marg object (generated with output_type = "draws").

Examples

data(d_sim_binom_cov_hgly2)

ermod_bin <- dev_ermod_bin(
  data = d_sim_binom_cov_hgly2,
  var_resp = "AEFLAG",
  var_exposure = "AUCss_1000",
  var_cov = "BHBA1C_5",
)

ersim_new_exp_marg_med_qi <- sim_er_new_exp_marg(
  ermod_bin,
  exposure_to_sim_vec = seq(2, 6, by = 0.2),
  data_cov = dplyr::tibble(BHBA1C_5 = 4:10),
  n_subj_sim = NULL,
  n_draws_sim = 500, # This is set to make the example run faster
  output_type = "median_qi"
)

ersim_new_exp_marg_med_qi

BayesERtools documentation built on June 8, 2025, 1:26 p.m.