vglmer_control: Control for vglmer estimation

In vglmer: Variational Inference for Hierarchical Generalized Linear Models

Control for vglmer estimation

Description

This function controls various estimation options for vglmer.

Usage

vglmer_control(
  iterations = 1000,
  prior_variance = "hw",
  factorization_method = c("strong", "partial", "weak"),
  parameter_expansion = "translation",
  do_SQUAREM = TRUE,
  tolerance_elbo = 1e-08,
  tolerance_parameters = 1e-05,
  force_whole = TRUE,
  print_prog = NULL,
  do_timing = FALSE,
  verbose_time = FALSE,
  return_data = FALSE,
  linpred_method = "joint",
  vi_r_method = "VEM",
  verify_columns = FALSE,
  debug_param = FALSE,
  debug_ELBO = FALSE,
  debug_px = FALSE,
  quiet = TRUE,
  quiet_rho = TRUE,
  px_method = "dynamic",
  px_numerical_it = 10,
  hw_inner = 10,
  init = "EM_FE"
)

Arguments

iterations	Default of 1000; this sets the maximum number of iterations used in estimation.
prior_variance	Prior distribution on the random effect variance \Sigma_j. Options are hw, jeffreys, mean_exists, uniform, and gamma. The default (hw) is the Huang-Wand (2013) prior whose hyper-parameters are \nu_j = 2 and A_{j,k} = 5. Otherwise, the prior is an Inverse Wishart with the following parameters where d_j is the dimensionality of the random effect j. mean_exists: IW(d_j + 1, I) jeffreys: IW(0, 0) uniform: IW(-[d_j+1], 0) limit: IW(d_j - 1, 0) Estimation may fail if an improper prior (jeffreys, uniform, limit) is used.
factorization_method	Factorization assumption for the variational approximation. Default of "strong", i.e. a fully factorized model. Described in detail in Goplerud (2022). "strong", "partial", and "weak" correspond to Schemes I, II, and III respectively in that paper.
parameter_expansion	Default of "translation" (see Goplerud 2022b). Valid options are "translation", "mean", or "none". "mean" should be employed if "translation" is not enabled or is too computationally expensive. For negative binomial estimation or any estimation where factorization_method != "strong", only "mean" and "none" are available.
do_SQUAREM	Default (TRUE) accelerates estimation using SQUAREM (Varadhan and Roland 2008).
tolerance_elbo	Default (1e-8) sets a convergence threshold if the change in the ELBO is below the tolerance.
tolerance_parameters	Default (1e-5) sets a convergence threshold that is achieved if no parameter changes by more than the tolerance from the prior estimated value.
force_whole	Default (TRUE) requires integers for observed outcome for binomial or count models. FALSE allows for fractional responses.
print_prog	Default (NULL) prints a "." to indicate once 5% of the total iterations have elapsed. Set to a positive integer int to print a "." every int iterations.
do_timing	Default (FALSE) does not estimate timing of each variational update; TRUE requires the package tictoc.
verbose_time	Default (FALSE) does not print the time elapsed for each parameter update. Set to TRUE, in conjunction with do_timing=TRUE, to see the time taken for each parameter update.
return_data	Default (FALSE) does not return the original design. Set to TRUE to debug convergence issues.
linpred_method	Default ("joint") updates the mean parameters for the fixed and random effects simultaneously. This can improve the speed of estimation but may be costly for large datasets; use "cyclical" to update each parameter block separately.
vi_r_method	Default ("VEM") uses a variational EM algorithm for updating r if family="negbin". This assumes a point mass distribution on r. A number can be provided to fix r. These are the only available options.
verify_columns	Default (FALSE) does not verify that all columns are drawn from the data.frame itself versus the environment. Set to TRUE to debug potential issues.
debug_param	Default (FALSE) does not store parameters before the final iteration. Set to TRUE to debug convergence issues.
debug_ELBO	Default (FALSE) does not store the ELBO after each parameter update. Set to TRUE to debug convergence issues.
debug_px	Default (FALSE) does not store information about whether parameter expansion worked. Set to TRUE to convergence issues.
quiet	Default (FALSE) does not print intermediate output about convergence. Set to TRUE to debug.
quiet_rho	Default (FALSE) does not print information about parameter expansions. Set to TRUE to debug convergence issues.
px_method	When code parameter_expansion="translation", default ("dynamic") tries a one-step late update and, if this fails, a numerical improvement by L-BFGS-B. For an Inverse-Wishart prior on \Sigma_j, this is set to "osl" that only attempts a one-step-late update.
px_numerical_it	Default of 10; if L-BFGS_B is needed for a parameter expansion, this sets the number of steps used.
hw_inner	If prior_variance="hw", this sets the number of repeated iterations between estimating \Sigma_j and a_{j,k} variational distributions at each iteration. A larger number approximates jointly updating both parameters. Default (10) typically performs well.
init	Default ("EM_FE") initializes the mean variational parameters for q(\beta, \alpha) by setting the random effects to zero and estimating the fixed effects using a short-running EM algorithm. "EM" initializes the model with a ridge regression with a guess as to the random effect variance. "random" initializes the means randomly. "zero" initializes them at zero.

Value

This function returns a named list with class vglmer_control. It is passed to vglmer in the argument control. This argument only accepts objects created using vglmer_control.

References

Goplerud, Max. 2022. "Fast and Accurate Estimation of Non-Nested Binomial Hierarchical Models Using Variational Inference." Bayesian Analysis. 17(2): 623-650.

Goplerud, Max. 2024. "Re-Evaluating Machine Learning for MRP Given the Comparable Performance of (Deep) Hierarchical Models." American Political Science Review. 118(1): 529-536.

Huang, Alan, and Matthew P. Wand. 2013. "Simple Marginally Noninformative Prior Distributions for Covariance Matrices." Bayesian Analysis. 8(2):439-452.

Varadhan, Ravi, and Christophe Roland. 2008. "Simple and Globally Convergent Methods for Accelerating the Convergence of any EM Algorithm." Scandinavian Journal of Statistics. 35(2): 335-353.

vglmer documentation built on April 3, 2025, 6:07 p.m.