Extract random-effect modes

Usage

# S3 method for class 'frmtmb_fit'
ranef(
  object,
  summary = TRUE,
  robust = FALSE,
  probs = c(0.025, 0.975),
  pars = NULL,
  groups = NULL,
  ...,
  condVar = FALSE
)

Arguments

object: A frmtmb_fit.
summary, robust, probs: brms's arguments, in brms's positions so that a positional brms call asks the same question. brms answers summary = FALSE with the posterior draws and robust = TRUE with their median and MAD, and a maximum-likelihood fit has no draws, so both are refused by name with the reason. The default of each is accepted and changes nothing.
pars: Optional coefficient names to keep, as brms's: "x" keeps the x column of every group, a dpar's included (sigma_x). A group left with no coefficient is dropped.
groups: Optional grouping factor names to keep. A name the model does not have keeps nothing.
...: Refused: an argument the method does not have is an error naming it, rather than silently changing nothing.
condVar: If TRUE, attach the conditional SDs of the modes (from the Laplace posterior) as a "condSD" attribute on each matrix, in matching layout.

Value

A named list of levels-by-coefficients matrices, one per random-effect term, KEYED BY THE GROUPING FACTOR as brms and lme4 key it (so ranef(fit)$g and coef(fit)$g name the same group). Each matrix carries its block label in a "term" attribute, which is also the grp column of as.data.frame(). That long form (with a condsd column when condVar = TRUE was used) is what broom.mixed-style code reads.

Several terms on ONE grouping factor give several entries under one name, and $ and [[ then take the block label instead: ranef(fit)[["chi: 1 | id"]]. The bare factor name is refused there, and names the labels, rather than returning the first block. Positional indexing reaches every block either way.

Two ordinary spellings put more than one block on one factor, so this is not a nonlinear-model corner: two bars written out on the same factor, (1 | g) + (0 + x | g); and a random effect on more than one distributional or nonlinear parameter, such as bf(y ~ x + (1 | g), sigma ~ (1 | g)) (1 | g and sigma: 1 | g) or (1 | id) on three nonlinear parameters. A slope (1 + x | g) is one block, and so is an uncorrelated slope (1 + x || g), as in brms; each is addressed by the factor name.

Examples

set.seed(1)
dd <- data.frame(x = rnorm(100), g = factor(rep(1:10, 10)))
dd$y <- rnorm(100, 1 + 0.5 * dd$x + rnorm(10, 0, 0.8)[dd$g], 1)
fit <- frm(bf(y ~ x + (1 | g)) + gaussian(), data = dd)

# one matrix per random-effect term, levels by coefficients
ranef(fit)
#> $g   (1 | g)
#>     Intercept
#> 1  -0.7929107
#> 2   0.1938151
#> 3  -0.6968770
#> 4  -0.3665206
#> 5  -1.2649301
#> 6   1.0458866
#> 7   0.8996913
#> 8   0.2424443
#> 9  -0.2011918
#> 10  0.9405934
#> 
ranef(fit)$g[1:3, ]                 # keyed by the grouping factor
#>          1          2          3 
#> -0.7929107  0.1938151 -0.6968770 
attr(ranef(fit)$g, "term")          # the block it came from
#> [1] "1 | g"
ranef(fit)[["1 | g"]][1:3, ]        # or by that label
#>          1          2          3 
#> -0.7929107  0.1938151 -0.6968770 

# condVar adds the conditional SDs a caterpillar plot needs
re <- as.data.frame(ranef(fit, condVar = TRUE))
head(re)
#>     grp      term level    condval    condsd
#> 1 1 | g Intercept     1 -0.7929107 0.3795349
#> 2 1 | g Intercept     2  0.1938151 0.3736803
#> 3 1 | g Intercept     3 -0.6968770 0.3773162
#> 4 1 | g Intercept     4 -0.3665206 0.3788816
#> 5 1 | g Intercept     5 -1.2649301 0.3829436
#> 6 1 | g Intercept     6  1.0458866 0.3798967
with(re[order(re$condval), ],
     plot(condval, seq_along(condval), pch = 16,
          xlim = range(condval - 2 * condsd, condval + 2 * condsd),
          xlab = "conditional mode", ylab = "group"))