control_opt: Generate control specifications for 'ngme()' function.
In ngme2: Linear Latent Non-Gaussian Models with Flexible Distributions

control_opt

R Documentation

Generate control specifications for `ngme()` function.

Description

These are configurations for ngme optimization process.

Usage

control_opt(
  seed = Sys.time(),
  burnin = 100,
  iterations = 500,
  estimation = TRUE,
  standardize_fixed = TRUE,
  n_batch = 10,
  iters_per_check = iterations/n_batch,
  optimizer = adam(),
  start = NULL,
  start_sd = 0.5,
  n_parallel_chain = 4,
  max_num_threads = n_parallel_chain,
  print_check_info = FALSE,
  max_relative_step = 0.5,
  max_absolute_step = 0.5,
  rao_blackwellization = FALSE,
  n_trace_iter = 10,
  sampling_strategy = "all",
  solver_backend = "cholmod",
  solver_type = "llt",
  verbose = FALSE,
  store_traj = TRUE,
  robust = FALSE,
  stepsize_control = NULL,
  n_min_batch = min(n_batch, 3),
  n_slope_check = min(n_batch, 3),
  trend_std_conv_check = TRUE,
  std_lim = 0.01,
  trend_lim = 0.01,
  R_hat_conv_check = TRUE,
  max_R_hat = 1.1,
  pflug_conv_check = TRUE,
  pflug_alpha = 0.9
)

Arguments

`seed`	set the seed for pesudo random number generator
`burnin`	interations for burn-in periods (before optimization)
`iterations`	optimization iterations
`estimation`	run the estimation process (call C++ in backend)
`standardize_fixed`	whether or not standardize the fixed effect. When `TRUE` (default), the design matrix is SVD-standardized internally and any user-supplied `control_ngme(beta_init = ...)` is automatically mapped from the original design scale to that standardized basis. Set to `FALSE` to keep both the design matrix and any provided `beta_init` on their original scale.
`n_batch`	number of checkpoints; optimization is split into `n_batch` equal batches
`iters_per_check`	run how many iterations between each check point (or specify `n_batch`)
`optimizer`	choose different sgd optimization method, currently support "sgd", "sgld", "precond_sgd", "momentum", "adagrad", "rmsprop", "adam", "adamW" see ?sgd, ?precond_sgd, ?momentum, ?adagrad, ?rmsprop, ?adam, ?adamW
`start`	deprecated guard argument. Do not pass model starts through `control_opt()`; use `ngme(..., start = previous_fit)` instead.
`start_sd`	standard deviation of the initial parameter (1st chain fixed, other chains random), set 0 to be fixed for all chains
`n_parallel_chain`	number of parallel chains
`max_num_threads`	maximum number of threads used for parallel computing, by default will be set same as n_parallel_chain. If it is more than n_parallel_chain, the rest will be used to parallel different replicates of the model.
`print_check_info`	print the convergence information
`max_relative_step`	max relative step allowed in 1 iteration
`max_absolute_step`	max absolute step allowed in 1 iteration
`rao_blackwellization`	use rao_blackwellization
`n_trace_iter`	use how many iterations to approximate the trace (Hutchinson’s trick)
`sampling_strategy`	subsampling method of replicates of model, c("all", "ws") "all" means using all replicates in each iteration, "ws" means weighted sampling (each iteration use 1 replicate to compute the gradient, the sample probability is proption to its number of observations)
`solver_backend`	backend in ("eigen", "cholmod", "pardiso")
`solver_type`	factorization type: "llt" or "ldlt"
`verbose`	print estimation
`store_traj`	store the optimizer trajectory for diagnostics (set FALSE to reduce memory)
`robust`	use robust mode in the backend optimizer/model updates
`stepsize_control`	unified stepsize configuration created by `stepsize_control()`, `poly_decay()`, or `batch_decay()`. For polynomial schedule, `poly_decay(..., burnin_iter = B)` keeps schedule scale at 1 for the first `B` iterations, then starts decay with reset local time index.
`n_min_batch`	minimum number of checkpoints before any convergence diagnostic is attempted
`n_slope_check`	number of checkpoints used as the regression window for the trend test
`trend_std_conv_check`	enable the trend/std diagnostic (uses `std_lim`, `trend_lim`, `n_slope_check`)
`std_lim`	maximum allowed standard deviation
`trend_lim`	maximum allowed slope
`R_hat_conv_check`	use the R-hat diagnostic for convergence checking
`max_R_hat`	maximum allowed R_hat
`pflug_conv_check`	use Pflug diagnostic for convergence check
`pflug_alpha`	scaling factor (0-1] for Pflug criterion: require `pflug_sum < pflug_alpha * max_pflug_sum`

Details

Convergence diagnostics (multi-chain): * R-hat: per-parameter Gelman–Rubin statistic; passes if R_hat <= max_R_hat. * Trend/Std: uses the last n_slope_check checkpoints after at least n_min_batch batches. Passes when both the relative std (sqrt(var)/|mean| <= std_lim) and linear trend of the means (|slope| <= trend_lim) satisfy their thresholds. * Pflug: per-chain criterion pflug_sum < pflug_alpha * max_pflug_sum in the latest batch; if all chains satisfy it, overall convergence is declared. Checks are evaluated every iters_per_check = iterations / n_batch. A parameter is marked converged if any enabled parameter-level diagnostic (R-hat or Trend/Std) passes; the run stops when all parameters converge or when the Pflug diagnostic triggers.