| 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 |
|