Computes variance inflation factors (VIF) and generalized VIF (GVIF) for a fitted brma meta-regression model. Also optionally returns the posterior correlation matrix of regression coefficients.
Usage
# S3 method for class 'brma'
vif(
object,
posterior_correlation = TRUE,
max_samples = Inf,
...,
probs = NULL,
include_samples = FALSE
)Arguments
- object
a fitted brma object with moderators
- posterior_correlation
logical; whether to also compute and return the posterior correlation matrix of regression coefficients. Defaults to
TRUE.- max_samples
maximum posterior draws used for the VIF/GVIF computation in every model class. Defaults to
Inf. Finite values deterministically thin draws across posterior row order. The optional posterior coefficient correlation still uses all draws.- ...
additional arguments (currently ignored)
- probs
optional credible-interval probabilities for GVIF (ordinary VIF for one-df terms). Defaults to
NULL, which retains the point-summary table. Requested empirical quantiles appear asCI_<probability>columns. These intervals describe GVIF, not its adjusted root.- include_samples
whether to include a
samplesdata frame with posteriordrawrow indices before thinning,term_index(the row of theviftable, also distinguishing repeated display labels),term,df,GVIF, andGVIF^(1/(2*df)). Defaults toFALSE.
Value
An object of class vif.brma containing:
- vif
A data frame with columns
term,df,GVIF, andGVIF^(1/(2*df))(= \(GVIF^{1/(2 \cdot df)}\)). For single-df terms, GVIF equals the standard VIF.- posterior_correlation
A correlation matrix of posterior regression coefficient samples when requested and available; otherwise
NULL.- samples
The optional long data frame of draw-wise diagnostics when
include_samples = TRUE. Printing and data-frame coercion of the result retain the summary-table view; extract this element explicitly for draws.
Details
VIF is computed from the correlation matrix derived from the coefficient variance-covariance matrix \((X'WX)^{-1}\). For standard meta-regression models, \(W = \mathrm{diag}(w_i/(v_i + \tau^2))\) at each posterior heterogeneity draw. Scale and multilevel models use observation-specific \(\tau_i\) and block-structured covariance where applicable. VIF/GVIF and its adjusted root are computed in each draw and averaged separately. These posterior means are generally different from applying VIF to an averaged covariance or to a posterior-mean heterogeneity. The mean adjusted GVIF is likewise generally different from transforming the mean GVIF. The diagnostic retains its GLS design-based meaning; it is not calculated from the empirical posterior covariance of the coefficients.
A VIF of 1 indicates no collinearity; values above 5 or 10 are commonly considered problematic.
The members of a RoBMA() ensemble can differ in their bias terms (PET
adds a PET column, PEESE a PEESE column, and the null and
weight-function members add none), so each posterior draw uses the design of
its member. A location term summarizes all selected posterior draws;
PET and PEESE summarize only draws in their own class
(NA when no selected draw belongs to it). Their samples are NA
outside that class, not zero, and their credible intervals are conditional
on class membership. Location terms keep the specified location design,
including terms with spike-and-slab priors.
For multi-column terms, such as factor contrasts, the Generalized VIF (GVIF) of Fox and Monette (1992) is reported. GVIF captures the joint inflation for all coefficients belonging to the same term. To enable comparison across terms with different degrees of freedom, \(GVIF^{1/(2 \cdot df)}\) is also reported; this value can be compared against the usual VIF thresholds (after squaring).
When posterior_correlation = TRUE, the function also returns the
posterior correlation matrix of the regression coefficients. This
Bayesian diagnostic complements VIF: while VIF diagnoses the
potential for collinearity problems (a data property), the
posterior correlation shows the realized identification
given the data and priors. Informative priors can mitigate
collinearity, reducing posterior correlations even when VIF is high.
Data-only objects created with only_data = TRUE are rejected because
VIF depends on fitted heterogeneity information, not just the parsed data.
For brma.mv() known-V models, VIF is computed from the full
marginal GLS covariance. Formula random effects are marginalized through
BayesTools' random-effect covariance metadata rather than treated as
conditioned fitted effects.
For known-V models, the VIF requires applying the inverse of the
marginal covariance. A covariance that is too ill-conditioned for that (a
reciprocal condition number of about 2e-10 or less in any posterior
draw used) is unavailable: the call stops with an error of class
RoBMA_known_v_precision_unavailable, whose parent class is
RoBMA_numerical_unavailable, instead of returning a rounded number.
The condition carries the draw positions (rows) and their
reciprocal_condition.
For generalized linear mixed models, this is a working effect-size-scale diagnostic based on the fitted model's approximate sampling variances. It is not a VIF derived directly from the binomial or Poisson information matrix. When the marginal covariance is fixed, the calculation reduces to the conventional fixed-covariance VIF used by metafor.
References
Fox J, Monette G (1992). “Generalized collinearity diagnostics.” Journal of the American Statistical Association, 87(417), 178–183. doi:10.1080/01621459.1992.10475190 .
Examples
if (FALSE) { # \dontrun{
if (requireNamespace("metadat", quietly = TRUE) &&
requireNamespace("metafor", quietly = TRUE)) {
data(dat.bcg, package = "metadat")
dat <- metafor::escalc(
measure = "RR",
ai = tpos,
bi = tneg,
ci = cpos,
di = cneg,
data = dat.bcg
)
fit <- brma(
yi = yi,
vi = vi,
mods = ~ ablat + year,
data = dat,
measure = "RR",
seed = 1,
silent = TRUE
)
vif(fit)
}
} # }