| 1 |
# from https://github.com/lme4/lme4 |
| 2 |
if(getRversion() < "2.15") |
| 3 |
paste0 <- function(...) paste(..., sep = '') |
| 4 |
|
| 5 |
### Utilities for parsing and manipulating mixed-model formulas |
| 6 |
|
| 7 |
##' From the result of \code{\link{findbars}} applied to a model formula and |
| 8 |
##' and the evaluation frame, create the model matrix, etc. associated with |
| 9 |
##' random-effects terms. See the description of the returned value for a |
| 10 |
##' detailed list. |
| 11 |
##' |
| 12 |
##' @title Create Z, Lambda, Lind, etc. |
| 13 |
##' @param bars a list of parsed random-effects terms |
| 14 |
##' @param fr a model frame in which to evaluate these terms |
| 15 |
##' @return a list with components |
| 16 |
##' \item{Zt}{transpose of the sparse model matrix for the random effects} |
| 17 |
##' \item{Lambdat}{transpose of the sparse relative covariance factor} |
| 18 |
##' \item{Lind}{an integer vector of indices determining the mapping of the |
| 19 |
##' elements of the \code{theta} to the \code{"x"} slot of \code{Lambdat}} |
| 20 |
##' \item{theta}{initial values of the covariance parameters} |
| 21 |
##' \item{lower}{lower bounds on the covariance parameters} |
| 22 |
##' \item{flist}{list of grouping factors used in the random-effects terms} |
| 23 |
##' \item{cnms}{a list of column names of the random effects according to |
| 24 |
##' the grouping factors} |
| 25 |
##' @importFrom Matrix sparseMatrix rBind drop0 |
| 26 |
##' @importMethodsFrom Matrix coerce |
| 27 |
##' @family utilities |
| 28 |
##' @export |
| 29 |
mkReTrms <- function(bars, fr) { |
| 30 |
if (!length(bars)) |
| 31 |
stop("No random effects terms specified in formula") |
| 32 |
stopifnot(is.list(bars), vapply(bars, is.language, NA), |
| 33 |
inherits(fr, "data.frame")) |
| 34 |
names(bars) <- barnames(bars) |
| 35 |
term.names <- unlist(lapply(bars, function(x) paste(deparse(x),collapse=" "))) |
| 36 |
|
| 37 |
## auxiliary {named, for easier inspection}: |
| 38 |
mkBlist <- function(x) { |
| 39 |
frloc <- fr |
| 40 |
## convert grouping variables to factors as necessary |
| 41 |
## TODO: variables that are *not* in the data frame are |
| 42 |
## not converted -- these could still break, e.g. if someone |
| 43 |
## tries to use the : operator |
| 44 |
for (i in all.vars(x[[3]])) { |
| 45 |
if (!is.null(frloc[[i]])) frloc[[i]] <- factor(frloc[[i]]) |
| 46 |
} |
| 47 |
if (is.null(ff <- tryCatch(eval(substitute(factor(fac), |
| 48 |
list(fac = x[[3]])), frloc), |
| 49 |
error=function(e) NULL))) |
| 50 |
stop("couldn't evaluate grouping factor ", |
| 51 |
deparse(x[[3]])," within model frame:", |
| 52 |
" try adding grouping factor to data ", |
| 53 |
"frame explicitly if possible") |
| 54 |
if (all(is.na(ff))) |
| 55 |
stop("Invalid grouping factor specification, ", |
| 56 |
deparse(x[[3]])) |
| 57 |
nl <- length(levels(ff)) |
| 58 |
mm <- model.matrix(eval(substitute( ~ foo, list(foo = x[[2]]))), frloc) |
| 59 |
nc <- ncol(mm) |
| 60 |
nseq <- seq_len(nc) |
| 61 |
sm <- as(ff, "sparseMatrix") |
| 62 |
if (nc > 1) |
| 63 |
sm <- do.call(rBind, lapply(nseq, function(i) sm)) |
| 64 |
## hack for NA values contained in factor (FIXME: test elsewhere for consistency?) |
| 65 |
sm@x[] <- t(mm[!is.na(ff),]) |
| 66 |
## When nc > 1 switch the order of the rows of sm |
| 67 |
## so the random effects for the same level of the |
| 68 |
## grouping factor are adjacent. |
| 69 |
if (nc > 1) |
| 70 |
sm <- sm[as.vector(matrix(seq_len(nc * nl), |
| 71 |
ncol = nl, byrow = TRUE)),] |
| 72 |
list(ff = ff, sm = sm, nl = nl, cnms = colnames(mm)) |
| 73 |
} |
| 74 |
blist <- lapply(bars, mkBlist) |
| 75 |
nl <- vapply(blist, `[[`, 0L, "nl") # no. of levels per term |
| 76 |
# (in lmer jss: \ell_i) |
| 77 |
|
| 78 |
## order terms stably by decreasing number of levels in the factor |
| 79 |
if (any(diff(nl) > 0)) { |
| 80 |
ord <- rev(order(nl)) |
| 81 |
blist <- blist[ord] |
| 82 |
nl <- nl[ord] |
| 83 |
} |
| 84 |
Ztlist <- lapply(blist, "[[", "sm") |
| 85 |
Zt <- do.call(rBind, Ztlist) |
| 86 |
names(Ztlist) <- term.names |
| 87 |
q <- nrow(Zt) |
| 88 |
|
| 89 |
## Create and install Lambdat, Lind, etc. This must be done after |
| 90 |
## any potential reordering of the terms. |
| 91 |
cnms <- lapply(blist, "[[", "cnms") # list of column names of the |
| 92 |
# model matrix per term |
| 93 |
nc <- vapply(cnms, length, 0L) # no. of columns per term |
| 94 |
# (in lmer jss: p_i) |
| 95 |
nth <- as.integer((nc * (nc+1))/2) # no. of parameters per term |
| 96 |
# (in lmer jss: ??) |
| 97 |
nb <- nc * nl # no. of random effects per term |
| 98 |
# (in lmer jss: q_i) |
| 99 |
stopifnot(sum(nb) == q) |
| 100 |
boff <- cumsum(c(0L, nb)) # offsets into b |
| 101 |
thoff <- cumsum(c(0L, nth)) # offsets into theta |
| 102 |
### FIXME: should this be done with cBind and avoid the transpose |
| 103 |
### operator? In other words should Lambdat be generated directly |
| 104 |
### instead of generating Lambda first then transposing? |
| 105 |
Lambdat <- |
| 106 |
t(do.call(sparseMatrix, |
| 107 |
do.call(rBind, |
| 108 |
lapply(seq_along(blist), function(i) |
| 109 |
{ |
| 110 |
mm <- matrix(seq_len(nb[i]), ncol = nc[i], |
| 111 |
byrow = TRUE) |
| 112 |
dd <- diag(nc[i]) |
| 113 |
ltri <- lower.tri(dd, diag = TRUE) |
| 114 |
ii <- row(dd)[ltri] |
| 115 |
jj <- col(dd)[ltri] |
| 116 |
dd[cbind(ii, jj)] <- seq_along(ii) # FIXME: this line unnecessary? |
| 117 |
data.frame(i = as.vector(mm[, ii]) + boff[i], |
| 118 |
j = as.vector(mm[, jj]) + boff[i], |
| 119 |
x = as.double(rep.int(seq_along(ii), |
| 120 |
rep.int(nl[i], length(ii))) + |
| 121 |
thoff[i])) |
| 122 |
})))) |
| 123 |
thet <- numeric(sum(nth)) |
| 124 |
ll <- list(Zt=Matrix::drop0(Zt), theta=thet, Lind=as.integer(Lambdat@x), |
| 125 |
Gp=unname(c(0L, cumsum(nb)))) |
| 126 |
## lower bounds on theta elements are 0 if on diagonal, else -Inf |
| 127 |
ll$lower <- -Inf * (thet + 1) |
| 128 |
ll$lower[unique(diag(Lambdat))] <- 0 |
| 129 |
ll$theta[] <- is.finite(ll$lower) # initial values of theta are 0 off-diagonal, 1 on |
| 130 |
Lambdat@x[] <- ll$theta[ll$Lind] # initialize elements of Lambdat |
| 131 |
ll$Lambdat <- Lambdat |
| 132 |
# massage the factor list |
| 133 |
fl <- lapply(blist, "[[", "ff") |
| 134 |
# check for repeated factors |
| 135 |
fnms <- names(fl) |
| 136 |
if (length(fnms) > length(ufn <- unique(fnms))) { |
| 137 |
fl <- fl[match(ufn, fnms)] |
| 138 |
asgn <- match(fnms, ufn) |
| 139 |
} else asgn <- seq_along(fl) |
| 140 |
names(fl) <- ufn |
| 141 |
fl <- do.call(data.frame, c(fl, check.names = FALSE)) |
| 142 |
attr(fl, "assign") <- asgn |
| 143 |
ll$flist <- fl |
| 144 |
ll$cnms <- cnms |
| 145 |
ll$Ztlist <- Ztlist |
| 146 |
ll |
| 147 |
} ## {mkReTrms} |
| 148 |
|
| 149 |
##' Create an lmerResp, glmResp or nlsResp instance |
| 150 |
##' |
| 151 |
##' @title Create an lmerResp, glmResp or nlsResp instance |
| 152 |
##' @param fr a model frame |
| 153 |
##' @param REML logical scalar, value of REML for an lmerResp instance |
| 154 |
##' @param family the optional glm family (glmResp only) |
| 155 |
##' @param nlenv the nonlinear model evaluation environment (nlsResp only) |
| 156 |
##' @param nlmod the nonlinear model function (nlsResp only) |
| 157 |
##' @param ... where to look for response information if \code{fr} is missing. |
| 158 |
##' Can contain a model response, \code{y}, offset, \code{offset}, and weights, |
| 159 |
##' \code{weights}. |
| 160 |
##' @return an lmerResp or glmResp or nlsResp instance |
| 161 |
##' @family utilities |
| 162 |
##' @export |
| 163 |
mkRespMod <- function(fr, REML=NULL, family = NULL, nlenv = NULL, nlmod = NULL, ...) { |
| 164 |
|
| 165 |
if(!missing(fr)){ |
| 166 |
y <- model.response(fr) |
| 167 |
offset <- model.offset(fr) |
| 168 |
weights <- model.weights(fr) |
| 169 |
N <- n <- nrow(fr) |
| 170 |
etastart_update <- model.extract(fr, "etastart") |
| 171 |
} else { |
| 172 |
fr <- list(...) |
| 173 |
y <- fr$y |
| 174 |
N <- n <- if(is.matrix(y)) nrow(y) else length(y) |
| 175 |
offset <- fr$offset |
| 176 |
weights <- fr$weights |
| 177 |
etastart_update <- fr$etastart |
| 178 |
} |
| 179 |
|
| 180 |
|
| 181 |
## FIXME: may need to add X, or pass it somehow, if we want to use glm.fit |
| 182 |
##y <- model.response(fr) |
| 183 |
if(length(dim(y)) == 1) { |
| 184 |
## avoid problems with 1D arrays, but keep names |
| 185 |
nm <- rownames(y) |
| 186 |
dim(y) <- NULL |
| 187 |
if(!is.null(nm)) names(y) <- nm |
| 188 |
} |
| 189 |
rho <- new.env() |
| 190 |
rho$y <- if (is.null(y)) numeric(0) else y |
| 191 |
if (!is.null(REML)) rho$REML <- REML |
| 192 |
rho$etastart <- fr$etastart |
| 193 |
rho$mustart <- fr$mustart |
| 194 |
##N <- n <- nrow(fr) |
| 195 |
if (!is.null(nlenv)) { |
| 196 |
stopifnot(is.language(nlmod), |
| 197 |
is.environment(nlenv), |
| 198 |
is.numeric(val <- eval(nlmod, nlenv)), |
| 199 |
length(val) == n, |
| 200 |
## FIXME? Restriction, not present in ole' nlme(): |
| 201 |
is.matrix(gr <- attr(val, "gradient")), |
| 202 |
mode(gr) == "numeric", |
| 203 |
nrow(gr) == n, |
| 204 |
!is.null(pnames <- colnames(gr))) |
| 205 |
N <- length(gr) |
| 206 |
rho$mu <- as.vector(val) |
| 207 |
rho$sqrtXwt <- as.vector(gr) |
| 208 |
rho$gam <- |
| 209 |
unname(unlist(lapply(pnames, |
| 210 |
function(nm) get(nm, envir=nlenv)))) |
| 211 |
} |
| 212 |
if (!is.null(offset)) { |
| 213 |
if (length(offset) == 1L) offset <- rep.int(offset, N) |
| 214 |
stopifnot(length(offset) == N) |
| 215 |
rho$offset <- unname(offset) |
| 216 |
} else rho$offset <- rep.int(0, N) |
| 217 |
if (!is.null(weights)) { |
| 218 |
stopifnot(length(weights) == n, all(weights >= 0)) |
| 219 |
rho$weights <- unname(weights) |
| 220 |
} else rho$weights <- rep.int(1, n) |
| 221 |
if (is.null(family)) { |
| 222 |
if (is.null(nlenv)) return(do.call(lmerResp$new, as.list(rho))) |
| 223 |
return(do.call(nlsResp$new, |
| 224 |
c(list(nlenv=nlenv, |
| 225 |
nlmod=substitute(~foo, list(foo=nlmod)), |
| 226 |
pnames=pnames), as.list(rho)))) |
| 227 |
} |
| 228 |
stopifnot(inherits(family, "family")) |
| 229 |
## need weights for initializing evaluation |
| 230 |
rho$nobs <- n |
| 231 |
## allow trivial objects, e.g. for simulation |
| 232 |
if (length(y)>0) eval(family$initialize, rho) |
| 233 |
family$initialize <- NULL # remove clutter from str output |
| 234 |
ll <- as.list(rho) |
| 235 |
ans <- do.call("new", c(list(Class="glmResp", family=family), |
| 236 |
ll[setdiff(names(ll), c("m", "nobs", "mustart"))])) |
| 237 |
if (length(y)>0) ans$updateMu(if (!is.null(es <- etastart_update)) es else |
| 238 |
family$linkfun(get("mustart", rho))) |
| 239 |
ans |
| 240 |
} |
| 241 |
|
| 242 |
##' From the right hand side of a formula for a mixed-effects model, |
| 243 |
##' determine the pairs of expressions that are separated by the |
| 244 |
##' vertical bar operator. Also expand the slash operator in grouping |
| 245 |
##' factor expressions and expand terms with the double vertical bar operator |
| 246 |
##' into separate, independent random effect terms. |
| 247 |
##' |
| 248 |
##' @title Determine random-effects expressions from a formula |
| 249 |
##' @seealso \code{\link{formula}}, \code{\link{model.frame}}, \code{\link{model.matrix}}. |
| 250 |
##' @param term a mixed-model formula |
| 251 |
##' @return pairs of expressions that were separated by vertical bars |
| 252 |
##' @section Note: This function is called recursively on individual |
| 253 |
##' terms in the model, which is why the argument is called \code{term} and not |
| 254 |
##' a name like \code{form}, indicating a formula. |
| 255 |
##' @example |
| 256 |
##' findbars(f1 <- Reaction ~ Days + (Days|Subject)) |
| 257 |
##' ## => list( Days | Subject ) |
| 258 |
##' findbars(y ~ Days + (1|Subject) + (0+Days|Subject)) |
| 259 |
##' ## => list of length 2: list ( 1 | Subject , 0+Days|Subject) |
| 260 |
##' findbars(~ 1 + (1|batch/cask)) |
| 261 |
##' ## => list of length 2: list ( 1 | cask:batch , 1 | batch) |
| 262 |
##' identical(findbars(~ 1 + (Days || Subject)), |
| 263 |
##' findbars(~ 1 + (1|Subject) + (0+Days|Subject))) |
| 264 |
##' \dontshow{ |
| 265 |
##' stopifnot(identical(findbars(f1), |
| 266 |
##' list(expression(Days | Subject)[[1]]))) |
| 267 |
##' } |
| 268 |
##' @family utilities |
| 269 |
##' @keywords models utilities |
| 270 |
##' @export |
| 271 |
findbars <- function(term) |
| 272 |
{ |
| 273 |
## Recursive function applied to individual terms |
| 274 |
fb <- function(term) |
| 275 |
{ |
| 276 |
if (is.name(term) || !is.language(term)) return(NULL) |
| 277 |
if (term[[1]] == as.name("(")) return(fb(term[[2]])) |
| 278 |
stopifnot(is.call(term)) |
| 279 |
if (term[[1]] == as.name('|')) return(term) |
| 280 |
if (length(term) == 2) return(fb(term[[2]])) |
| 281 |
c(fb(term[[2]]), fb(term[[3]])) |
| 282 |
} |
| 283 |
## Expand any slashes in the grouping factors returned by fb |
| 284 |
expandSlash <- function(bb) |
| 285 |
{ |
| 286 |
## Create the interaction terms for nested effects |
| 287 |
makeInteraction <- function(x) |
| 288 |
{ |
| 289 |
if (length(x) < 2) return(x) |
| 290 |
trm1 <- makeInteraction(x[[1]]) |
| 291 |
trm11 <- if(is.list(trm1)) trm1[[1]] else trm1 |
| 292 |
list(substitute(foo:bar, list(foo=x[[2]], bar = trm11)), trm1) |
| 293 |
} |
| 294 |
## Return the list of '/'-separated terms |
| 295 |
slashTerms <- function(x) |
| 296 |
{ |
| 297 |
if (!("/" %in% all.names(x))) return(x) |
| 298 |
if (x[[1]] != as.name("/")) |
| 299 |
stop("unparseable formula for grouping factor") |
| 300 |
list(slashTerms(x[[2]]), slashTerms(x[[3]])) |
| 301 |
} |
| 302 |
|
| 303 |
if (!is.list(bb)) |
| 304 |
expandSlash(list(bb)) |
| 305 |
else |
| 306 |
unlist(lapply(bb, function(x) { |
| 307 |
if (length(x) > 2 && is.list(trms <- slashTerms(x[[3]]))) |
| 308 |
## lapply(unlist(...)) - unlist returns a flattened list |
| 309 |
lapply(unlist(makeInteraction(trms)), |
| 310 |
function(trm) substitute(foo|bar, list(foo = x[[2]], bar = trm))) |
| 311 |
else x |
| 312 |
})) |
| 313 |
}## {expandSlash} |
| 314 |
|
| 315 |
modterm <- expandDoubleVerts( |
| 316 |
if(is(term, "formula")) term[[length(term)]] else term) |
| 317 |
expandSlash(fb(modterm)) |
| 318 |
} |
| 319 |
|
| 320 |
##' From the right hand side of a formula for a mixed-effects model, |
| 321 |
##' expand terms with the double vertical bar operator |
| 322 |
##' into separate, independent random effect terms. |
| 323 |
##' |
| 324 |
##' @title Expand terms with \code{'||'} notation into separate \code{'|'} terms |
| 325 |
##' @seealso \code{\link{formula}}, \code{\link{model.frame}}, \code{\link{model.matrix}}. |
| 326 |
##' @param term a mixed-model formula |
| 327 |
##' @return the modified term |
| 328 |
##' @family utilities |
| 329 |
##' @keywords models utilities |
| 330 |
##' @export |
| 331 |
expandDoubleVerts <- function(term) |
| 332 |
{ |
| 333 |
expandDoubleVert <- function(term) { |
| 334 |
frml <- formula(paste0("~", deparse(term[[2]]))) |
| 335 |
## need term.labels not all.vars to capture interactions too: |
| 336 |
newtrms <- paste0("0+", attr(terms(frml), "term.labels")) |
| 337 |
if(attr(terms(frml), "intercept")!=0) |
| 338 |
newtrms <- c("1", newtrms) |
| 339 |
as.formula(paste("~(", |
| 340 |
paste(vapply(newtrms, function(trm) |
| 341 |
paste0(trm, "|", deparse(term[[3]])), ""), |
| 342 |
collapse=")+("), ")"))[[2]] |
| 343 |
} |
| 344 |
|
| 345 |
if (!is.name(term) && is.language(term)) { |
| 346 |
if (term[[1]] == as.name("(")) { |
| 347 |
term[[2]] <- expandDoubleVerts(term[[2]]) |
| 348 |
} |
| 349 |
stopifnot(is.call(term)) |
| 350 |
if (term[[1]] == as.name('||')) |
| 351 |
return( expandDoubleVert(term) ) |
| 352 |
## else : |
| 353 |
term[[2]] <- expandDoubleVerts(term[[2]]) |
| 354 |
if (length(term) != 2) { |
| 355 |
if(length(term) == 3) |
| 356 |
term[[3]] <- expandDoubleVerts(term[[3]]) |
| 357 |
} |
| 358 |
} |
| 359 |
term |
| 360 |
} |
| 361 |
|
| 362 |
|
| 363 |
|
| 364 |
##' Remove the random-effects terms from a mixed-effects formula, |
| 365 |
##' thereby producing the fixed-effects formula. |
| 366 |
##' |
| 367 |
##' @title Omit terms separated by vertical bars in a formula |
| 368 |
##' @param term the right-hand side of a mixed-model formula |
| 369 |
##' @return the fixed-effects part of the formula |
| 370 |
##' @section Note: This function is called recursively on individual |
| 371 |
##' terms in the model, which is why the argument is called \code{term} and not |
| 372 |
##' a name like \code{form}, indicating a formula. |
| 373 |
##' @examples |
| 374 |
##' nobars(Reaction ~ Days + (Days|Subject)) ## => Reaction ~ Days |
| 375 |
##' @seealso \code{\link{formula}}, \code{\link{model.frame}}, \code{\link{model.matrix}}. |
| 376 |
##' @family utilities |
| 377 |
##' @keywords models utilities |
| 378 |
##' @export |
| 379 |
nobars <- function(term) |
| 380 |
{ |
| 381 |
if (!any(c('|','||') %in% all.names(term))) return(term) |
| 382 |
if (is.call(term) && term[[1]] == as.name('|')) return(NULL) |
| 383 |
if (is.call(term) && term[[1]] == as.name('||')) return(NULL) |
| 384 |
if (length(term) == 2) { |
| 385 |
nb <- nobars(term[[2]]) |
| 386 |
if (is.null(nb)) return(NULL) |
| 387 |
term[[2]] <- nb |
| 388 |
return(term) |
| 389 |
} |
| 390 |
nb2 <- nobars(term[[2]]) |
| 391 |
nb3 <- nobars(term[[3]]) |
| 392 |
if (is.null(nb2)) return(nb3) |
| 393 |
if (is.null(nb3)) return(nb2) |
| 394 |
term[[2]] <- nb2 |
| 395 |
term[[3]] <- nb3 |
| 396 |
term |
| 397 |
} |
| 398 |
|
| 399 |
##' Substitute the '+' function for the '|' and '||' function in a mixed-model |
| 400 |
##' formula. This provides a formula suitable for the current |
| 401 |
##' model.frame function. |
| 402 |
##' |
| 403 |
##' @title "Sub[stitute] Bars" |
| 404 |
##' @param term a mixed-model formula |
| 405 |
##' @return the formula with all | and || operators replaced by + |
| 406 |
##' @section Note: This function is called recursively on individual |
| 407 |
##' terms in the model, which is why the argument is called \code{term} and not |
| 408 |
##' a name like \code{form}, indicating a formula. |
| 409 |
##' @examples |
| 410 |
##' subbars(Reaction ~ Days + (Days|Subject)) ## => Reaction ~ Days + (Days + Subject) |
| 411 |
##' @seealso \code{\link{formula}}, \code{\link{model.frame}}, \code{\link{model.matrix}}. |
| 412 |
##' @family utilities |
| 413 |
##' @keywords models utilities |
| 414 |
##' @export |
| 415 |
subbars <- function(term) |
| 416 |
{ |
| 417 |
if (is.name(term) || !is.language(term)) return(term) |
| 418 |
if (length(term) == 2) { |
| 419 |
term[[2]] <- subbars(term[[2]]) |
| 420 |
return(term) |
| 421 |
} |
| 422 |
stopifnot(length(term) >= 3) |
| 423 |
if (is.call(term) && term[[1]] == as.name('|')) |
| 424 |
term[[1]] <- as.name('+') |
| 425 |
if (is.call(term) && term[[1]] == as.name('||')) |
| 426 |
term[[1]] <- as.name('+') |
| 427 |
for (j in 2:length(term)) term[[j]] <- subbars(term[[j]]) |
| 428 |
term |
| 429 |
} |
| 430 |
|
| 431 |
##' @param bars result of findbars |
| 432 |
barnames <- function(bars) { |
| 433 |
unlist(lapply(bars, function(x) deparse(x[[3]]))) |
| 434 |
} |
| 435 |
|
| 436 |
##' Does every level of f1 occur in conjunction with exactly one level |
| 437 |
##' of f2? The function is based on converting a triplet sparse matrix |
| 438 |
##' to a compressed column-oriented form in which the nesting can be |
| 439 |
##' quickly evaluated. |
| 440 |
##' |
| 441 |
##' @title Is f1 nested within f2? |
| 442 |
##' |
| 443 |
##' @param f1 factor 1 |
| 444 |
##' @param f2 factor 2 |
| 445 |
##' |
| 446 |
##' @return TRUE if factor 1 is nested within factor 2 |
| 447 |
##' @examples |
| 448 |
##' with(Pastes, isNested(cask, batch)) ## => FALSE |
| 449 |
##' with(Pastes, isNested(sample, batch)) ## => TRUE |
| 450 |
##' @export |
| 451 |
isNested <- function(f1, f2) |
| 452 |
{ |
| 453 |
f1 <- as.factor(f1) |
| 454 |
f2 <- as.factor(f2) |
| 455 |
stopifnot(length(f1) == length(f2)) |
| 456 |
k <- length(levels(f1)) |
| 457 |
sm <- as(new("ngTMatrix", |
| 458 |
i = as.integer(f2) - 1L, |
| 459 |
j = as.integer(f1) - 1L, |
| 460 |
Dim = c(length(levels(f2)), k)), |
| 461 |
"CsparseMatrix") |
| 462 |
all(sm@p[2:(k+1L)] - sm@p[1:k] <= 1L) |
| 463 |
} |
| 464 |
|
| 465 |
subnms <- function(form, nms) { |
| 466 |
## Recursive function applied to individual terms |
| 467 |
sbnm <- function(term) |
| 468 |
{ |
| 469 |
if (is.name(term)) { |
| 470 |
if (any(term == nms)) 0 else term |
| 471 |
} else switch(length(term), |
| 472 |
term, ## 1 |
| 473 |
{ ## 2 |
| 474 |
term[[2]] <- sbnm(term[[2]]) |
| 475 |
term |
| 476 |
}, |
| 477 |
{ ## 3 |
| 478 |
term[[2]] <- sbnm(term[[2]]) |
| 479 |
term[[3]] <- sbnm(term[[3]]) |
| 480 |
term |
| 481 |
}) |
| 482 |
} |
| 483 |
sbnm(form) |
| 484 |
} |
| 485 |
|
| 486 |
## Check for a constant term (a literal 1) in an expression |
| 487 |
## |
| 488 |
## In the mixed-effects part of a nonlinear model formula, a constant |
| 489 |
## term is not meaningful because every term must be relative to a |
| 490 |
## nonlinear model parameter. This function recursively checks the |
| 491 |
## expressions in the formula for a a constant, calling stop() if |
| 492 |
## such a term is encountered. |
| 493 |
## @title Check for constant terms. |
| 494 |
## @param expr an expression |
| 495 |
## @return NULL. The function is executed for its side effect. |
| 496 |
chck1 <- function(expr) { |
| 497 |
if ((le <- length(expr)) == 1) { |
| 498 |
if (is.numeric(expr) && expr == 1) |
| 499 |
stop("1 is not meaningful in a nonlinear model formula") |
| 500 |
return() |
| 501 |
} else |
| 502 |
for (j in seq_len(le)[-1]) Recall(expr[[j]]) |
| 503 |
} |
| 504 |
|
| 505 |
## ---> ../man/nlformula.Rd --- Manipulate a nonlinear model formula |
| 506 |
##' @param mc matched call from the caller, with arguments 'formula','start',... |
| 507 |
##' @return a list with components "respMod", "frame", "X", "reTrms" |
| 508 |
nlformula <- function(mc) { |
| 509 |
start <- eval(mc$start, parent.frame(2L)) |
| 510 |
if (is.numeric(start)) start <- list(nlpars = start) |
| 511 |
stopifnot(is.numeric(nlpars <- start$nlpars), |
| 512 |
vapply(nlpars, length, 0L) == 1L, |
| 513 |
length(pnames <- names(nlpars)) == length(nlpars), |
| 514 |
length(form <- as.formula(mc$formula)) == 3L, |
| 515 |
is(nlform <- eval(form[[2]]), "formula"), |
| 516 |
pnames %in% |
| 517 |
(av <- all.vars(nlmod <- as.call(nlform[[lnl <- length(nlform)]])))) |
| 518 |
|
| 519 |
## MM{FIXME}: fortune(106) even twice in here! |
| 520 |
nlform[[lnl]] <- parse(text= paste(setdiff(all.vars(form), pnames), collapse=' + '))[[1]] |
| 521 |
nlform <- eval(nlform) |
| 522 |
environment(nlform) <- environment(form) |
| 523 |
m <- match(c("data", "subset", "weights", "na.action", "offset"), |
| 524 |
names(mc), 0) |
| 525 |
mc <- mc[c(1, m)] |
| 526 |
mc$drop.unused.levels <- TRUE |
| 527 |
mc[[1]] <- as.name("model.frame") |
| 528 |
mc$formula <- nlform |
| 529 |
fr <- eval(mc, parent.frame(2L)) |
| 530 |
n <- nrow(fr) |
| 531 |
nlenv <- list2env(fr, parent=parent.frame(2L)) |
| 532 |
lapply(pnames, function(nm) nlenv[[nm]] <- rep.int(nlpars[[nm]], n)) |
| 533 |
respMod <- mkRespMod(fr, nlenv=nlenv, nlmod=nlmod) |
| 534 |
|
| 535 |
chck1(meform <- form[[3L]]) |
| 536 |
pnameexpr <- parse(text=paste(pnames, collapse='+'))[[1]] |
| 537 |
nb <- nobars(meform) |
| 538 |
fe <- eval(substitute(~ 0 + nb + pnameexpr)) |
| 539 |
environment(fe) <- environment(form) |
| 540 |
frE <- do.call(rbind, lapply(seq_along(nlpars), function(i) fr)) # rbind s copies of the frame |
| 541 |
for (nm in pnames) # convert these variables in fr to indicators |
| 542 |
frE[[nm]] <- as.numeric(rep(nm == pnames, each = n)) |
| 543 |
X <- model.matrix(fe, frE) |
| 544 |
rownames(X) <- NULL |
| 545 |
|
| 546 |
reTrms <- mkReTrms(lapply(findbars(meform), |
| 547 |
function(expr) { |
| 548 |
expr[[2]] <- substitute(0+foo, list(foo=expr[[2]])) |
| 549 |
expr |
| 550 |
}), frE) |
| 551 |
list(respMod=respMod, frame=fr, X=X, reTrms=reTrms, pnames=pnames) |
| 552 |
} ## {nlformula} |
| 553 |
|
| 554 |
##--> ../man/mkMerMod.Rd ---Create a merMod object |
| 555 |
##' @param rho the environment of the objective function |
| 556 |
##' @param opt the value returned by the optimizer |
| 557 |
##' @param reTrms reTrms list from the calling function |
| 558 |
mkMerMod <- function(rho, opt, reTrms, fr, mc, lme4conv=NULL) { |
| 559 |
if(missing(mc)) mc <- match.call() |
| 560 |
stopifnot(is.environment(rho), |
| 561 |
is(pp <- rho$pp, "merPredD"), |
| 562 |
is(resp <- rho$resp, "lmResp"), |
| 563 |
is.list(opt), "par" %in% names(opt), |
| 564 |
c("conv","fval") %in% substr(names(opt),1,4), ## "conv[ergence]", "fval[ues]" |
| 565 |
is.list(reTrms), c("flist", "cnms", "Gp", "lower") %in% names(reTrms), |
| 566 |
length(rcl <- class(resp)) == 1) |
| 567 |
n <- nrow(pp$V) |
| 568 |
p <- ncol(pp$V) |
| 569 |
dims <- c(N=nrow(pp$X), n=n, p=p, nmp=n-p, |
| 570 |
nth=length(pp$theta), q=nrow(pp$Zt), |
| 571 |
nAGQ=rho$nAGQ, |
| 572 |
compDev=rho$compDev, |
| 573 |
## 'use scale' in the sense of whether dispersion parameter should |
| 574 |
## be reported/used (*not* whether theta should be scaled by sigma) |
| 575 |
useSc=(rcl != "glmResp" || |
| 576 |
!resp$family$family %in% c("poisson","binomial")), |
| 577 |
reTrms=length(reTrms$cnms), |
| 578 |
spFe=0L, |
| 579 |
REML=if (rcl=="lmerResp") resp$REML else 0L, |
| 580 |
GLMM=(rcl=="glmResp"), |
| 581 |
NLMM=(rcl=="nlsResp")) |
| 582 |
storage.mode(dims) <- "integer" |
| 583 |
fac <- as.numeric(rcl != "nlsResp") |
| 584 |
if (trivial.y <- (length(resp$y)==0)) { |
| 585 |
## trivial model |
| 586 |
sqrLenU <- wrss <- pwrss <- NA |
| 587 |
} else { |
| 588 |
sqrLenU <- pp$sqrL(fac) |
| 589 |
wrss <- resp$wrss() |
| 590 |
pwrss <- wrss + sqrLenU |
| 591 |
} |
| 592 |
weights <- resp$weights |
| 593 |
beta <- pp$beta(fac) |
| 594 |
#sigmaML <- pwrss/sum(weights) |
| 595 |
sigmaML <- pwrss/n |
| 596 |
if (rcl != "lmerResp") { |
| 597 |
pars <- opt$par |
| 598 |
if (length(pars) > length(pp$theta)) beta <- pars[-(seq_along(pp$theta))] |
| 599 |
} |
| 600 |
cmp <- c(ldL2=pp$ldL2(), ldRX2=pp$ldRX2(), wrss=wrss, |
| 601 |
ussq=sqrLenU, pwrss=pwrss, |
| 602 |
drsum=if (rcl=="glmResp" && !trivial.y) resp$resDev() else NA, |
| 603 |
REML=if (rcl=="lmerResp" && resp$REML != 0L && !trivial.y) |
| 604 |
opt$fval else NA, |
| 605 |
## FIXME: construct 'REML deviance' here? |
| 606 |
dev=if (rcl=="lmerResp" && resp$REML != 0L || trivial.y) NA else opt$fval, |
| 607 |
sigmaML=sqrt(unname(if (!dims["useSc"] || trivial.y) NA else sigmaML)), |
| 608 |
sigmaREML=sqrt(unname(if (rcl!="lmerResp" || trivial.y) NA else sigmaML*(dims['n']/dims['nmp']))), |
| 609 |
tolPwrss=rho$tolPwrss) |
| 610 |
## TODO: improve this hack to get something in frame slot (maybe need weights, etc...) |
| 611 |
if(missing(fr)) fr <- data.frame(resp$y) |
| 612 |
new(switch(rcl, lmerResp="lmerMod", glmResp="glmerMod", nlsResp="nlmerMod"), |
| 613 |
call=mc, frame=fr, flist=reTrms$flist, cnms=reTrms$cnms, |
| 614 |
Gp=reTrms$Gp, theta=pp$theta, beta=beta, |
| 615 |
u=if (trivial.y) rep(NA_real_,nrow(pp$Zt)) else pp$u(fac), |
| 616 |
lower=reTrms$lower, devcomp=list(cmp=cmp, dims=dims), |
| 617 |
pp=pp, resp=resp, |
| 618 |
optinfo = list (optimizer= attr(opt,"optimizer"), |
| 619 |
control = attr(opt,"control"), |
| 620 |
derivs = attr(opt,"derivs"), |
| 621 |
conv = list(opt=opt$conv, lme4=lme4conv), |
| 622 |
feval = if (is.null(opt$feval)) NA else opt$feval, |
| 623 |
warnings = attr(opt,"warnings"), val = opt$par) |
| 624 |
) |
| 625 |
}## {mkMerMod} |
| 626 |
|
| 627 |
## generic argument checking |
| 628 |
## 'type': name of calling function ("glmer", "lmer", "nlmer") |
| 629 |
## |
| 630 |
checkArgs <- function(type,...) { |
| 631 |
l... <- list(...) |
| 632 |
if (isTRUE(l...[["sparseX"]])) warning("sparseX = TRUE has no effect at present") |
| 633 |
## '...' handling up front, safe-guarding against typos ("familiy") : |
| 634 |
if(length(l... <- list(...))) { |
| 635 |
if (!is.null(l...[["family"]])) { # call glmer if family specified |
| 636 |
## we will only get here if 'family' is *not* in the arg list |
| 637 |
warning("calling lmer with family() is deprecated: please use glmer() instead") |
| 638 |
type <- "glmer" |
| 639 |
} |
| 640 |
## Check for method argument which is no longer used |
| 641 |
## (different meanings/hints depending on glmer vs lmer) |
| 642 |
if (!is.null(method <- l...[["method"]])) { |
| 643 |
msg <- paste("Argument", sQuote("method"), "is deprecated.") |
| 644 |
if (type=="lmer") msg <- paste(msg,"Use the REML argument to specify ML or REML estimation.") |
| 645 |
if (type=="glmer") msg <- paste(msg,"Use the nAGQ argument to specify Laplace (nAGQ=1) or adaptive", |
| 646 |
"Gauss-Hermite quadrature (nAGQ>1). PQL is no longer available.") |
| 647 |
warning(msg) |
| 648 |
l... <- l...[names(l...) != "method"] |
| 649 |
} |
| 650 |
if(length(l...)) { |
| 651 |
warning("extra argument(s) ", |
| 652 |
paste(sQuote(names(l...)), collapse=", "), |
| 653 |
" disregarded") |
| 654 |
} |
| 655 |
} |
| 656 |
} |
| 657 |
|
| 658 |
## check formula and data: return an environment suitable for evaluating |
| 659 |
## the formula. |
| 660 |
## (1) if data is specified, return it |
| 661 |
## (2) otherwise, if formula has an environment, use it |
| 662 |
## (3) otherwise [e.g. if formula was passed as a string], try to use parent.frame(2) |
| 663 |
|
| 664 |
## if #3 is true *and* the user is doing something tricky with nested functions, |
| 665 |
## this may fail ... |
| 666 |
|
| 667 |
checkFormulaData <- function(formula,data,checkLHS=TRUE,debug=FALSE) { |
| 668 |
dataName <- deparse(substitute(data)) |
| 669 |
missingData <- inherits(tryCatch(eval(data), error=function(e)e), "error") |
| 670 |
## data not found (this *should* only happen with garbage input, |
| 671 |
## OR when strings used as formulae -> drop1/update/etc.) |
| 672 |
## |
| 673 |
## alternate attempt (fails) |
| 674 |
## |
| 675 |
## ff <- sys.frames() |
| 676 |
## ex <- substitute(data) |
| 677 |
## ii <- rev(seq_along(ff)) |
| 678 |
## for(i in ii) { |
| 679 |
## ex <- eval(substitute(substitute(x, env=sys.frames()[[n]]), |
| 680 |
## env = list(x = ex, n=i))) |
| 681 |
## } |
| 682 |
## origName <- deparse(ex) |
| 683 |
## missingData <- !exists(origName) |
| 684 |
## (!dataName=="NULL" && !exists(dataName)) |
| 685 |
if (missingData) { |
| 686 |
varex <- function(v,env) exists(v,envir=env,inherits=FALSE) |
| 687 |
allvars <- all.vars(as.formula(formula)) |
| 688 |
allvarex <- function(vvec=allvars,...) { all(sapply(vvec,varex,...)) } |
| 689 |
if (allvarex(env=(ee <- environment(formula)))) { |
| 690 |
stop("'data' not found, but variables found in environment of formula: ", |
| 691 |
"try specifying 'formula' as a formula rather ", |
| 692 |
"than a string in the original model") |
| 693 |
} else stop("'data' not found, and some variables missing from formula environment") |
| 694 |
} else { |
| 695 |
if (is.null(data)) { |
| 696 |
if (!is.null(ee <- environment(formula))) { |
| 697 |
## use environment of formula |
| 698 |
denv <- ee |
| 699 |
} else { |
| 700 |
## e.g. no environment, e.g. because formula is a character vector |
| 701 |
## parent.frame(2L) works because [g]lFormula (our calling environment) |
| 702 |
## has been called within [g]lmer with env=parent.frame(1L) |
| 703 |
## If you call checkFormulaData in some other bizarre way such that |
| 704 |
## parent.frame(2L) is *not* OK, you deserve what you get |
| 705 |
## calling checkFormulaData directly from the global |
| 706 |
## environment should be OK, since trying to go up beyond the global |
| 707 |
## environment keeps bringing you back to the global environment ... |
| 708 |
denv <- parent.frame(2L) |
| 709 |
} |
| 710 |
} else { |
| 711 |
## data specified |
| 712 |
denv <- list2env(data) |
| 713 |
} |
| 714 |
} |
| 715 |
## FIXME: set enclosing environment of denv to environment(formula), or parent.frame(2L) ? |
| 716 |
if (debug) { |
| 717 |
cat("Debugging parent frames in checkFormulaData:\n") |
| 718 |
## find global environment -- could do this with sys.nframe() ? |
| 719 |
glEnv <- 1 |
| 720 |
while (!identical(parent.frame(glEnv),.GlobalEnv)) { |
| 721 |
glEnv <- glEnv+1 |
| 722 |
} |
| 723 |
## where are vars? |
| 724 |
for (i in 1:glEnv) { |
| 725 |
OK <- allvarex(env=parent.frame(i)) |
| 726 |
cat("vars exist in parent frame ",i) |
| 727 |
if (i==glEnv) cat(" (global)") |
| 728 |
cat(" ",OK,"\n") |
| 729 |
} |
| 730 |
cat("vars exist in env of formula ",allvarex(env=denv),"\n") |
| 731 |
} ## if (debug) |
| 732 |
|
| 733 |
stopifnot(!checkLHS || length(as.formula(formula,env=denv)) == 3) ## check for two-sided formula |
| 734 |
return(denv) |
| 735 |
} |
| 736 |
|
| 737 |
## checkFormulaData <- function(formula,data) { |
| 738 |
## ee <- environment(formula) |
| 739 |
## if (is.null(ee)) { |
| 740 |
## ee <- parent.frame(2) |
| 741 |
## } |
| 742 |
## if (missing(data)) data <- ee |
| 743 |
## stopifnot(length(as.formula(formula,env=as.environment(data))) == 3) |
| 744 |
## return(data) |
| 745 |
## } |
| 746 |
|
| 747 |
|
| 748 |
##' Not exported; for tests (and examples) that can be slow; |
| 749 |
##' Use if(lme4:::testLevel() >= 1.) ..... see ../README.md |
| 750 |
testLevel <- function() |
| 751 |
if(nzchar(s <- Sys.getenv("LME4_TEST_LEVEL")) && |
| 752 |
is.finite(s <- as.numeric(s))) s else 1 |
| 753 |
|
| 754 |
##' General conditional variance-covariance matrix |
| 755 |
##' |
| 756 |
##' Experimental function for estimating the variance-covariance |
| 757 |
##' matrix of the random effects, conditional on the observed data |
| 758 |
##' and at the (RE)ML estimate of the fixed effects and covariance |
| 759 |
##' parameters. Applicable for any Lambda matrix, but slower than |
| 760 |
##' other block-by-block methods. |
| 761 |
##' Not exported. |
| 762 |
##' |
| 763 |
##' TODO: |
| 764 |
##' (1) Write up quite note on theory (e.g. Laplace approximation). |
| 765 |
##' (2) Figure out how to convert between full q-by-q matrix, and |
| 766 |
##' the format currently in the postVar attributes of the |
| 767 |
##' elements of the output of ranef. |
| 768 |
##' (3) Test. |
| 769 |
##' (4) Do we need to think carefully about the differences |
| 770 |
##' between REML and ML, beyond just multiplying by a different |
| 771 |
##' sigma^2 estimate? |
| 772 |
##' |
| 773 |
##' @param object \code{merMod} object |
| 774 |
##' @return Sparse covariance matrix |
| 775 |
condVar <- function(object) { |
| 776 |
s2 <- sigma(object)^2 |
| 777 |
Lamt <- getME(object,"Lambdat") |
| 778 |
L <- getME(object,"L") |
| 779 |
|
| 780 |
## never do it this way! fortune("SOOOO") |
| 781 |
#V <- solve(L, system = "A") |
| 782 |
#V <- chol2inv(L) |
| 783 |
#s2*crossprod(Lamt, V) %*% Lamt |
| 784 |
|
| 785 |
LL <- solve(L, Lamt, system = "A") |
| 786 |
s2 * crossprod(Lamt, LL) |
| 787 |
} |
| 788 |
|
| 789 |
mkMinimalData <- function(formula) { |
| 790 |
vars <- all.vars(formula) |
| 791 |
nVars <- length(vars) |
| 792 |
matr <- matrix(0, 2, nVars) |
| 793 |
data <- as.data.frame(matr) |
| 794 |
setNames(data, vars) |
| 795 |
} |
| 796 |
|
| 797 |
##' Make template for mixed model parameters |
| 798 |
mkParsTemplate <- function(formula, data){ |
| 799 |
if(missing(data)) data <- mkMinimalData(formula) |
| 800 |
mfRanef <- model.frame( subbars(formula), data) |
| 801 |
mmFixef <- model.matrix(nobars(formula) , data) |
| 802 |
reTrms <- mkReTrms(findbars(formula), mfRanef) |
| 803 |
cnms <- reTrms$cnms |
| 804 |
thetaNamesList <- mapply(mkPfun(), names(cnms), cnms) |
| 805 |
thetaNames <- unlist(thetaNamesList) |
| 806 |
betaNames <- colnames(mmFixef) |
| 807 |
list(beta = setNames(numeric(length( betaNames)), betaNames), |
| 808 |
theta = setNames(reTrms$theta, thetaNames), |
| 809 |
sigma = 1) |
| 810 |
} |
| 811 |
|
| 812 |
##' Make template for mixed model data |
| 813 |
##' |
| 814 |
##' Useful for simulating balanced designs and for |
| 815 |
##' getting started on unbalanced simulations |
| 816 |
##' |
| 817 |
##' @param formula formula |
| 818 |
##' @param data data -- not necessary |
| 819 |
##' @param nGrps number of groups per grouping factor |
| 820 |
##' @param rfunc function for generating covariate data |
| 821 |
##' @param ... additional parameters for rfunc |
| 822 |
mkDataTemplate <- function(formula, data, |
| 823 |
nGrps = 2, nPerGrp = 1, |
| 824 |
rfunc = NULL, ...){ |
| 825 |
if(missing(data)) data <- mkMinimalData(formula) |
| 826 |
grpFacNames <- unique(barnames(findbars(formula))) |
| 827 |
varNames <- all.vars(formula) |
| 828 |
covariateNames <- setdiff(varNames, grpFacNames) |
| 829 |
nGrpFac <- length(grpFacNames) |
| 830 |
nCov <- length(covariateNames) |
| 831 |
grpFac <- gl(nGrps, nPerGrp) |
| 832 |
grpDat <- expand.grid(replicate(nGrpFac, grpFac, simplify = FALSE)) |
| 833 |
colnames(grpDat) <- grpFacNames |
| 834 |
nObs <- nrow(grpDat) |
| 835 |
if(is.null(rfunc)) rfunc <- function(n, ...) rep(0, n) |
| 836 |
params <- c(list(nObs), list(...)) |
| 837 |
covDat <- as.data.frame(replicate(nCov, do.call(rfunc, params), |
| 838 |
simplify = FALSE)) |
| 839 |
colnames(covDat) <- covariateNames |
| 840 |
cbind(grpDat, covDat) |
| 841 |
} |