Create list of structures needed for models with random effects

From the result of findbars applied to a model formula and and the evaluation frame, create the model matrix, etc. associated with random-effects terms. See the description of the returned value for a detailed list.

mkReTrms(
  bars,
  fr,
  drop.unused.levels = TRUE,
  reorder.terms = TRUE,
  reorder.vars = FALSE,
  calc.lambdat = TRUE,
  sparse = NULL
)

Arguments

bars: a list of parsed random-effects terms
fr: a model frame in which to evaluate these terms
drop.unused.levels: (logical) drop unused factor levels?
reorder.terms: arrange random effects terms in decreasing order of number of groups (factor levels)?
reorder.vars: arrange columns of individual random effects terms in alphabetical order?
calc.lambdat: (logical) compute Lambdat and Lind components? (At present these components are needed for lme4 machinery but not for glmmTMB, and may be large in some cases; see Bates et al. 2015
sparse: (logical) set up sparse model matrices?

Value

a list with components

Zt: transpose of the sparse model matrix for the random effects
Ztlist: list of components of the transpose of the random-effects model matrix, separated by random-effects term
Lambdat: transpose of the sparse relative covariance factor
Lind: an integer vector of indices determining the mapping of the elements of the theta to the "x" slot of Lambdat
theta: initial values of the covariance parameters
lower: lower bounds on the covariance parameters
flist: list of grouping factors used in the random-effects terms
cnms: a list of column names of the random effects according to the grouping factors
Gp: a vector indexing the association of elements of the conditional mode vector with random-effect terms; if nb is the vector of numbers of conditional modes per term (i.e. number of groups times number of effects per group), Gp is c(0,cumsum(nb)) (and conversely nb is diff(Gp))
nl: names of the terms (in the same order as Zt, i.e. reflecting the reorder.terms argument)
ord: an integer vector giving the relationship between the order of the terms in the formula and the terms in the final object (which are ordered by the number of levels in the grouping variable, if reorder.terms is TRUE)

Details

Lambdat, Lind, theta, lower are likely to be useful only for lme4; the other terms can be generally useful for constructing mixed-effect models

References

Bates D, Mächler M, Bolker B, Walker S (2015). “Fitting Linear Mixed-Effects Models Using lme4.” Journal of Statistical Software, 67(1), 1–48. doi:10.18637/jss.v067.i01 . )

Examples

## (silly/impractical formula, for illustration only)
form <- mpg ~ 1 + (1|gear) + (factor(cyl)|gear) + (1 + hp | carb)
fr <- model.frame(subbars(form), data = mtcars)
rterms <- mkReTrms(findbars(form), fr)
names(rterms)
#>  [1] "Zt"      "theta"   "Lind"    "Gp"      "lower"   "Lambdat" "flist"  
#>  [8] "cnms"    "Ztlist"  "nl"      "ord"    
## block sizes (latent variables per block) of each term
(nperblock <- lengths(rterms$cnms))
#> carb gear gear 
#>    2    3    1 
## latent variables per term
(nperterm <- diff(rterms$Gp))
#> [1] 12  9  3
with(rterms, identical(unname(nl*nperblock), nperterm))
#> [1] TRUE
## illustrate reordering of terms
dd <- expand.grid(a = 1:7, b = 1:3, c = 1:5, d = 1:9)
dd$y <- 1
form2 <- y ~ 1 + (1|a) + (1|b) + (1|c) + (1|d)
rterms2 <- mkReTrms(findbars(form2), dd, reorder.terms = TRUE)
## reorder elements into original formula order
with(rterms2, cnms[order(ord)])
#> $a
#> [1] "(Intercept)"
#> 
#> $b
#> [1] "(Intercept)"
#> 
#> $c
#> [1] "(Intercept)"
#> 
#> $d
#> [1] "(Intercept)"
#> 
## reorder splitForm output to match mkReTrms components
ss <- splitForm(form2)
ss$reTrmFormulas[rterms2$ord]
#> [[1]]
#> 1 | d
#> 
#> [[2]]
#> 1 | a
#> 
#> [[3]]
#> 1 | c
#> 
#> [[4]]
#> 1 | b
#>