Optimize simulated longitudinal mixed-effects data to match target correlations and regression estimates

Uses the DISCOURSE algorithmic framework to simulate data such that the resulting correlations and regression coefficients including random-intercept SD match specified targets under a given mixed-effects regression model and input parameters.

Usage

optim_lme(
  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,
  progress_bar = TRUE,
  max_starts = 1,
  hill_climbs = 100,
  move_prob = list(start = c(residual = 0, k_cycle = 0, local = 0.25, tau = 0.75), end =
    c(residual = 0.2, k_cycle = 0.1, local = 0.7, tau = 0)),
  min_decimals = 1,
  eps = 1e-05,
  progress_mode = "console"
)

Arguments

sim_data

Data.frame. Wide-format predictors and outcome columns for longitudinal data.

target_cor

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

target_reg

Numeric vector. Target fixed-effect coefficients (including intercept and random-intercept SD).

reg_equation

Character or formula. Mixed-effects model formula (e.g., "Y ~ X1 + X2 + (1|ID)").

target_se

Numeric vector, optional. Target standard errors for fixed-effect estimates; length matches `target_reg` minus 1 (random-intercept SD).

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`.

progress_bar

Logical. Show text progress bar during optimization. Default `TRUE`.

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`.

move_prob

List. Start/end move probabilities for operations: residual swap, k-cycle, local swap, tau reordering.

min_decimals

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

eps

Numeric. Small constant to stabilize scaling (prevent division by zero). Default `1e-5`.

progress_mode

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

@return A `discourse.object` list containing:

best_error: Numeric. Minimum objective error achieved.
data: Data.frame. Optimized wide-format longitudinal data.
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.
track_move_best: Character vector. Move types that produced best improvements.
track_move_acc: Character vector. Move types accepted per iteration.

Examples

 if (FALSE) { # \dontrun{
# Optimize data
optim_lme(
  sim_data       = sim_data,
  target_cor     = c(0.4),
  target_reg     = c(1, 0.5, 4),
  reg_equation   = "Y ~ X1 + (1|ID)",
  max_iter       = 2000,
  hill_climbs    = 50
)
} # }