vcovUnconditional: EXPERIMENTAL: Request unconditional variance in...

In marginaleffects: Predictions, Comparisons, Slopes, Marginal Means, and Hypothesis Tests

EXPERIMENTAL: Request unconditional variance in marginaleffects calls

Description

EXPERIMENTAL: Request unconditional variance in marginaleffects calls

Usage

vcovUnconditional(type = "HC0", cluster = NULL)

Arguments

type	Character string specifying the finite-sample adjustment. The available types are "HC0" and "HC1". "HC0" uses the raw plug-in covariance, while "HC1" multiplies the complete unconditional covariance by a conventional model degrees-of-freedom factor analogous to the one used by the sandwich package.
cluster	An optional one-sided formula such as ~id identifying the variable used for one-way clustered inference. The right-hand side must be a bare variable name; transformations and multiple variables are not supported. As in the default behavior of sandwich::vcovCL(), clustered estimates include the cluster-count adjustment G / (G - 1).

Details

The bare function form vcov = vcovUnconditional is equivalent to vcov = vcovUnconditional().

Without clustering, HC0 applies no finite-sample multiplier and HC1 applies n / (n - k). With clustering, HC0 applies G / (G - 1) and HC1 applies G / (G - 1) * (n - 1) / (n - k), where k is the dimension of the model's estimating-function system and G is the number of clusters. These multipliers match the corresponding sandwich adjustments. They are applied after the coefficient-estimation and empirical-distribution influence components have been combined. HC1 therefore scales the variance of both components and their cross-covariance; it does not correct only the first-stage model-score contribution. HC0 is the plug-in estimator derived by Hansen and Overgaard. Applying the HC1 multiplier to the complete unconditional influence function is a documented convention, not a target-level correction derived in that paper, and it is not generally an unbiased finite-sample correction. Because its factor depends on k, HC1 can differ across model specifications even when they produce the same averaged estimand. The df argument of the calling marginaleffects function controls the reference distribution for inference separately and does not determine these covariance multipliers.

Unconditional variance is available for effects evaluated over original model-data rows, valid subsets of those rows, or counterfactual grids that preserve a valid rowid/rowidcf mapping to original model-data rows. The effect must be averaged or aggregated with ⁠avg_*()⁠ or by, or it must be a scalar comparison. Hypotheses applied directly to unit-level effects are rejected because the empirical-distribution influence function is not identifiable from an arbitrary post-hoc hypothesis function. Synthetic grids such as newdata = "mean" are rejected because the current implementation cannot generally infer how those grid values vary with the empirical covariate distribution. Models must provide compatible score and bread matrices through sandwich::estfun()/sandwich::bread() or model-specific equivalents. Supported model classes are validated through an allow-list. Survey-weighted linear and generalized linear models fitted by survey::svyglm() are supported using their observation-level coefficient influence functions. For multiple-imputation objects, unconditional variance is estimated in each completed dataset and the results are pooled using Rubin's rules. Prediction methods that return posterior draws, censored and survival models such as tobit, survreg, and coxph, average predictions from fixest models with fixed effects, and nonlinear fixest models with fixed effects are rejected explicitly. For feols models with fixed effects, unconditional inference is available for additive differences and dydx/dyex slopes when the counterfactual data leave every fixed-effect and varying-slope variable unchanged. The combined influence function retains the covariance between coefficient estimation and the empirical covariate distribution, which is one ingredient of robustness to conditional-mean misspecification. That robustness also requires the model's score and bread methods to represent the derivative of its full estimating equations; this is not guaranteed for every supported model and link under misspecification. HC2 through HC5 are not available because their regression-leverage adjustments are not defined for this combined influence function.

Value

An object which can be supplied to the vcov argument of avg_predictions(), avg_comparisons(), or avg_slopes().

marginaleffects documentation built on Sept. 3, 2026, 9:08 a.m.