Debian Codegraph @

R/clubSandwich.R

raw
1 #----------------------------------------------
2 # user-facing vcovCR function
3 #----------------------------------------------
4
5 #' Cluster-robust variance-covariance matrix
6 #'
7 #' \code{vcovCR} returns a sandwich estimate of the variance-covariance matrix
8 #' of a set of regression coefficient estimates.
9 #'
10 #' @param obj Fitted model for which to calculate the variance-covariance matrix
11 #' @param cluster Expression or vector indicating which observations belong to
12 #' the same cluster. For some classes, the cluster will be detected
13 #' automatically if not specified.
14 #' @param type Character string specifying which small-sample adjustment should
15 #' be used, with available options \code{"CR0"}, \code{"CR1"}, \code{"CR1p"},
16 #' \code{"CR1S"}, \code{"CR2"}, or \code{"CR3"}. See "Details" section of
17 #' \code{\link{vcovCR}} for further information.
18 #' @param target Optional matrix or vector describing the working
19 #' variance-covariance model used to calculate the \code{CR2} and \code{CR4}
20 #' adjustment matrices. If a vector, the target matrix is assumed to be
21 #' diagonal. If not specified, \code{vcovCR} will attempt to infer a value.
22 #' @param inverse_var Optional logical indicating whether the weights used in
23 #' fitting the model are inverse-variance. If not specified, \code{vcovCR}
24 #' will attempt to infer a value.
25 #' @param form Controls the form of the returned matrix. The default
26 #' \code{"sandwich"} will return the sandwich variance-covariance matrix.
27 #' Alternately, setting \code{form = "meat"} will return only the meat of the
28 #' sandwich and setting \code{form = B}, where \code{B} is a matrix of
29 #' appropriate dimension, will return the sandwich variance-covariance matrix
30 #' calculated using \code{B} as the bread. \code{form = "estfun"} will return the
31 #' (appropriately scaled) estimating function, the transposed crossproduct of
32 #' which is equal to the sandwich variance-covariance matrix.
33 #' @param ... Additional arguments available for some classes of objects.
34 #'
35 #' @description This is a generic function, with specific methods defined for
36 #' \code{\link[stats]{lm}}, \code{\link[plm]{plm}}, \code{\link[stats]{glm}},
37 #' \code{\link[nlme]{gls}}, \code{\link[nlme]{lme}},
38 #' \code{\link[robumeta]{robu}}, \code{\link[metafor]{rma.uni}},
39 #' \code{\link[metafor]{rma.mv}}, and \code{\link[estimatr]{lm_robust}}
40 #' objects.
41 #'
42 #' @details Several different small sample corrections are available, which run
43 #' parallel with the "HC" corrections for heteroskedasticity-consistent
44 #' variance estimators, as implemented in \code{\link[sandwich]{vcovHC}}. The
45 #' "CR2" adjustment is recommended (Pustejovsky & Tipton, 2017; Imbens &
46 #' Kolesar, 2016). See Pustejovsky and Tipton (2017) and Cameron and Miller
47 #' (2015) for further technical details. Available options include: \describe{
48 #' \item{"CR0"}{is the original form of the sandwich estimator (Liang & Zeger,
49 #' 1986), which does not make any small-sample correction.}
50 #' \item{"CR1"}{multiplies CR0 by \code{m / (m - 1)}, where \code{m} is the
51 #' number of clusters.}
52 #' \item{"CR1p"}{multiplies CR0 by \code{m / (m - p)}, where \code{m} is the
53 #' number of clusters and \code{p} is the number of covariates.}
54 #' \item{"CR1S"}{multiplies CR0 by \code{(m (N-1)) / [(m -
55 #' 1)(N - p)]}, where \code{m} is the number of clusters, \code{N} is the
56 #' total number of observations, and \code{p} is the number of covariates.
57 #' Some Stata commands use this correction by default.}
58 #' \item{"CR2"}{is the
59 #' "bias-reduced linearization" adjustment proposed by Bell and McCaffrey
60 #' (2002) and further developed in Pustejovsky and Tipton (2017). The
61 #' adjustment is chosen so that the variance-covariance estimator is exactly
62 #' unbiased under a user-specified working model.}
63 #' \item{"CR3"}{approximates the leave-one-cluster-out jackknife variance estimator (Bell & McCaffrey,
64 #' 2002).} }
65 #'
66 #' @references Bell, R. M., & McCaffrey, D. F. (2002). Bias reduction in
67 #' standard errors for linear regression with multi-stage samples. Survey
68 #' Methodology, 28(2), 169-181.
69 #'
70 #' Cameron, A. C., & Miller, D. L. (2015). A Practitioner's Guide to
71 #' Cluster-Robust Inference. \emph{Journal of Human Resources, 50}(2), 317-372.
72 #' \doi{10.3368/jhr.50.2.317}
73 #'
74 #' Imbens, G. W., & Kolesar, M. (2016). Robust standard errors in small samples:
75 #' Some practical advice. \emph{Review of Economics and Statistics, 98}(4),
76 #' 701-712. \doi{10.1162/rest_a_00552}
77 #'
78 #' Liang, K.-Y., & Zeger, S. L. (1986). Longitudinal data analysis using
79 #' generalized linear models. \emph{Biometrika, 73}(1), 13-22.
80 #' \doi{10.1093/biomet/73.1.13}
81 #'
82 #' Pustejovsky, J. E. & Tipton, E. (2018). Small sample methods for
83 #' cluster-robust variance estimation and hypothesis testing in fixed effects
84 #' models. \emph{Journal of Business and Economic Statistics, 36}(4), 672-683.
85 #' \doi{10.1080/07350015.2016.1247004}
86 #'
87 #' @return An object of class \code{c("vcovCR","clubSandwich")}, which consists
88 #' of a matrix of the estimated variance of and covariances between the
89 #' regression coefficient estimates. The matrix has several attributes:
90 #' \describe{ \item{type}{indicates which small-sample adjustment was used}
91 #' \item{cluster}{contains the factor vector that defines independent
92 #' clusters} \item{bread}{contains the bread matrix} \item{v_scale}{constant
93 #' used in scaling the sandwich estimator} \item{est_mats}{contains a list of
94 #' estimating matrices used to calculate the sandwich estimator}
95 #' \item{adjustments}{contains a list of adjustment matrices used to calculate
96 #' the sandwich estimator} \item{target}{contains the working
97 #' variance-covariance model used to calculate the adjustment matrices. This
98 #' is needed for calculating small-sample corrections for Wald tests.} }
99 #'
100 #' @seealso \code{\link{vcovCR.lm}}, \code{\link{vcovCR.plm}},
101 #' \code{\link{vcovCR.glm}}, \code{\link{vcovCR.gls}},
102 #' \code{\link{vcovCR.lme}}, \code{\link{vcovCR.lmerMod}}, \code{\link{vcovCR.robu}},
103 #' \code{\link{vcovCR.rma.uni}}, \code{\link{vcovCR.rma.mv}},
104 #' \code{\link{vcovCR.lm_robust}}
105 #'
106 #' @examples
107 #'
108 #' # simulate design with cluster-dependence
109 #' m <- 8
110 #' cluster <- factor(rep(LETTERS[1:m], 3 + rpois(m, 5)))
111 #' n <- length(cluster)
112 #' X <- matrix(rnorm(3 * n), n, 3)
113 #' nu <- rnorm(m)[cluster]
114 #' e <- rnorm(n)
115 #' y <- X %*% c(.4, .3, -.3) + nu + e
116 #' dat <- data.frame(y, X, cluster, row = 1:n)
117 #'
118 #' # fit linear model
119 #' lm_fit <- lm(y ~ X1 + X2 + X3, data = dat)
120 #' vcov(lm_fit)
121 #'
122 #' # cluster-robust variance estimator with CR2 small-sample correction
123 #' vcovCR(lm_fit, cluster = dat$cluster, type = "CR2")
124 #'
125 #' # compare small-sample adjustments
126 #' CR_types <- paste0("CR",c("0","1","1S","2","3"))
127 #' sapply(CR_types, function(type)
128 #' sqrt(diag(vcovCR(lm_fit, cluster = dat$cluster, type = type))))
129 #'
130 #' @export
131 #' @import stats
132
133 vcovCR <- function(obj, cluster, type, target, inverse_var, form, ...) UseMethod("vcovCR")
134
135 #' Cluster-robust variance-covariance matrix
136 #'
137 #' \code{vcovCR} returns a sandwich estimate of the variance-covariance matrix
138 #' of a set of regression coefficient estimates.
139 #'
140 #' @rdname vcovCR
141 #' @export
142
143 vcovCR.default <- function(obj, cluster, type, target = NULL, inverse_var = FALSE, form = "sandwich", ...)
144 vcov_CR(obj, cluster, type, target, inverse_var, form)
145
146 #---------------------------------------------
147 # Cluster-robust variance estimator
148 #---------------------------------------------
149
150 handle_vectors <- function(x, obj) {
151
152 # Handle omitted observations due to missing outcome or predictors
153 if (inherits(na.action(obj), "omit")) {
154 x <- x[-na.action(obj)]
155 }
156
157 # Handle observations omitted due to weights of zero
158 if (!is.null(wts <- weights(obj))) {
159 pos_wts <- wts > 0
160 if (!all(pos_wts)) x <- x[pos_wts]
161 }
162
163 return(x)
164 }
165
166
167 adjust_est_mats <- function(type, est_mats, adjustments) {
168 switch(type,
169 CR0 = est_mats,
170 CR1 = lapply(est_mats, function(e) e * adjustments),
171 CR1p = lapply(est_mats, function(e) e * adjustments),
172 CR1S = lapply(est_mats, function(e) e * adjustments),
173 CR2 = Map(function(e, a) e %*% a, e = est_mats, a = adjustments),
174 CR3 = Map(function(e, a) e %*% a, e = est_mats, a = adjustments),
175 CR4 = Map(function(e, a) a %*% e, e = est_mats, a = adjustments))
176 }
177
178 # uses methods:
179 # residuals_CS(),
180 # model_matrix(),
181 # weightMatrix(),
182 # targetVariance(),
183 # bread(),
184 # v_scale()
185
186 vcov_CR <- function(obj, cluster, type, target = NULL, inverse_var = FALSE, form = "sandwich", ignore_FE = FALSE) {
187
188 cluster <- droplevels(as.factor(cluster))
189
190 alias <- is.na(coef_CS(obj))
191 X <- model_matrix(obj)
192 if (any(alias)) {
193 X <- X[, !alias, drop = FALSE]
194 }
195
196 p <- NCOL(X)
197 N <- NROW(X)
198
199 cluster_length <- length(cluster)
200
201 if (cluster_length != N) {
202
203 cluster <- droplevels(handle_vectors(cluster, obj))
204
205 if (length(cluster) != N) {
206 stop("Clustering variable must have length equal to the number of rows in the data used to fit obj.")
207 }
208
209 }
210
211 if (any(is.na(cluster))) stop("Clustering variable cannot have missing values.")
212
213 J <- nlevels(cluster)
214 if (J < 2) stop("Cluster-robust variance estimation will not work when the data only includes a single cluster.")
215
216 X_list <- matrix_list(X, cluster, "row")
217 W_list <- weightMatrix(obj, cluster)
218 XW_list <- Map(function(x, w) as.matrix(t(x) %*% w), x = X_list, w = W_list)
219
220 if (is.null(target)) {
221 if (inverse_var) {
222 Theta_list <- lapply(W_list, function(w) chol2inv(chol(w)))
223 } else {
224 Theta_list <- targetVariance(obj, cluster)
225 }
226 } else {
227 if (!is.list(target)) {
228 if (length(target) != N) {
229 target <- handle_vectors(target, obj)
230 }
231 Theta_list <- matrix_list(target, cluster, "both")
232 } else {
233 Theta_list <- target
234 }
235 }
236
237 if (type %in% c("CR2","CR4")) {
238 S <- augmented_model_matrix(obj, cluster, inverse_var, ignore_FE)
239
240 if (is.null(S)) {
241 rm(S)
242 U_list <- X_list
243 UW_list <- XW_list
244 } else {
245 U <- cbind(X, S)
246 rm(S)
247 U_list <- matrix_list(U, cluster, "row")
248 UW_list <- Map(function(u, w) as.matrix(t(u) %*% w), u = U_list, w = W_list)
249 }
250
251 UWU_list <- Map(function(uw, u) uw %*% u, uw = UW_list, u = U_list)
252 M_U <- matrix_power(Reduce("+",UWU_list), p = -1)
253 }
254
255 adjustments <- do.call(type, args = mget(names(formals(type))))
256
257 E_list <- adjust_est_mats(type = type, est_mats = XW_list, adjustments = adjustments)
258
259 resid <- residuals_CS(obj)
260 res_list <- split(resid, cluster)
261
262 components <- do.call(cbind, Map(function(e, r) e %*% r, e = E_list, r = res_list))
263
264 v_scale <- v_scale(obj)
265 w_scale <- attr(W_list, "w_scale")
266 if (is.null(w_scale)) w_scale <- 1L
267
268 if (form == "estfun") {
269 bread <- sandwich::bread(obj)
270 estfun <- bread %*% components
271 return(estfun * (w_scale / v_scale))
272 }
273
274 meat <- tcrossprod(components) * w_scale^2 / v_scale
275
276 if (form == "sandwich") {
277 bread <- sandwich::bread(obj)
278 } else if (form == "meat") {
279 bread <- NULL
280 } else if (is.matrix(form)) {
281 bread <- form
282 form <- "sandwich"
283 }
284
285 vcov <- switch(form,
286 sandwich = bread %*% meat %*% bread / v_scale,
287 meat = meat)
288 rownames(vcov) <- colnames(vcov) <- colnames(X)
289 attr(vcov, "type") <- type
290 attr(vcov, "cluster") <- cluster
291 attr(vcov, "bread") <- bread
292 attr(vcov, "v_scale") <- v_scale
293 attr(vcov, "est_mats") <- XW_list
294 attr(vcov, "adjustments") <- adjustments
295 attr(vcov, "target") <- Theta_list
296 attr(vcov, "inverse_var") <- inverse_var
297 attr(vcov, "ignore_FE") <- ignore_FE
298 class(vcov) <- c("vcovCR","clubSandwich")
299 return(vcov)
300 }
301
302 #---------------------------------------------
303 # as.matrix method for vcovCR
304 #---------------------------------------------
305
306 #' @export
307
308 as.matrix.clubSandwich <- function(x, ...) {
309 attr(x, "type") <- NULL
310 attr(x, "cluster") <- NULL
311 attr(x, "bread") <- NULL
312 attr(x, "v_scale") <- NULL
313 attr(x, "est_mats") <- NULL
314 attr(x, "adjustments") <- NULL
315 attr(x, "target") <- NULL
316 attr(x, "inverse_var") <- NULL
317 attr(x, "ignore_FE") <- NULL
318 class(x) <- "matrix"
319 x
320 }
321
322
323 #---------------------------------------------
324 # print method for vcovCR
325 #---------------------------------------------
326
327 #' @export
328
329 print.clubSandwich <- function(x, ...) {
330 print(as.matrix(x))
331 }