Skip to contents

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

Source: R/fct_parallel_lme.R
parallel_lme.Rd

Uses the DISCOURSE algorithmic framework to simulate multiple data sets 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

parallel_lme(
  parallel_start,
  return_best_solution,
  sim_data,
  target_cor,
  target_reg,
  reg_equation,
  target_se = NULL,
  weight = NA,
  max_iter = 10000,
  init_temp = 1,
  cooling_rate = NULL,
  tolerance = 1e-06,
  max_starts = 1,
  hill_climbs = NULL,
  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,
  progress_mode = "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. 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`.

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

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. 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
parallel_lme(
  parallel_start = 7,
  return_best_solution = FALSE,
  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
)
} # }