Generate Synthetic Simulation Covariates and Continuous Response — generate_covariate_dataset • EDI: Experimental Design and Inference

A helper function to generate synthetic covariates and a latent continuous response identical to the logic used within SimulationFramework. Covariates may be supplied directly via X_mat or drawn randomly via cov_draw_method; exactly one of the two must be non-NULL.

Usage

generate_covariate_dataset(
  n,
  p,
  cond_exp_func_model = c("linear", "nonlinear"),
  norm_sq_beta_vec = 1,
  X_mat = NULL,
  cov_draw_method = stats::rnorm,
  cov_draw_method_args = list(mean = 0, sd = 1)
)

Arguments

n: Integer. Sample size (number of rows).
p: Integer. Number of covariates (number of columns).
cond_exp_func_model: Character scalar. Either "linear" (latent response is a weighted linear combination of covariates) or "nonlinear" (Friedman 1991 function applied to the first five covariates; requires p >= 5).
norm_sq_beta_vec: Positive numeric scalar. The desired squared Euclidean norm of the coefficient vector, i.e. sum(beta^2). The coefficient vector (or the overall Friedman scale) is rescaled so that this quantity equals norm_sq_beta_vec. Default 1.
X_mat: Numeric matrix of dimensions n x p, or NULL (default). When supplied, this matrix is used directly as the covariate matrix and cov_draw_method must be NULL.
cov_draw_method: A function used to draw n * p i.i.d. covariate values, or NULL. The function must accept the number of draws as its first positional argument followed by any named arguments in cov_draw_method_args. Default stats::rnorm. Must be NULL when X_mat is supplied.
cov_draw_method_args: Named list of additional arguments forwarded to cov_draw_method beyond the sample-size first argument. Default is list(mean = 0, sd = 1).

Value

A list with two elements: X (a data frame of covariates) and y_cont (a numeric vector of the latent continuous response).

Details

Two conditional-expectation models are supported, both rescaled so that the latent response y_cont has a controlled signal magnitude:

"linear": $y_i = x_i^\top \beta$, with $\beta$ a fixed evenly spaced sequence from $1$ to $-1$ across the $p$ covariates (seq(1, -1, length.out = p)) — i.e. the first covariate gets the strongest positive effect, the last the strongest negative effect, and (for even $p$) covariates near the middle get effects near zero — rescaled so that $\|\beta\|_2^2 = \code{norm\_sq\_beta\_vec}$.
"nonlinear": The Friedman (1991) MARS benchmark function applied to the first five covariates (requires $p \ge 5$; covariates beyond the fifth do not enter the response at all), $$y_i = c \left(10 \sin(\pi x_{i1} x_{i2}) + 20 (x_{i3} - 0.5)^2 + 10 x_{i4} + 5 x_{i5}\right),$$ with the overall scale $c$ chosen so that $c^2 \sum_k \beta_{\mathrm{friedman},k}^2 = \code{norm\_sq\_beta\_vec}$ for the nominal term coefficients $\beta_{\mathrm{friedman}} = (10, 20, 10, 5)$ (the $\sin$ term's coefficient is not part of this nominal vector, so the realized $\|c \cdot (10,20,10,5)\|_2^2$ may not exactly equal norm_sq_beta_vec once the $\sin$ term's own variance is accounted for — norm_sq_beta_vec calibrates the linear-in-covariate part of the scale, not the full response variance). This function assumes each covariate lies roughly in $[-1, 1]$, matching Friedman's original specification; covariates drawn or supplied on a very different scale will not reproduce the intended signal shape.

References

Friedman, J. H. (1991). "Multivariate Adaptive Regression Splines." The Annals of Statistics, 19(1), 1-67, doi:10.1214/aos/1176347963 , for the nonlinear benchmark function used when cond_exp_func_model = "nonlinear".

Examples

generate_covariate_dataset(n = 10, p = 5)
#> $X
#>              x1         x2          x3         x4         x5
#>           <num>      <num>       <num>      <num>      <num>
#>  1:  0.86137545 -1.3293933  0.19622418 -2.0384120 -0.8915961
#>  2: -0.56699901 -2.0015230 -0.76358859 -0.6630919 -0.4162236
#>  3:  0.82446215  1.6365834 -0.34980822 -1.2024139  0.7774133
#>  4:  0.06685871  0.3233087 -0.46500917 -0.8398402  0.5922588
#>  5:  0.84203714  0.2527599 -0.80468968 -0.2756607 -1.0096366
#>  6:  2.61951343  2.5243751 -0.24474606 -2.7422213 -0.9991874
#>  7:  1.17444024 -0.5616758 -0.07264187  0.0783221 -0.5535619
#>  8: -1.31118526 -0.8551114 -0.93033833 -0.6457872 -1.6485462
#>  9: -2.34790322  1.6990683 -0.26443476 -1.3793748 -0.7019544
#> 10: -1.71644404 -0.7178294  1.27308401 -1.3623736  0.8221127
#> 
#> $y_cont
#>  [1]  1.33288797 -0.51860780  0.92752607  0.03552776  1.33820254  3.95411136
#>  [7]  0.89049941  0.14717167 -0.06750024 -1.40170151
#>