Generate Synthetic Simulation Covariates and Continuous Response

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: -1.6576905  0.6900494 -0.2578632  0.481970480 -0.9864917
#>  2: -0.5753156 -1.1307935 -0.4581839  1.197358916 -0.8757496
#>  3:  0.8540098 -1.4678003  0.2708438 -1.610768765  1.7200192
#>  4: -0.2764356 -1.4624243 -2.8662993  0.001041489 -0.6992095
#>  5: -0.3958664 -0.9445823  0.4079083 -0.205604632 -0.7165168
#>  6: -1.1230043  1.6964699  0.5132579 -1.324601388  0.7054210
#>  7:  0.5849049 -0.2591284  0.2311685 -0.077121368  0.7625495
#>  8:  0.3098709  0.1325740 -2.3355036 -0.862197642 -0.8582451
#>  9:  0.1269871  0.2230616 -0.1915970 -0.503605666  0.4553143
#> 10: -0.5217339  1.4119040  2.6517932 -1.656166553 -1.9895635
#> 
#> $y_cont
#>  [1] -0.35870308 -0.54621523 -0.50250185 -0.19540282 -0.03088811 -0.20105104
#>  [7] -0.16990804  1.05335586  0.02213997  1.89854604
#>