Debian Codegraph @

R/lme.R

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