Debian Codegraph @

tests/inputs/utilities.R

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