Debian Codegraph @

R/plm.R

raw
1 #-------------------------------------
2 # vcovCR with defaults
3 #-------------------------------------
4
5 #' Cluster-robust variance-covariance matrix for a plm object.
6 #'
7 #' \code{vcovCR} returns a sandwich estimate of the variance-covariance matrix
8 #' of a set of regression coefficient estimates from a \code{\link[plm]{plm}}
9 #' object.
10 #'
11 #' @param cluster Optional character string, expression, or vector indicating
12 #' which observations belong to the same cluster. For fixed-effect models that
13 #' include individual effects or time effects (but not both), the cluster will
14 #' be taken equal to the included fixed effects if not otherwise specified.
15 #' Clustering on individuals can also be obtained by specifying the name of
16 #' the individual index (e.g., \code{cluster = "state"}) or \code{cluster =
17 #' "individual"}; clustering on time periods can be obtained by specifying the
18 #' name of the time index (e.g., \code{cluster = "year"}) or \code{cluster =
19 #' "time"}; if a group index is specified, clustering on groups (in which
20 #' individuals are nested) can be obtained by specifying the name of the group
21 #' index or \code{cluster = "group"}. For random-effects models, the cluster
22 #' will be taken equal to the included random effect identifier if not
23 #' otherwise specified.
24 #' @param target Optional matrix or vector describing the working
25 #' variance-covariance model used to calculate the \code{CR2} and \code{CR4}
26 #' adjustment matrices. By default, the target is taken to be an identity
27 #' matrix for fixed effect models or the estimated compound-symmetric
28 #' covariance matrix for random effects models.
29 #' @param ignore_FE Optional logical controlling whether fixed effects are
30 #' ignored when calculating small-sample adjustments in models where fixed
31 #' effects are estimated through absorption.
32 #' @inheritParams vcovCR
33 #'
34 #' @return An object of class \code{c("vcovCR","clubSandwich")}, which consists
35 #' of a matrix of the estimated variance of and covariances between the
36 #' regression coefficient estimates.
37 #'
38 #' @seealso \code{\link{vcovCR}}
39 #'
40 #' @examples
41 #'
42 #' if (requireNamespace("plm", quietly = TRUE)) withAutoprint({
43 #'
44 #' library(plm)
45 #' # fixed effects
46 #' data("Produc", package = "plm")
47 #' plm_FE <- plm(log(gsp) ~ log(pcap) + log(pc) + log(emp) + unemp,
48 #' data = Produc, index = c("state","year","region"),
49 #' effect = "individual", model = "within")
50 #' vcovCR(plm_FE, type="CR2")
51 #' vcovCR(plm_FE, type = "CR2", cluster = Produc$region) # clustering on region
52 #'
53 #' # random effects
54 #' plm_RE <- update(plm_FE, model = "random")
55 #' vcovCR(plm_RE, type = "CR2")
56 #' vcovCR(plm_RE, type = "CR2", cluster = Produc$region) # clustering on region
57 #'
58 #' # nested random effects
59 #' plm_nested <- update(plm_FE, effect = "nested", model = "random")
60 #' vcovCR(plm_nested, type = "CR2") # clustering on region
61 #' })
62 #'
63 #' pkgs_available <- requireNamespace("plm", quietly = TRUE) & requireNamespace("AER", quietly = TRUE)
64 #'
65 #' if (pkgs_available) withAutoprint({
66 #' # first differencing
67 #' data(Fatalities, package = "AER")
68 #' Fatalities <- within(Fatalities, {
69 #' frate <- 10000 * fatal / pop
70 #' drinkagec <- cut(drinkage, breaks = 18:22, include.lowest = TRUE, right = FALSE)
71 #' drinkagec <- relevel(drinkagec, ref = 4)
72 #' })
73 #'
74 #' plm_FD <- plm(frate ~ beertax + drinkagec + miles + unemp + log(income),
75 #' data = Fatalities, index = c("state", "year"),
76 #' model = "fd")
77 #' vcovHC(plm_FD, method="arellano", type = "sss", cluster = "group")
78 #' vcovCR(plm_FD, type = "CR1S")
79 #' vcovCR(plm_FD, type = "CR2")
80 #'
81 #' })
82 #'
83 #' @export
84
85 vcovCR.plm <- function(obj, cluster, type, target, inverse_var, form = "sandwich", ignore_FE = FALSE, ...) {
86
87 if (missing(cluster)) {
88 cluster <- findCluster.plm(obj = obj)
89 } else {
90 cluster <- findCluster.plm(obj = obj, cluster = cluster)
91 }
92
93 if (missing(target)) target <- NULL
94 if (missing(inverse_var)) inverse_var <- is.null(target)
95 obj$na.action <- attr(obj$model, "na.action")
96
97 vcov_CR(obj, cluster = cluster, type = type,
98 target = target, inverse_var = inverse_var,
99 form = form, ignore_FE = ignore_FE)
100 }
101
102 get_index_order <- function(obj) {
103 envir <- environment(obj$formula)
104 mf <- match.call(plm::plm, call = obj$call, envir = envir)
105 dat <- eval(mf$data, envir)
106
107 index_names <- eval(mf$index)
108
109 if (inherits(dat, "pdata.frame") | is.numeric(index_names)) {
110 indices <- plm::index(obj)
111 } else {
112 if (is.null(index_names)) index_names <- names(dat)[1:2]
113 indices <- as.list(dat[index_names])
114 }
115
116 if (length(indices) == 3) indices <- indices[c(3,1:2)]
117 do.call(order, args = indices)
118 }
119
120 findCluster.plm <- function(obj, cluster) {
121
122 index <- attr(model.frame(obj),"index")
123 effect <- obj$args$effect
124
125 if (obj$args$model=="random" & effect=="twoways") stop("Variance matrix is not block diagonal. clubSandwich methods are not available for such models.")
126
127 if (missing(cluster)) {
128
129 # Infer missing clustering variable
130
131 if (effect=="twoways") stop("You must specify a clustering variable when effect = 'twoways'.")
132
133 cluster <- switch(obj$args$effect,
134 individual = index[[1]],
135 time = index[[2]],
136 nested = index[[3]])
137
138 } else if ((length(cluster)==1) & is.character(cluster)) {
139
140 # Translate clustering variable keywords
141
142 allowed_clusters <- switch(effect,
143 individual = c("individual","group"),
144 time = "time",
145 twoways = "none",
146 nested = "group")
147
148 if (cluster %in% c("individual","time","group")) {
149
150 # Check for nesting of random effects inside clusters
151 if (obj$args$model == "random" & !cluster %in% allowed_clusters) {
152 err_msg <- paste0("For a random effects model, cluster = '", cluster, "' is not allowed when effect = '", effect, "'.")
153 stop(err_msg)
154 }
155
156 cluster <- switch(cluster,
157 individual = index[[1]],
158 time = index[[2]],
159 group = index[[3]])
160
161 } else if (cluster %in% names(index)) {
162
163 cluster_ID <- c("individual","time","group")[1:length(index)][cluster == names(index)]
164
165 # Check for nesting of random effects inside clusters
166 if (obj$args$model == "random" & !cluster_ID %in% allowed_clusters) {
167 err_msg <- paste0("For a random effects model, cluster = '", cluster, "' is not allowed when effect = '", effect, "'.")
168 stop(err_msg)
169 }
170
171 cluster <- index[[cluster]]
172
173 } else {
174 err_msg <- paste0("Clustering variable could not be inferred. Please check the argument cluster = '", cluster, "'.")
175 stop(err_msg)
176 }
177
178 } else {
179
180 # Sort user-specified clustering variable
181
182 sort_order <- get_index_order(obj)
183 cluster <- cluster[sort_order]
184
185 }
186
187 # Check for nesting of random effects inside clusters
188
189 if (obj$args$model == "random") {
190 RE_index <- switch(effect,
191 individual = index[[1]],
192 time = index[[2]],
193 nested = index[[3]])
194
195 if(!check_nested(RE_index, cluster)) stop("Random effects are not nested within clustering variable. clubSandwich methods are not available for such models.")
196 }
197
198 if (obj$args$model=="fd") {
199 cluster <- cluster[index[[2]] != levels(index[[2]])[1]]
200 }
201
202 cluster
203 }
204
205 #-----------------------------------------------
206 # Model matrix
207 #-----------------------------------------------
208
209 #' @export
210
211 model_matrix.plm <- function(obj) {
212 if (obj$args$model=="random") {
213 model.matrix(Formula::as.Formula(formula(obj)), model.frame(obj))
214 } else {
215 cstcovar.rm <- switch(obj$args$model,
216 within = "all",
217 fd = "covariates",
218 pooling = "none",
219 between = "none")
220 model.matrix(obj,
221 model = obj$args$model,
222 effect = obj$args$effect,
223 cstcovar.rm = cstcovar.rm)
224 }
225 }
226
227 #----------------------------------------------
228 # Augmented model matrix
229 #----------------------------------------------
230
231 #' @export
232
233 augmented_model_matrix.plm <- function(obj, cluster, inverse_var, ignore_FE) {
234 index <- attr(model.frame(obj),"index")
235 individual <- droplevels(as.factor(index[[1]]))
236 time <- droplevels(as.factor(index[[2]]))
237 effect <- obj$args$effect
238
239 if (ignore_FE) {
240 S <- NULL
241 } else if (obj$args$model=="within") {
242 if (effect=="individual") {
243 if (inverse_var & identical(individual, cluster)) {
244 S <- NULL
245 } else {
246 S <- model.matrix(~ 0 + individual)
247 }
248 } else if (effect=="time") {
249 if (inverse_var & identical(time, cluster)) {
250 S <- NULL
251 } else {
252 S <- model.matrix(~ 0 + time)
253 }
254 } else if (effect=="twoways") {
255 if (inverse_var & identical(individual, cluster)) {
256 S <- residuals(lm.fit(model.matrix(~ 0 + individual), model.matrix(~ 0 + time)[,-1]))
257 } else if (inverse_var & identical(time, cluster)) {
258 S <- residuals(lm.fit(model.matrix(~ 0 + time), model.matrix(~ 0 + individual)[,-1]))
259 } else {
260 S <- model.matrix(~ 0 + individual + time)
261 }
262 }
263 } else {
264 S <- NULL
265 }
266
267 return(S)
268 }
269
270 #-------------------------------------
271 # unadjusted residuals
272 #-------------------------------------
273
274 #' @export
275
276 residuals_CS.plm <- function(obj) {
277 if (obj$args$model=="random") {
278 y <- plm::pmodel.response(formula(obj), model.frame(obj), model = "pooling")
279 nm <- names(y)
280 y <- as.numeric(y)
281 names(y) <- nm
282 Xb <- as.numeric(model_matrix(obj) %*% coef(obj))
283 y - Xb
284 } else {
285 residuals(obj)
286 }
287 }
288
289 #-------------------------------------
290 # Get (model-based) working variance matrix
291 #-------------------------------------
292
293 block_mat <- function(nj, r) {
294 Vj <- matrix(r, nj, nj)
295 diag(Vj) <- 1 + r
296 Vj
297 }
298
299 #' @export
300
301 targetVariance.plm <- function(obj, cluster) {
302
303 if (obj$args$model=="random") {
304
305 index <- attr(model.frame(obj),"index")
306 r <- obj$ercomp$sigma2[[2]] / obj$ercomp$sigma2[[1]]
307
308 if (obj$args$effect=="nested") {
309
310 r_grp <- obj$ercomp$sigma2[[3]] / obj$ercomp$sigma2[[1]]
311 grp_mat <- lapply(table(index[[3]]), function(x) matrix(r_grp, nrow = x, ncol = x))
312 ind_mat <- lapply(table(index[[1]]), block_mat, r = r)
313 RE_index <- index[[3]]
314 target_mat <- add_bdiag(ind_mat, grp_mat, crosswalk = index[c(1,3)])
315
316 } else {
317
318 RE_index <- switch(obj$args$effect,
319 individual = index[[1]],
320 time = index[[2]])
321 target_mat <- lapply(table(RE_index), block_mat, r = r)
322
323 }
324
325 nest_bdiag(target_mat, crosswalk = data.frame(RE_index, cluster))
326
327 } else {
328
329 matrix_list(rep(1, nobs(obj)), cluster, "both")
330
331 }
332 }
333
334 #-------------------------------------
335 # Get weighting matrix
336 #-------------------------------------
337
338 inverse_block_mat <- function(nj, r) {
339 theta <- r / (1 + r * nj)
340 Wj <- matrix(-theta, nj, nj)
341 diag(Wj) <- 1 - theta
342 Wj
343 }
344
345 inverse_nested_block_mat <- function(nj, r1, r2) {
346 V_inv <- lapply(nj, inverse_block_mat, r = r1)
347 const <- 1 / sqrt(1 / r2 + sum(nj / (1 + r1 * nj)))
348 vec <- const * rep(1 / (1 + nj * r1), nj)
349 indices <- factor(names(vec), levels = names(nj))
350 add_submatrices(indices, small_mat = V_inv, big_mat = -tcrossprod(vec))
351 }
352
353 #' @export
354
355 weightMatrix.plm <- function(obj, cluster) {
356
357 if (obj$args$model=="random") {
358
359 index <- attr(model.frame(obj),"index")
360 r <- obj$ercomp$sigma2[[2]] / obj$ercomp$sigma2[[1]]
361
362 if (obj$args$effect=="nested") {
363
364 r_grp <- obj$ercomp$sigma2[[3]] / obj$ercomp$sigma2[[1]]
365 njs <- tapply(index[[1]], index[[3]], function(x) table(droplevels(x)))
366 RE_index <- index[[3]]
367 target_mat <- lapply(njs, inverse_nested_block_mat, r1 = r, r2 = r_grp)
368
369 } else {
370
371 RE_index <- switch(obj$args$effect,
372 individual = index[[1]],
373 time = index[[2]])
374 target_mat <- lapply(table(RE_index), inverse_block_mat, r = r)
375
376 }
377
378 nest_bdiag(target_mat, crosswalk = data.frame(RE_index, cluster))
379
380 } else {
381
382 matrix_list(rep(1, nobs(obj)), cluster, "both")
383
384 }
385 }
386
387 #---------------------------------------
388 # Get bread matrix and scaling constant
389 #---------------------------------------
390
391 #' @export
392
393 bread.plm <- function(x, ...) {
394 v_scale(x) * vcov(x) / with(x, sum(residuals^2) / df.residual)
395 }
396
397 #' @export
398
399 v_scale.plm <- function(obj) {
400 max(sapply(attr(obj$model, "index"), nlevels))
401 }