vcov_hetero: Heteroskedasticity-Robust VCOV

In fixest: Fast Fixed-Effects Estimations

Heteroskedasticity-Robust VCOV

Description

Computes the heteroskedasticity-robust VCOV of fixest objects.

Usage

vcov_hetero(
  x,
  type = "hc1",
  exact = TRUE,
  boot.size = NULL,
  ssc = NULL,
  vcov_fix = TRUE
)

Arguments

x	A fixest object.
type	A string scalar equal to "HC1" (default), "HC2" or "HC3". Note that the case is ignored.
exact	Logical scalar, default is TRUE. Whether the diagonals of the projection matrix should be calculated exactly. If FALSE, then it will be approximated using a JLA algorithm. See details. Unless you have a very large number of observations, it is recommended to keep the default value.
boot.size	Integer scalar or NULL, default is 1000. This is only used when exact == FALSE. This determines the number of bootstrap samples used to estimate the projection matrix. If equal to NULL, it falls back to the default value of 1000.
ssc	An object returned by the function ssc. It specifies how to perform the small sample correction. Note that this argument is only used in "HC1" which accepts ssc arguments starting with "K". In that case when ssc(K.adj = FALSE), it leads to "HC0". The argument ssc is ignored for HC2 and HC2 VCOVs.
vcov_fix	Logical scalar, default is FALSE. If the VCOV ends up not being positive definite, whether to "fix" it using an eigenvalue decomposition (a la Cameron, Gelbach & Miller 2011). Since the VCOV should be PSD asymptotically, this might be a sign of a problem with using the asymptotic approximation (e.g. too few units in clusters). If a problem is detected, the function will print a message to inform you. Note that a message informs the user only if the regularized PD matrix is substantially different than the original non PD one (i.e. at least one difference between the two greated than 1e-8).

Value

If the first argument is a fixest object, then a VCOV is returned (i.e. a symmetric matrix).

If the first argument is not a fixest object, then a) implicitly the arguments are shifted to the left (i.e. vcov_hetero("HC3") is equivalent to vcov_hetero(type = "HC3") and b) a VCOV-request is returned and NOT a VCOV. That VCOV-request can then be used in the argument vcov of various fixest functions (e.g. vcov.fixest or even in the estimation calls).

Small sample correction

A custom small sample correction can be applied to the HC1 VCOV using the ssc argument and function. By default an adjustment of N/(N-K) is applied to the VCOV, with N the number of observations and K the number of parameters. If ssc(K.adj = FALSE), meaning that there is no adjustment, this leads to the HC0 VCOV. Finally ssc's arguemnts K.fixef and K.exact determine how to account for the parameters associated to the fixed-effects (if the estimation contains fixed-effects).

Author(s)

Laurent Berge and Kyle Butts

References

MacKinnon, J. G. (2012). "Thirty years of heteroscedasticity-robust inference." Recent Advances and Future Directions in Causality, Prediction, and Specification Analysis, pp. 437–461. https://doi.org/10.1007/978-1-4614-1653-1_17

Examples

base = iris
names(base) = c("y", "x1", "x2", "x3", "species")

est = feols(y ~ x1 | species, base)

vcov_hetero(est, "hc1")
vcov_hetero(est, "hc1", ssc = ssc(K.adj = FALSE))
vcov_hetero(est, "hc2")
vcov_hetero(est, "hc3")

# Using approximate hatvalues
vcov_hetero(est, "hc3", exact = FALSE, boot.size = 500)

fixest documentation built on March 18, 2026, 9:06 a.m.