| 1 |
#------------------------------------- |
| 2 |
# vcovCR with defaults |
| 3 |
#------------------------------------- |
| 4 |
|
| 5 |
#' Cluster-robust variance-covariance matrix for an lme 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[nlme]{lme}} object. |
| 9 |
#' |
| 10 |
#' @param cluster Optional expression or vector indicating which observations |
| 11 |
#' belong to the same cluster. If not specified, will be set to |
| 12 |
#' \code{getGroups(obj)}. |
| 13 |
#' @param target Optional matrix or vector describing the working |
| 14 |
#' variance-covariance model used to calculate the \code{CR2} and \code{CR4} |
| 15 |
#' adjustment matrices. If not specified, the target is taken to be the |
| 16 |
#' estimated variance-covariance structure of the \code{lme} object. |
| 17 |
#' @inheritParams vcovCR |
| 18 |
#' |
| 19 |
#' @return An object of class \code{c("vcovCR","clubSandwich")}, which consists |
| 20 |
#' of a matrix of the estimated variance of and covariances between the |
| 21 |
#' regression coefficient estimates. |
| 22 |
#' |
| 23 |
#' @seealso \code{\link{vcovCR}} |
| 24 |
#' |
| 25 |
#' @examples |
| 26 |
#' |
| 27 |
#' if (requireNamespace("nlme", quietly = TRUE)) { |
| 28 |
#' |
| 29 |
#' library(nlme) |
| 30 |
#' rat_weight <- lme(weight ~ Time * Diet, data=BodyWeight, ~ Time | Rat) |
| 31 |
#' vcovCR(rat_weight, type = "CR2") |
| 32 |
#' |
| 33 |
#' } |
| 34 |
#' |
| 35 |
#' pkgs_available <- |
| 36 |
#' requireNamespace("nlme", quietly = TRUE) & |
| 37 |
#' requireNamespace("mlmRev", quietly = TRUE) |
| 38 |
#' |
| 39 |
#' if (pkgs_available) { |
| 40 |
#' |
| 41 |
#' data(egsingle, package = "mlmRev") |
| 42 |
#' subset_ids <- levels(egsingle$schoolid)[1:10] |
| 43 |
#' egsingle_subset <- subset(egsingle, schoolid %in% subset_ids) |
| 44 |
#' |
| 45 |
#' math_model <- lme(math ~ year * size + female + black + hispanic, |
| 46 |
#' random = list(~ year | schoolid, ~ 1 | childid), |
| 47 |
#' data = egsingle_subset) |
| 48 |
#' |
| 49 |
#' vcovCR(math_model, type = "CR2") |
| 50 |
#' |
| 51 |
#' } |
| 52 |
#' |
| 53 |
#' @export |
| 54 |
|
| 55 |
vcovCR.lme <- function(obj, cluster, type, target, inverse_var, form = "sandwich", ...) { |
| 56 |
if (missing(cluster)) cluster <- nlme::getGroups(obj, level = 1) |
| 57 |
if (missing(target)) target <- NULL |
| 58 |
if (missing(inverse_var)) inverse_var <- is.null(target) |
| 59 |
vcov_CR(obj, cluster = cluster, type = type, |
| 60 |
target = target, inverse_var = inverse_var, form = form) |
| 61 |
} |
| 62 |
|
| 63 |
# nobs() |
| 64 |
|
| 65 |
#------------------------------------- |
| 66 |
# residuals_CS() |
| 67 |
#------------------------------------- |
| 68 |
|
| 69 |
#' @export |
| 70 |
|
| 71 |
residuals_CS.lme <- function(obj) |
| 72 |
residuals(obj, level = 0) |
| 73 |
|
| 74 |
#------------------------------------- |
| 75 |
# coef_CS() |
| 76 |
#------------------------------------- |
| 77 |
|
| 78 |
#' @export |
| 79 |
|
| 80 |
coef_CS.lme <- function(obj) |
| 81 |
nlme::fixef(obj) |
| 82 |
|
| 83 |
#------------------------------------- |
| 84 |
# model_matrix() |
| 85 |
#------------------------------------- |
| 86 |
|
| 87 |
#' @export |
| 88 |
|
| 89 |
model_matrix.lme <- function(obj) { |
| 90 |
dat <- droplevels(get_data(obj)) |
| 91 |
model.matrix(formula(obj), data = dat) |
| 92 |
} |
| 93 |
|
| 94 |
#------------------------------------- |
| 95 |
# Get (model-based) working variance matrix |
| 96 |
#------------------------------------- |
| 97 |
|
| 98 |
get_cor_grouping <- function(obj, levels = NULL) { |
| 99 |
if (!is.null(obj$groups)) { |
| 100 |
struct <- obj$modelStruct$corStruct |
| 101 |
if (is.null(struct)) struct <- obj |
| 102 |
mod_formula <- nlme::getGroupsFormula(struct) |
| 103 |
grps <- stats::model.frame(mod_formula, data = nlme::getData(obj)) |
| 104 |
grps <- lapply(grps, as.character) |
| 105 |
grps <- do.call(paste, args = c(grps, sep = "/")) |
| 106 |
if (is.null(levels)) levels <- unique(grps) |
| 107 |
grps <- factor(grps, levels = levels) |
| 108 |
} else if (!is.null(obj$modelStruct$corStruct)) { |
| 109 |
grps <- factor(rep("A",obj$dims$N)) |
| 110 |
} else { |
| 111 |
grps <- factor(1:obj$dims$N) |
| 112 |
} |
| 113 |
grps |
| 114 |
} |
| 115 |
|
| 116 |
# Construct list of block-diagonal lowest-level var-cov matrices |
| 117 |
|
| 118 |
get_sort_order <- function(obj) { |
| 119 |
groups <- obj$groups |
| 120 |
|
| 121 |
if (is.data.frame(groups)) { |
| 122 |
order(do.call(order, groups)) |
| 123 |
} else if (!is.null(groups)) { |
| 124 |
order(order(groups)) |
| 125 |
} else { |
| 126 |
1:obj$dims$N |
| 127 |
} |
| 128 |
} |
| 129 |
|
| 130 |
build_var_cor_mats <- function(obj) { |
| 131 |
|
| 132 |
if (is.null(obj$modelStruct$corStruct)) { |
| 133 |
|
| 134 |
# if there is no correlation structure, |
| 135 |
# then build block-diagonals with first available grouping variable |
| 136 |
|
| 137 |
if (is.null(obj$groups)) { |
| 138 |
|
| 139 |
# if there are no groups then make diagonal matrix-lists |
| 140 |
|
| 141 |
if (is.null(obj$modelStruct$varStruct)) { |
| 142 |
V_list <- as.list(rep(1, obj$dims$N)) |
| 143 |
} else { |
| 144 |
sd_vec <- 1 / as.numeric(nlme::varWeights(obj$modelStruct$varStruct)) |
| 145 |
V_list <- as.list(sd_vec^2) |
| 146 |
} |
| 147 |
grps <- factor(1:obj$dims$N) |
| 148 |
attr(V_list, "groups") <- grps |
| 149 |
names(V_list) <- levels(grps) |
| 150 |
|
| 151 |
} else { |
| 152 |
|
| 153 |
# if there are groups then make block-diagonal matrix-lists |
| 154 |
|
| 155 |
if (is.null(obj$modelStruct$varStruct)) { |
| 156 |
grps <- obj$groups[[1]] |
| 157 |
V_list <- tapply(rep(1, length(grps)), grps, diag) |
| 158 |
} else { |
| 159 |
sort_order <- get_sort_order(obj) |
| 160 |
sd_vec <- 1 / as.numeric(nlme::varWeights(obj$modelStruct$varStruct))[sort_order] |
| 161 |
V_list <- tapply(sd_vec^2, obj$groups[[1]], diag) |
| 162 |
} |
| 163 |
attr(V_list, "groups") <- obj$groups[[1]] |
| 164 |
} |
| 165 |
|
| 166 |
} else { |
| 167 |
|
| 168 |
# if there is a correlation structure, |
| 169 |
# build block-diagonals according to its grouping structure |
| 170 |
|
| 171 |
R_list <- nlme::corMatrix(obj$modelStruct$corStruct) |
| 172 |
|
| 173 |
if (!is.list(R_list)) R_list <- list(A = R_list) |
| 174 |
|
| 175 |
cor_grps <- attr(obj$modelStruct$corStruct, "groups") |
| 176 |
missing_grps <- setdiff(levels(cor_grps), names(R_list)) |
| 177 |
|
| 178 |
if (length(missing_grps) > 0) { |
| 179 |
R_full <- rep(list(matrix(1,1,1)), nlevels(cor_grps)) |
| 180 |
names(R_full) <- levels(cor_grps) |
| 181 |
R_full[names(R_list)] <- R_list |
| 182 |
R_list <- R_full |
| 183 |
} |
| 184 |
|
| 185 |
if (is.null(obj$modelStruct$varStruct)) { |
| 186 |
V_list <- R_list |
| 187 |
} else { |
| 188 |
sd_vec <- 1 / as.numeric(nlme::varWeights(obj$modelStruct$varStruct)) |
| 189 |
sd_list <- split(sd_vec, cor_grps) |
| 190 |
V_list <- Map(function(R, s) tcrossprod(s) * R, R = R_list, s = sd_list) |
| 191 |
} |
| 192 |
|
| 193 |
grps <- get_cor_grouping(obj) |
| 194 |
V_list <- V_list[levels(grps)] |
| 195 |
|
| 196 |
attr(V_list, "groups") <- grps |
| 197 |
} |
| 198 |
|
| 199 |
return(V_list) |
| 200 |
} |
| 201 |
|
| 202 |
build_RE_mats <- function(obj) { |
| 203 |
|
| 204 |
# Get random effects structure |
| 205 |
all_groups <- rev(obj$groups) |
| 206 |
|
| 207 |
if (length(all_groups) == 1) { |
| 208 |
|
| 209 |
D_mat <- as.matrix(obj$modelStruct$reStruct[[1]]) |
| 210 |
Z_mat <- model.matrix(obj$modelStruct$reStruc, nlme::getData(obj)) |
| 211 |
row.names(Z_mat) <- NULL |
| 212 |
Z_list <- matrix_list(Z_mat, all_groups[[1]], "row") |
| 213 |
ZDZ_list <- ZDZt(D_mat, Z_list) |
| 214 |
|
| 215 |
attr(ZDZ_list, "groups") <- all_groups[[1]] |
| 216 |
|
| 217 |
} else { |
| 218 |
D_list <- lapply(obj$modelStruct$reStruct, as.matrix) |
| 219 |
Z_mat <- model.matrix(obj$modelStruct$reStruc, nlme::getData(obj)) |
| 220 |
Z_names <- sapply(strsplit(colnames(Z_mat), ".", fixed=TRUE), function(x) x[1]) |
| 221 |
row.names(Z_mat) <- NULL |
| 222 |
Z_levels <- lapply(names(all_groups), function(x) Z_mat[,x==Z_names,drop=FALSE]) |
| 223 |
Z_levels <- Map(matrix_list, x = Z_levels, fac = all_groups, dim = "row") |
| 224 |
ZDZ_lists <- Map(ZDZt, D = D_list, Z_list = Z_levels) |
| 225 |
|
| 226 |
for (i in 2:length(all_groups)) { |
| 227 |
ZDZ_lists[[i]] <- add_bdiag(small_mats = ZDZ_lists[[i-1]], |
| 228 |
big_mats = ZDZ_lists[[i]], |
| 229 |
crosswalk = all_groups[c(i-1,i)]) |
| 230 |
} |
| 231 |
|
| 232 |
ZDZ_list <- ZDZ_lists[[i]] |
| 233 |
|
| 234 |
attr(ZDZ_list, "groups") <- all_groups[[i]] |
| 235 |
|
| 236 |
} |
| 237 |
|
| 238 |
ZDZ_list |
| 239 |
|
| 240 |
} |
| 241 |
|
| 242 |
ZDZt <- function(D, Z_list) { |
| 243 |
lapply(Z_list, function(z) z %*% D %*% t(z)) |
| 244 |
} |
| 245 |
|
| 246 |
#' @export |
| 247 |
|
| 248 |
targetVariance.lme <- function(obj, cluster = nlme::getGroups(obj, level = 1)) { |
| 249 |
|
| 250 |
if (inherits(obj, "nlme")) stop("not implemented for \"nlme\" objects") |
| 251 |
|
| 252 |
# lowest-level covariance structure |
| 253 |
V_list <- build_var_cor_mats(obj) |
| 254 |
|
| 255 |
# random effects covariance structure |
| 256 |
ZDZ_list <- build_RE_mats(obj) |
| 257 |
|
| 258 |
V_grps <- attr(V_list, "groups") |
| 259 |
|
| 260 |
# Check if lowest-level covariance structure is nested within RE structure |
| 261 |
ZDZ_grps <- attr(ZDZ_list, "groups") |
| 262 |
group_mapping <- tapply(ZDZ_grps, V_grps, function(x) length(unique(x))) |
| 263 |
nested <- all(group_mapping == 1L) |
| 264 |
|
| 265 |
if (nested) { |
| 266 |
target_list <- add_bdiag(V_list, ZDZ_list, data.frame(V_grps, ZDZ_grps)) |
| 267 |
target_grps <- attr(ZDZ_list, "groups") |
| 268 |
} else { |
| 269 |
V_mat <- unblock(V_list, block = V_grps) |
| 270 |
ZDZ_mat <- unblock(ZDZ_list, block = ZDZ_grps) |
| 271 |
target_list <- V_mat + ZDZ_mat |
| 272 |
target_grps <- factor(rep("A", nrow(target_list))) |
| 273 |
} |
| 274 |
|
| 275 |
# check if clustering level is higher than highest level of random effects |
| 276 |
|
| 277 |
tb_groups <- table(target_grps) |
| 278 |
tb_cluster <- table(cluster) |
| 279 |
|
| 280 |
if (length(tb_groups) < length(tb_cluster) | |
| 281 |
any(as.vector(tb_groups) != rep(as.vector(tb_cluster), length.out = length(tb_groups))) | |
| 282 |
any(names(tb_groups) != rep(names(tb_cluster), length.out = length(tb_groups)))) { |
| 283 |
|
| 284 |
# check that random effects are nested within clusters |
| 285 |
tb_cross <- table(target_grps, cluster) |
| 286 |
nested <- apply(tb_cross, 1, function(x) sum(x > 0) == 1) |
| 287 |
if (!all(nested)) stop("Random effects are not nested within clustering variable.") |
| 288 |
|
| 289 |
# expand target_list to level of clustering |
| 290 |
crosswalk <- data.frame(target_grps, cluster) |
| 291 |
target_list <- add_bdiag(small_mats = target_list, |
| 292 |
big_mats = matrix_list(rep(0, length(cluster)), cluster, dim = "both"), |
| 293 |
crosswalk = crosswalk) |
| 294 |
} |
| 295 |
|
| 296 |
return(target_list) |
| 297 |
} |
| 298 |
|
| 299 |
|
| 300 |
#------------------------------------- |
| 301 |
# Get weighting matrix |
| 302 |
#------------------------------------- |
| 303 |
|
| 304 |
#' @export |
| 305 |
|
| 306 |
weightMatrix.lme <- function(obj, cluster = nlme::getGroups(obj, level = 1)) { |
| 307 |
V_list <- targetVariance(obj, cluster) |
| 308 |
lapply(V_list, function(v) chol2inv(chol(v))) |
| 309 |
} |
| 310 |
|
| 311 |
#--------------------------------------- |
| 312 |
# Get bread matrix and scaling constant |
| 313 |
#--------------------------------------- |
| 314 |
|
| 315 |
#' @export |
| 316 |
|
| 317 |
bread.lme <- function(x, ...) { |
| 318 |
vcov(x) * v_scale(x) / x$sigma^2 |
| 319 |
} |
| 320 |
|
| 321 |
#' @export |
| 322 |
|
| 323 |
v_scale.lme <- function(obj) { |
| 324 |
nlevels(nlme::getGroups(obj)) |
| 325 |
} |