Debian Codegraph @

man/vcovCR.Rd

raw
1 % Generated by roxygen2: do not edit by hand
2 % Please edit documentation in R/clubSandwich.R
3 \name{vcovCR}
4 \alias{vcovCR}
5 \alias{vcovCR.default}
6 \title{Cluster-robust variance-covariance matrix}
7 \usage{
8 vcovCR(obj, cluster, type, target, inverse_var, form, ...)
9
10 \method{vcovCR}{default}(
11 obj,
12 cluster,
13 type,
14 target = NULL,
15 inverse_var = FALSE,
16 form = "sandwich",
17 ...
18 )
19 }
20 \arguments{
21 \item{obj}{Fitted model for which to calculate the variance-covariance matrix}
22
23 \item{cluster}{Expression or vector indicating which observations belong to
24 the same cluster. For some classes, the cluster will be detected
25 automatically if not specified.}
26
27 \item{type}{Character string specifying which small-sample adjustment should
28 be used, with available options \code{"CR0"}, \code{"CR1"}, \code{"CR1p"},
29 \code{"CR1S"}, \code{"CR2"}, or \code{"CR3"}. See "Details" section of
30 \code{\link{vcovCR}} for further information.}
31
32 \item{target}{Optional matrix or vector describing the working
33 variance-covariance model used to calculate the \code{CR2} and \code{CR4}
34 adjustment matrices. If a vector, the target matrix is assumed to be
35 diagonal. If not specified, \code{vcovCR} will attempt to infer a value.}
36
37 \item{inverse_var}{Optional logical indicating whether the weights used in
38 fitting the model are inverse-variance. If not specified, \code{vcovCR}
39 will attempt to infer a value.}
40
41 \item{form}{Controls the form of the returned matrix. The default
42 \code{"sandwich"} will return the sandwich variance-covariance matrix.
43 Alternately, setting \code{form = "meat"} will return only the meat of the
44 sandwich and setting \code{form = B}, where \code{B} is a matrix of
45 appropriate dimension, will return the sandwich variance-covariance matrix
46 calculated using \code{B} as the bread. \code{form = "estfun"} will return the
47 (appropriately scaled) estimating function, the transposed crossproduct of
48 which is equal to the sandwich variance-covariance matrix.}
49
50 \item{...}{Additional arguments available for some classes of objects.}
51 }
52 \value{
53 An object of class \code{c("vcovCR","clubSandwich")}, which consists
54 of a matrix of the estimated variance of and covariances between the
55 regression coefficient estimates. The matrix has several attributes:
56 \describe{ \item{type}{indicates which small-sample adjustment was used}
57 \item{cluster}{contains the factor vector that defines independent
58 clusters} \item{bread}{contains the bread matrix} \item{v_scale}{constant
59 used in scaling the sandwich estimator} \item{est_mats}{contains a list of
60 estimating matrices used to calculate the sandwich estimator}
61 \item{adjustments}{contains a list of adjustment matrices used to calculate
62 the sandwich estimator} \item{target}{contains the working
63 variance-covariance model used to calculate the adjustment matrices. This
64 is needed for calculating small-sample corrections for Wald tests.} }
65 }
66 \description{
67 This is a generic function, with specific methods defined for
68 \code{\link[stats]{lm}}, \code{\link[plm]{plm}}, \code{\link[stats]{glm}},
69 \code{\link[nlme]{gls}}, \code{\link[nlme]{lme}},
70 \code{\link[robumeta]{robu}}, \code{\link[metafor]{rma.uni}},
71 \code{\link[metafor]{rma.mv}}, and \code{\link[estimatr]{lm_robust}}
72 objects.
73
74 \code{vcovCR} returns a sandwich estimate of the variance-covariance matrix
75 of a set of regression coefficient estimates.
76 }
77 \details{
78 \code{vcovCR} returns a sandwich estimate of the variance-covariance matrix
79 of a set of regression coefficient estimates.
80
81 Several different small sample corrections are available, which run
82 parallel with the "HC" corrections for heteroskedasticity-consistent
83 variance estimators, as implemented in \code{\link[sandwich]{vcovHC}}. The
84 "CR2" adjustment is recommended (Pustejovsky & Tipton, 2017; Imbens &
85 Kolesar, 2016). See Pustejovsky and Tipton (2017) and Cameron and Miller
86 (2015) for further technical details. Available options include: \describe{
87 \item{"CR0"}{is the original form of the sandwich estimator (Liang & Zeger,
88 1986), which does not make any small-sample correction.}
89 \item{"CR1"}{multiplies CR0 by \code{m / (m - 1)}, where \code{m} is the
90 number of clusters.}
91 \item{"CR1p"}{multiplies CR0 by \code{m / (m - p)}, where \code{m} is the
92 number of clusters and \code{p} is the number of covariates.}
93 \item{"CR1S"}{multiplies CR0 by \code{(m (N-1)) / [(m -
94 1)(N - p)]}, where \code{m} is the number of clusters, \code{N} is the
95 total number of observations, and \code{p} is the number of covariates.
96 Some Stata commands use this correction by default.}
97 \item{"CR2"}{is the
98 "bias-reduced linearization" adjustment proposed by Bell and McCaffrey
99 (2002) and further developed in Pustejovsky and Tipton (2017). The
100 adjustment is chosen so that the variance-covariance estimator is exactly
101 unbiased under a user-specified working model.}
102 \item{"CR3"}{approximates the leave-one-cluster-out jackknife variance estimator (Bell & McCaffrey,
103 2002).} }
104 }
105 \examples{
106
107 # simulate design with cluster-dependence
108 m <- 8
109 cluster <- factor(rep(LETTERS[1:m], 3 + rpois(m, 5)))
110 n <- length(cluster)
111 X <- matrix(rnorm(3 * n), n, 3)
112 nu <- rnorm(m)[cluster]
113 e <- rnorm(n)
114 y <- X \%*\% c(.4, .3, -.3) + nu + e
115 dat <- data.frame(y, X, cluster, row = 1:n)
116
117 # fit linear model
118 lm_fit <- lm(y ~ X1 + X2 + X3, data = dat)
119 vcov(lm_fit)
120
121 # cluster-robust variance estimator with CR2 small-sample correction
122 vcovCR(lm_fit, cluster = dat$cluster, type = "CR2")
123
124 # compare small-sample adjustments
125 CR_types <- paste0("CR",c("0","1","1S","2","3"))
126 sapply(CR_types, function(type)
127 sqrt(diag(vcovCR(lm_fit, cluster = dat$cluster, type = type))))
128
129 }
130 \references{
131 Bell, R. M., & McCaffrey, D. F. (2002). Bias reduction in
132 standard errors for linear regression with multi-stage samples. Survey
133 Methodology, 28(2), 169-181.
134
135 Cameron, A. C., & Miller, D. L. (2015). A Practitioner's Guide to
136 Cluster-Robust Inference. \emph{Journal of Human Resources, 50}(2), 317-372.
137 \doi{10.3368/jhr.50.2.317}
138
139 Imbens, G. W., & Kolesar, M. (2016). Robust standard errors in small samples:
140 Some practical advice. \emph{Review of Economics and Statistics, 98}(4),
141 701-712. \doi{10.1162/rest_a_00552}
142
143 Liang, K.-Y., & Zeger, S. L. (1986). Longitudinal data analysis using
144 generalized linear models. \emph{Biometrika, 73}(1), 13-22.
145 \doi{10.1093/biomet/73.1.13}
146
147 Pustejovsky, J. E. & Tipton, E. (2018). Small sample methods for
148 cluster-robust variance estimation and hypothesis testing in fixed effects
149 models. \emph{Journal of Business and Economic Statistics, 36}(4), 672-683.
150 \doi{10.1080/07350015.2016.1247004}
151 }
152 \seealso{
153 \code{\link{vcovCR.lm}}, \code{\link{vcovCR.plm}},
154 \code{\link{vcovCR.glm}}, \code{\link{vcovCR.gls}},
155 \code{\link{vcovCR.lme}}, \code{\link{vcovCR.lmerMod}}, \code{\link{vcovCR.robu}},
156 \code{\link{vcovCR.rma.uni}}, \code{\link{vcovCR.rma.mv}},
157 \code{\link{vcovCR.lm_robust}}
158 }