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