Optimize multiple simulated data sets to match target correlations and fixed-effects regression fits

Uses the DISCOURSE algorithmic framework to simulate multiple data sets such that the resulting correlations and regression coefficients match specified targets under a given regression model and input parameters.

Usage

parallel_lm(
  parallel_start,
  return_best_solution,
  sim_data,
  target_cor,
  target_reg,
  reg_equation,
  target_se = NULL,
  weight = c(1, 1),
  max_iter = 1e+05,
  init_temp = 1,
  cooling_rate = NULL,
  tolerance = 1e-06,
  prob_global_move = 0.1,
  max_starts = 1,
  hill_climbs = NULL,
  min_decimals = 1,
  progress_mode = c("console")
)

Arguments

parallel_start

Number of independent runs (parallel or sequential) to simulate data sets.

return_best_solution

Logical; return only the best run if TRUE.

sim_data

Data frame. Predictor variables and outcome to be optimized; at least two columns.

target_cor

Numeric vector. Target upper-triangular (excluding diagonal) correlation values for predictor and outcome variables.

target_reg

Numeric vector. Target regression coefficients including intercept, matching terms in `reg_equation`.

reg_equation

Character or formula. Regression model (e.g., "Y ~ X1 + X2 + X1:X2").

target_se

Numeric vector, optional. Target standard errors for regression coefficients (same length as `target_reg`).

weight

Numeric vector of length 2. Weights for correlation vs. regression error in the objective function. Default `c(1, 1)`.

max_iter

Integer. Maximum iterations for simulated annealing per start. Default `1e5`.

init_temp

Numeric. Initial temperature for annealing. Default `1`.

cooling_rate

Numeric or NULL. Cooling rate per iteration (0–1); if NULL, computed as `(max_iter - 10) / max_iter`.

tolerance

Numeric. Error tolerance for convergence; stops early if best error < `tolerance`. Default `1e-6`.

prob_global_move

Numeric (0–1). Probability of a global shuffle move vs. local swap. Default `0.1`.

max_starts

Integer. Number of annealing restarts. Default `1`.

hill_climbs

Integer or NULL. Number of hill‐climbing iterations for optional local refinement; if NULL, skips refinement. Default `NULL`.

min_decimals

Integer. Minimum number of decimal places for target values (including trailing zeros). Default `1`.

progress_mode

Character. Either "console" or "shiny" for progress handler. Default `console`.

Value

A list of multiple `discourse.object`s, each containing:

best_error

Numeric. Minimum objective error achieved.

data

Data frame of optimized predictor and outcome values.

inputs

List of all input parameters for reproducibility.

track_error

Numeric vector of best error at each iteration of annealing.

track_error_ratio

Numeric vector of error ratios (cor vs. reg) per iteration.

Examples

 if (FALSE) { # \dontrun{
# Optimize given sim_data from the Descriptives module matching means and SDs.
res <- parallel_lm(
  parallel_start = 7,
  return_best_solution = FALSE,
  sim_data = sim_data,
  target_cor = c(.23),
  target_reg = c(2.1, 1.2, -0.8),
  reg_equation = "Y ~ X1 + X2",
  max_iter = 10000,
  hill_climbs = 50
)
} # }