Debian Codegraph @

R/lm_robust.R

raw
1 #-------------------------------------
2 # vcovCR with defaults
3 #-------------------------------------
4
5 #' Cluster-robust variance-covariance matrix for an \code{estimatr::lm_robust}
6 #' object.
7 #'
8 #' \code{vcovCR} returns a sandwich estimate of the variance-covariance matrix
9 #' of a set of regression coefficient estimates from an
10 #' \code{\link[estimatr]{lm_robust}} object.
11 #'
12 #' @param cluster Expression or vector indicating which observations belong to
13 #' the same cluster. If not specified, will be detected from the
14 #' \code{clusters} argument of \code{obj}.
15 #' @param type Character string specifying which small-sample adjustment should
16 #' be used, with available options \code{"CR0"}, \code{"CR1"}, \code{"CR1p"},
17 #' \code{"CR1S"}, \code{"CR2"}, or \code{"CR3"}. If not specified, will be
18 #' detected from the \code{se_type} argument of \code{obj}. See "Details"
19 #' section of \code{\link{vcovCR}} for further information.
20 #' @param target Optional matrix or vector describing the working
21 #' variance-covariance model used to calculate the \code{CR2} and \code{CR4}
22 #' adjustment matrices. If a vector, the target matrix is assumed to be
23 #' diagonal. If not specified, the target is taken to be an identity matrix.
24 #' @inheritParams vcovCR
25 #'
26 #' @return An object of class \code{c("vcovCR","clubSandwich")}, which consists
27 #' of a matrix of the estimated variance of and covariances between the
28 #' regression coefficient estimates.
29 #'
30 #' @seealso \code{\link{vcovCR}}
31 #'
32 #' @examples
33 #'
34 #' data("ChickWeight", package = "datasets")
35 #' ChickWeight$Chick <- factor(ChickWeight$Chick, ordered = FALSE)
36 #'
37 #' if (requireNamespace("estimatr", quietly = TRUE)) withAutoprint({
38 #' library(estimatr)
39 #'
40 #' lm_fit <- lm_robust(
41 #' weight ~ Time + Diet:Time,
42 #' data = ChickWeight
43 #' )
44 #' vcovCR(lm_fit, cluster = ChickWeight$Chick, type = "CR2")
45 #'
46 #' lm_fit_clust <- lm_robust(
47 #' weight ~ Time + Diet:Time, data = ChickWeight,
48 #' clusters = Chick
49 #' )
50 #' conf_int(lm_fit_clust, vcov = "CR2")
51 #'
52 #' # similar model via lm_lin()
53 #' lin_fit_clust <- lm_lin(
54 #' weight ~ Diet,
55 #' covariates = ~ Time,
56 #' data = ChickWeight,
57 #' clusters = Chick
58 #' )
59 #' conf_int(lin_fit_clust, vcov = "CR2")
60 #'
61 #' lm_fit_fe <- lm_robust(
62 #' weight ~ Time:Diet, data = ChickWeight,
63 #' clusters = Chick,
64 #' fixed_effects = ~ Chick
65 #' )
66 #' vcovCR(lm_fit_fe)
67 #'
68 #' # two-way fixed effects model
69 #' data("MortalityRates")
70 #' MortalityRates <- subset(MortalityRates, cause == "Motor Vehicle")
71 #' MortalityRates$state <- factor(MortalityRates$state)
72 #' MortalityRates$year <- factor(MortalityRates$year)
73 #' MLDA_fit <- lm_robust(
74 #' mrate ~ legal + beertaxa + beerpercap + winepercap + spiritpercap,
75 #' fixed_effects = ~ year + state,
76 #' data = MortalityRates,
77 #' cluster = state
78 #' )
79 #' conf_int(MLDA_fit, vcov = "CR2")
80 #'
81 #' if (requireNamespace("plm", quietly = TRUE)) withAutoprint({
82 #'
83 #' data("Produc", package = "plm")
84 #' lm_individual <- lm_robust(
85 #' log(gsp) ~ log(pcap) + log(pc) + log(emp) + unemp,
86 #' data = Produc,
87 #' fixed_effects = ~ state,
88 #' cluster = state
89 #' )
90 #' vcovCR(lm_individual, type = "CR2")
91 #'
92 #' })
93 #'
94 #' })
95 #'
96 #' @export
97
98 vcovCR.lm_robust <- function(obj, cluster, type, target = NULL, inverse_var = NULL, form = "sandwich", ...) {
99
100 if (obj$fes && !requireNamespace("fixest", quietly = TRUE)) {
101 message("For improved performance in models with fixed effects, install the package {fixest}.")
102 }
103
104 obj$model.frame <- model.frame(obj)
105
106 if (missing(cluster)) {
107 cluster <- findCluster.lm_robust(obj)
108 if (is.null(cluster)) stop("You must specify a clustering variable or `obj` must include a clustering variable.")
109 }
110
111 if (missing(type)) {
112 type <- switch(obj$se_type, CR0 = "CR0", CR2 = "CR2", stata = "CR1S", "No valid SE type")
113 if (type == "No valid SE type") stop("You must specify a `type` of sandwich estimator to calculate or `obj` must include an `se_type` of 'CR0','CR2',or 'stata'.")
114 }
115
116 if (is.null(inverse_var)) inverse_var <- is.null(weights(obj)) & is.null(target)
117
118 vcov_CR(obj, cluster = cluster, type = type,
119 target = target, inverse_var = inverse_var, form = form)
120 }
121
122
123 #' Pulls clustering variable from lm_robust objects, if they have one.
124 #'
125 #' @param obj an lm_robust object
126 #'
127 #' @return The data within the clustering variable
128 #' @keywords internal
129 #' @noRd
130
131 findCluster.lm_robust <- function(obj) {
132
133 if (!obj$clustered) return(NULL)
134
135 model.frame(obj)[["(clusters)"]]
136 }
137
138
139 #' @export
140
141 augmented_model_matrix.lm_robust <- function(obj, cluster, inverse_var, ignore_FE) {
142
143 if(!obj$fes) return(NULL)
144
145 # get formula for the fixed effects
146 fe_formula <- as.formula(obj$call$fixed_effects)
147 fe_formula <- update(fe_formula, ~ . - 1)
148
149 # get the model.frame
150 mf <- model.frame(obj)
151
152 # ensure fixed effects are all factors
153 varnames <- all.vars(fe_formula)
154 for (v in varnames) mf[[v]] <- as.factor(mf[[v]])
155
156 # compute model.matrix of the fixed effects
157 model.matrix(fe_formula, data = mf)
158
159 }
160
161
162 requireNamespace <- function(...) base::requireNamespace(...)
163
164
165 #' @export
166 model_matrix.lm_robust <- function(obj) {
167
168 # get formula
169 frm <- as.formula(obj$call$formula)
170
171 # If model was made using lm_lin
172 if ("lm_lin" %in% as.character(obj$call[[1]])) {
173
174 # get covariate formula, if it exists
175 covariates <- as.formula(obj$call$covariates)
176
177 if (!is.null(covariates)) { # No covariates case - keep original formula as is
178
179 # get model frame
180 mf <- model.frame(obj)
181
182 # With covariates - preserve the intercept specification from original formula
183 treatment <- all.vars(frm[[3]])
184 covar_names <- paste0("`",names(obj$scaled_center), "_c`")
185 interactions <- paste0(treatment, ":", covar_names)
186 update_formula <- reformulate(c(".", covar_names, interactions))
187 frm <- update(old = frm, new = update_formula)
188
189 }
190
191 # use model frame and formula built above to return model matrix
192 return(model.matrix(frm, data = mf))
193
194 } else { # If model was made using lm_robust
195 # If no fixed effects, just return default mm
196 if (!obj$fes) {
197 return(model.matrix(obj))
198 } else { # If fixed effects
199 # get model frame
200 mf <- model.frame(obj)
201
202 # get base model matrix
203 X_mat <- model.matrix(frm, data = mf)
204 intercept_col <- colnames(X_mat) == "(Intercept)"
205 if (any(intercept_col)) {
206 X_mat <- X_mat[,!intercept_col,drop=FALSE]
207 }
208
209 # get fixed effects formula
210 fe_formula <- as.formula(obj$call$fixed_effects)
211
212 # use fixed effects formula to get model matrix for fixed effects,
213 # then connect it to the base model matrix
214 if (requireNamespace("fixest", quietly = TRUE)) {
215 frame <- mf[attr(terms(fe_formula),"term.labels")]
216 X_demean <- fixest::demean(X = X_mat, f = frame)
217 } else {
218 fe_formula <- update(fe_formula, ~ . - 1)
219 F_mat <- model.matrix(fe_formula, data = mf)
220 X_reg <- stats::lm.fit(F_mat, X_mat)
221 X_demean <- X_reg$residuals
222 }
223
224 return(X_demean)
225 }
226 }
227 }
228
229
230 #' @export
231
232 model.frame.lm_robust <- function (formula, ...) {
233
234 # Check if model.frame is already stored in the object
235 mf <- formula$model.frame
236 if (!is.null(mf)) return(mf)
237
238 # environment where initial call was evaluated
239 fit_env <- environment(formula$terms)
240
241 # Extract relevant arguments from call
242 cl <- formula$call
243
244 # Extract relevant arguments from call
245 mf_args <- match(c("formula","data","weights","subset","clusters"), names(cl), 0L)
246
247 # Construct the model.frame for outcome and core predictors
248 mf_cl <- cl[c(1L, mf_args)]
249 mf_cl[[1L]] <- quote(stats::model.frame)
250 mf <- eval(mf_cl, envir = fit_env)
251
252 # If model was made using lm_lin
253 if ("lm_lin" %in% as.character(formula$call[[1]])) {
254 if (!"covariates" %in% names(cl)) return(mf)
255 word <- "covariates"
256 } else { # If model was made using lm_robust
257 if (!formula$fes) return(mf)
258 word <- "fixed_effects"
259 }
260
261 # Construct a model.frame for covariates or fixed effects
262 word_args <- match(c(word,"data","subset"), names(cl), 0L)
263 word_cl <- cl[c(1L, word_args)]
264 names(word_cl)[[2]] <- "formula"
265 word_cl[[2]] <- reformulate(all.vars(word_cl[[2]])) # remove any expressions to get basic variables
266 word_cl[[1L]] <- quote(stats::model.frame)
267 mf_word <- eval(word_cl, envir = fit_env)
268
269 # compare omitted rows across model and covariates/fixed effects
270 mf_omit <- na.action(mf)
271 if (!is.null(names(mf_omit))) mf_omit <- names(mf_omit)
272 word_omit <- na.action(mf_word)
273 if (!is.null(names(word_omit))) word_omit <- names(word_omit)
274
275 # combine model.frames for model and for covariates/fixed effects
276 if (identical(mf_omit, word_omit)) {
277 mf_combined <- cbind(mf, mf_word)
278 mf_combined_omit <- mf_omit
279 } else {
280 mf_combined <- cbind(
281 mf[!(rownames(mf) %in% word_omit),,drop=FALSE],
282 mf_word[!(rownames(mf_word) %in% mf_omit),,drop=FALSE]
283 )
284 mf_combined_omit <- sort(c(mf_omit, word_omit))
285 i_unique <- !duplicated(mf_combined_omit)
286 mf_combined_omit <- mf_combined_omit[i_unique]
287 class(mf_combined_omit) <- "omit"
288 }
289
290 # Take care of centering if needed
291 if (word == "covariates") {
292
293 # Calculate centered covariatess
294 uncentered_mm <- model.matrix(as.formula(cl$covariates), data = mf_combined)
295 covar_names <- names(formula$scaled_center)
296 for (v in covar_names) {
297 v_c <- paste0(v, "_c")
298 mf_combined[[v_c]] <- uncentered_mm[,v] - formula$scaled_center[v]
299 }
300
301 # Remove uncentered covariates
302 covariate_terms <- all.vars(word_cl$formula)
303 for (v in covariate_terms) mf_combined[[v]] <- NULL
304
305 }
306
307 attr(mf_combined, "terms") <- attr(mf, "terms")
308 attr(mf_combined, "na.action") <- mf_combined_omit
309
310 return(mf_combined)
311 }
312
313
314 #' @export
315
316 residuals.lm_robust <- function(object, ...) {
317
318 mf <- model.frame(object)
319
320 mf[[object$outcome]] - object$fitted.values
321
322 }
323
324
325 #' @export
326
327 bread.lm_robust <- function(x, ...) {
328
329 N <- nobs(x)
330
331 X_mat <- model_matrix(x)
332
333 if (x$weighted) {
334 XtWX <- crossprod(X_mat, x$weights * X_mat)
335 } else {
336 XtWX <- crossprod(X_mat)
337 }
338
339 N * solve(XtWX)
340 }
341
342
343 #' @export
344
345 na.action.lm_robust <- function(object, ...) {
346 na.action(model.frame(object))
347 }
348