mixle.inference.robust module

Sandwich (robust) covariance estimators for M-estimators and regression.

A model’s “model-based” covariance (e.g. sigma^2 (X'X)^{-1} for OLS) is only correct when the model’s variance assumptions hold. When they don’t – heteroscedasticity, within-cluster correlation, serial correlation – the point estimate is often still consistent but its standard errors are wrong, usually too small. The sandwich estimator fixes the standard errors without changing the estimate:

Cov(theta_hat) = B M B’

where the bread B is the inverse sensitivity of the estimating equations ((X'X)^{-1} for OLS, the inverse negative Hessian / Fisher for a general M-estimator or GLM) and the meat M is the empirical covariance of the per-observation score contributions, formed to respect the failure you are guarding against:

• ols_robust_covariance() – heteroscedasticity-consistent HC0–HC3 for OLS.

• cluster_robust_covariance() – one-way and multi-way (Cameron–Gelbach–Miller) clustering, for correlation within groups (the genus-clustered SE pattern, and any repeated-measures design).

• newey_west_covariance() – heteroscedasticity- and autocorrelation-consistent (HAC) for serially correlated series.

• sandwich_covariance() – the generic core: hand it the per-observation scores and the bread and it works for any M-estimator / GLM.

robust_standard_errors() reads the standard errors off any of these covariance matrices.

robust_standard_errors(cov)

Standard errors sqrt(diag(cov)) from a covariance matrix.

Parameters:

cov (ndarray)

Return type:

ndarray

sandwich_covariance(scores, bread, *, clusters=None, n_params=None, small_sample=True)

Generic sandwich covariance B M B' from per-observation scores and the bread.

Parameters:

• scores (ndarray) – (n, p) per-observation contributions to the estimating equation (for OLS the i-th row is x_i * e_i; for a GLM the score of observation i).

• bread (ndarray) – (p, p) inverse sensitivity B (e.g. (X'X)^{-1} for OLS, the inverse negative Hessian / inverse Fisher for an M-estimator).

• clusters (ndarray | None) – optional (n,) cluster labels; scores are summed within cluster before forming the meat (the robust-to-within-cluster-correlation meat). If None, observations are independent.

• n_params (int | None) – number of estimated parameters for the small-sample correction (defaults to p).

• small_sample (bool) – apply the usual finite-sample correction (n/(n-p) for independent data, G/(G-1) * (n-1)/(n-p) for clustered).

Returns:

The (p, p) robust covariance matrix.

Return type:

ndarray

ols_robust_covariance(x, residuals, *, hc='hc1')

Heteroscedasticity-consistent (White) covariance for OLS coefficients.

Cov = (X'X)^{-1} ( sum_i w_i x_i x_i' ) (X'X)^{-1} where the per-observation weight w_i is the squared residual, optionally adjusted for leverage h_ii:

• hc0: e_i^2 (White’s original; biased down in small samples).

• hc1: e_i^2 * n/(n-p) (degrees-of-freedom correction; the common default).

• hc2: e_i^2 / (1 - h_ii).

• hc3: e_i^2 / (1 - h_ii)^2 (best small-sample behaviour; ~jackknife).

Parameters:

• x (ndarray) – (n, p) design matrix (include an intercept column if wanted).

• residuals (ndarray) – (n,) OLS residuals y - X beta_hat.

• hc (str) – one of "hc0", "hc1", "hc2", "hc3".

Returns:

The (p, p) robust covariance matrix.

Return type:

ndarray

cluster_robust_covariance(x, residuals, clusters, *, small_sample=True)

Cluster-robust (one-way or multi-way) covariance for OLS coefficients.

Allows arbitrary correlation within clusters while assuming independence across them. Pass one label array for one-way clustering, or a list/tuple of label arrays for multi-way clustering, which uses the Cameron–Gelbach–Miller inclusion–exclusion V_A + V_B - V_{A∩B} (two-way) and its higher-way generalisation.

Parameters:

• x (ndarray) – (n, p) design matrix.

• residuals (ndarray) – (n,) OLS residuals.

• clusters (ndarray | list) – (n,) labels, or a list of such arrays for multi-way clustering.

• small_sample (bool) – apply the G/(G-1) * (n-1)/(n-p) finite-sample correction per term.

Returns:

The (p, p) cluster-robust covariance matrix.

Return type:

ndarray

newey_west_covariance(x, residuals, *, lags=None, small_sample=True)

Newey–West HAC covariance for OLS coefficients (serially correlated errors).

Heteroscedasticity- and autocorrelation-consistent: the meat is the long-run covariance of the scores s_t = x_t e_t, estimated with Bartlett (triangular) weights so it stays positive semi-definite:

S = Gamma_0 + sum_{l=1}^{L} (1 - l/(L+1)) (Gamma_l + Gamma_l’), Gamma_l = sum_t s_t s_{t-l}’.

Rows of x (and residuals) are assumed to be in time order.

Parameters:

• x (ndarray) – (n, p) design matrix, rows in time order.

• residuals (ndarray) – (n,) residuals in time order.

• lags (int | None) – truncation lag L; defaults to the Newey–West rule floor(4 (n/100)^{2/9}).

• small_sample (bool) – apply the n/(n-p) degrees-of-freedom correction.

Returns:

The (p, p) HAC covariance matrix.

Return type:

ndarray