merTools
A package for getting the most of our multilevel models in R
by Jared E. Knowles and Carl Frederick
Working with generalized linear mixed models (GLMM) and linear mixed
models (LMM) has become increasingly easy with advances in the lme4
package. As we have found ourselves using these models more and more
within our work, we, the authors, have developed a set of tools for
simplifying and speeding up common tasks for interacting with merMod
objects from lme4. This package provides those tools.
Installation
# development version
library(devtools)
install_github("jknowles/merTools")
# CRAN version
install.packages("merTools")Recent Updates
merTools 0.4.1
New Features
- Standard errors reported by
merModListfunctions now apply the Rubin correction for multiple imputation
Bug fixes
- Contribution by Alex Whitworth (@alexWhitworth) adding error checking to plotting functions
merTools 0.4.0
New Features
- Added vignette on using multilevel models with multiply imputed data
- Added
fixefandranefgenerics formerModListobjects - Added
fastdispgeneric formerModList - Added
summarygeneric formerModList - Added
printgeneric formerModList - Documented all generics for
merModListincluding examples and a new imputation vignette - Added
modelInfogeneric formerModobjects that provides simple summary stats about a whole model
Bug Fixes
- Fix bug that returned NaN for
std.errorof a multiply imputedmerModListwhen callingmodelRandEffStats - Fixed bug in
REimpactwhere some column names innewdatawould prevent the prediction intervals from being computed correctly. Users will now be warned. - Fixed bug in
wigglewhere documentation incorrectly stated the arguments to the function and the documentation did not describe function correctly
See NEWS.md for more details.
Shiny App and Demo
The easiest way to demo the features of this application is to use the bundled Shiny application which launches a number of the metrics here to aide in exploring the model. To do this:
library(merTools)
m1 <- lmer(y ~ service + lectage + studage + (1|d) + (1|s), data=InstEval)
shinyMer(m1, simData = InstEval[1:100, ]) # just try the first 100 rows of data
On the first tab, the function presents the prediction intervals for the
data selected by user which are calculated using the predictInterval
function within the package. This function calculates prediction
intervals quickly by sampling from the simulated distribution of the
fixed effect and random effect terms and combining these simulated
estimates to produce a distribution of predictions for each observation.
This allows prediction intervals to be generated from very large models
where the use of bootMer would not be feasible computationally.
On the next tab the distribution of the fixed effect and group-level
effects is depicted on confidence interval plots. These are useful for
diagnostics and provide a way to inspect the relative magnitudes of
various parameters. This tab makes use of four related functions in
merTools: FEsim, plotFEsim, REsim and plotREsim which are
available to be used on their own as well.
On the third tab are some convenient ways to show the influence or
magnitude of effects by leveraging the power of predictInterval. For
each case, up to 12, in the selected data type, the user can view the
impact of changing either one of the fixed effect or one of the grouping
level terms. Using the REimpact function, each case is simulated with
the model’s prediction if all else was held equal, but the observation
was moved through the distribution of the fixed effect or the random
effect term. This is plotted on the scale of the dependent variable,
which allows the user to compare the magnitude of effects across
variables, and also between models on the same data.
Predicting
Standard prediction looks like so.
predict(m1, newdata = InstEval[1:10, ])
#> 1 2 3 4 5 6 7 8
#> 3.146336 3.165211 3.398499 3.114248 3.320686 3.252670 4.180896 3.845218
#> 9 10
#> 3.779336 3.331012With predictInterval we obtain predictions that are more like the
standard objects produced by lm and
glm:
#predictInterval(m1, newdata = InstEval[1:10, ]) # all other parameters are optional
predictInterval(m1, newdata = InstEval[1:10, ], n.sims = 500, level = 0.9,
stat = 'median')
#> fit upr lwr
#> 1 3.125394 4.979246 1.1166373
#> 2 3.304650 5.192903 1.2958078
#> 3 3.421564 5.513007 1.3941391
#> 4 3.098004 5.018878 0.8932288
#> 5 3.253312 5.338664 1.1236043
#> 6 3.199142 5.166880 1.1563780
#> 7 4.067185 6.313856 1.9312797
#> 8 3.766062 5.746171 1.7210402
#> 9 3.744515 5.681148 1.7479590
#> 10 3.325182 5.357726 1.1783253Note that predictInterval is slower because it is computing
simulations. It can also return all of the simulated yhat values as an
attribute to the predict object itself.
predictInterval uses the sim function from the arm package heavily
to draw the distributions of the parameters of the model. It then
combines these simulated values to create a distribution of the yhat
for each observation.
Inspecting the Prediction Components
We can also explore the components of the prediction interval by asking
predictInterval to return specific components of the prediction
interval.
predictInterval(m1, newdata = InstEval[1:10, ], n.sims = 200, level = 0.9,
stat = 'median', which = "all")
#> effect fit upr lwr obs
#> 1 combined 3.05142664 4.893535 1.1453327 1
#> 2 combined 3.26515473 5.228517 0.9245461 2
#> 3 combined 3.39424116 5.445855 1.3459129 3
#> 4 combined 2.95792564 5.151298 1.2972070 4
#> 5 combined 3.28378686 5.334808 1.1797896 5
#> 6 combined 3.33398777 5.467897 1.3173296 6
#> 7 combined 4.31607723 6.236707 2.3684152 7
#> 8 combined 3.78177816 5.915230 1.9452920 8
#> 9 combined 3.78801812 6.137100 1.8042376 9
#> 10 combined 3.40311223 5.472319 1.3328570 10
#> 11 s 0.33120450 2.635771 -1.8232921 1
#> 12 s 0.07722743 2.135277 -1.7939259 2
#> 13 s 0.17659021 2.199019 -1.9514854 3
#> 14 s 0.18544864 1.866820 -1.6960335 4
#> 15 s -0.25029379 1.753376 -2.0009388 5
#> 16 s 0.07575502 1.821340 -1.8900120 6
#> 17 s 0.37605480 2.665245 -1.5634669 7
#> 18 s 0.19175873 2.250059 -1.6432148 8
#> 19 s 0.27428472 2.377856 -1.4729972 9
#> 20 s 0.30033064 1.989653 -1.7652454 10
#> 21 d -0.13550930 1.893747 -2.2727313 1
#> 22 d -0.21943931 2.122796 -2.1435895 2
#> 23 d 0.02686489 1.896004 -1.9601462 3
#> 24 d -0.30799468 1.730694 -2.0044624 4
#> 25 d 0.02167456 1.907354 -1.9105378 5
#> 26 d -0.03063146 2.006059 -1.8768102 6
#> 27 d 0.76043305 2.710346 -1.3152748 7
#> 28 d -0.02853018 2.228498 -1.8649234 8
#> 29 d 0.03933386 1.955542 -1.7880232 9
#> 30 d -0.41025679 2.022148 -1.9079259 10
#> 31 fixed 3.21823828 5.004409 0.9239508 1
#> 32 fixed 3.17739019 5.092532 1.6046582 2
#> 33 fixed 3.30796530 5.251162 1.2900951 3
#> 34 fixed 3.06731437 4.756057 1.2541274 4
#> 35 fixed 3.33175950 5.231223 1.1547966 5
#> 36 fixed 3.45077676 5.089393 1.1347821 6
#> 37 fixed 3.06641488 4.910878 1.2608331 7
#> 38 fixed 3.24223202 5.085719 1.6450764 8
#> 39 fixed 3.47941329 5.623999 1.4291720 9
#> 40 fixed 3.14623403 4.992673 1.2811486 10This can lead to some useful plotting:
library(ggplot2)
plotdf <- predictInterval(m1, newdata = InstEval[1:10, ], n.sims = 2000,
level = 0.9, stat = 'median', which = "all",
include.resid.var = FALSE)
plotdfb <- predictInterval(m1, newdata = InstEval[1:10, ], n.sims = 2000,
level = 0.9, stat = 'median', which = "all",
include.resid.var = TRUE)
plotdf <- bind_rows(plotdf, plotdfb, .id = "residVar")
plotdf$residVar <- ifelse(plotdf$residVar == 1, "No Model Variance",
"Model Variance")
ggplot(plotdf, aes(x = obs, y = fit, ymin = lwr, ymax = upr)) +
geom_pointrange() +
geom_hline(yintercept = 0, color = I("red"), size = 1.1) +
scale_x_continuous(breaks = c(1, 10)) +
facet_grid(residVar~effect) + theme_bw()
We can also investigate the makeup of the prediction for each observation.
ggplot(plotdf[plotdf$obs < 6,],
aes(x = effect, y = fit, ymin = lwr, ymax = upr)) +
geom_pointrange() +
geom_hline(yintercept = 0, color = I("red"), size = 1.1) +
facet_grid(residVar~obs) + theme_bw()
Plotting
merTools also provides functionality for inspecting merMod objects
visually. The easiest are getting the posterior distributions of both
fixed and random effect parameters.
feSims <- FEsim(m1, n.sims = 100)
head(feSims)
#> term mean median sd
#> 1 (Intercept) 3.22306436 3.22345526 0.01995396
#> 2 service1 -0.06979601 -0.07113286 0.01297003
#> 3 lectage.L -0.18769609 -0.18658318 0.01621428
#> 4 lectage.Q 0.02251329 0.02154975 0.01222164
#> 5 lectage.C -0.02182935 -0.02134305 0.01183856
#> 6 lectage^4 -0.01800829 -0.01789510 0.01300245And we can also plot this:
plotFEsim(FEsim(m1, n.sims = 100), level = 0.9, stat = 'median', intercept = FALSE)
We can also quickly make caterpillar plots for the random-effect terms:
reSims <- REsim(m1, n.sims = 100)
head(reSims)
#> groupFctr groupID term mean median sd
#> 1 s 1 (Intercept) 0.17849937 0.19083849 0.2789109
#> 2 s 2 (Intercept) -0.04530464 -0.03605309 0.3276079
#> 3 s 3 (Intercept) 0.31172494 0.30584665 0.2902461
#> 4 s 4 (Intercept) 0.23045733 0.21928685 0.2728494
#> 5 s 5 (Intercept) 0.03069242 0.04029338 0.3251431
#> 6 s 6 (Intercept) 0.08975814 0.06813835 0.2409531plotREsim(REsim(m1, n.sims = 100), stat = 'median', sd = TRUE)
Note that plotREsim highlights group levels that have a simulated
distribution that does not overlap 0 – these appear darker. The lighter
bars represent grouping levels that are not distinguishable from 0 in
the data.
Sometimes the random effects can be hard to interpret and not all of
them are meaningfully different from zero. To help with this merTools
provides the expectedRank function, which provides the percentile
ranks for the observed groups in the random effect distribution taking
into account both the magnitude and uncertainty of the estimated effect
for each group.
ranks <- expectedRank(m1, groupFctr = "d")
head(ranks)
#> groupFctr groupLevel term estimate std.error ER pctER
#> 2 d 1 _Intercept 0.3944916 0.08665149 835.3004 74
#> 3 d 6 _Intercept -0.4428947 0.03901987 239.5364 21
#> 4 d 7 _Intercept 0.6562683 0.03717200 997.3570 88
#> 5 d 8 _Intercept -0.6430679 0.02210017 138.3445 12
#> 6 d 12 _Intercept 0.1902942 0.04024063 702.3412 62
#> 7 d 13 _Intercept 0.2497467 0.03216254 750.0176 66A nice features expectedRank is that you can return the expected rank
for all factors simultaneously and use them:
ranks <- expectedRank(m1)
head(ranks)
#> groupFctr groupLevel term estimate std.error ER pctER
#> 2 s 1 _Intercept 0.16732725 0.08165631 1931.569 65
#> 3 s 2 _Intercept -0.04409515 0.09234206 1368.161 46
#> 4 s 3 _Intercept 0.30382125 0.05204068 2309.940 78
#> 5 s 4 _Intercept 0.24756083 0.06641676 2151.827 72
#> 6 s 5 _Intercept 0.05232309 0.08174095 1627.693 55
#> 7 s 6 _Intercept 0.10191622 0.06648371 1772.548 60
ggplot(ranks, aes(x = term, y = estimate)) +
geom_violin(fill = "gray50") + facet_wrap(~groupFctr) +
theme_bw()
Effect Simulation
It can still be difficult to interpret the results of LMM and GLMM
models, especially the relative influence of varying parameters on the
predicted outcome. This is where the REimpact and the wiggle
functions in merTools can be handy.
impSim <- REimpact(m1, InstEval[7, ], groupFctr = "d", breaks = 5,
n.sims = 300, level = 0.9)
#> Warning: executing %dopar% sequentially: no parallel backend registered
impSim
#> case bin AvgFit AvgFitSE nobs
#> 1 1 1 2.792772 2.842321e-04 193
#> 2 1 2 3.263785 6.273483e-05 240
#> 3 1 3 3.557189 5.018429e-05 254
#> 4 1 4 3.845991 6.175618e-05 265
#> 5 1 5 4.224282 1.855857e-04 176The result of REimpact shows the change in the yhat as the case we
supplied to newdata is moved from the first to the fifth quintile in
terms of the magnitude of the group factor coefficient. We can see here
that the individual professor effect has a strong impact on the outcome
variable. This can be shown graphically as
well:
ggplot(impSim, aes(x = factor(bin), y = AvgFit, ymin = AvgFit - 1.96*AvgFitSE,
ymax = AvgFit + 1.96*AvgFitSE)) +
geom_pointrange() + theme_bw() + labs(x = "Bin of `d` term", y = "Predicted Fit")
Here the standard error is a bit different – it is the weighted standard
error of the mean effect within the bin. It does not take into account
the variability within the effects of each observation in the bin –
accounting for this variation will be a future addition to merTools.
Explore Substantive Impacts
Another feature of merTools is the ability to easily generate
hypothetical scenarios to explore the predicted outcomes of a merMod
object and understand what the model is saying in terms of the outcome
variable.
Let’s take the case where we want to explore the impact of a model with an interaction term between a category and a continuous predictor. First, we fit a model with interactions:
data(VerbAgg)
fmVA <- glmer(r2 ~ (Anger + Gender + btype + situ)^2 +
(1|id) + (1|item), family = binomial,
data = VerbAgg)
#> Warning in checkConv(attr(opt, "derivs"), opt$par, ctrl = control
#> $checkConv, : Model failed to converge with max|grad| = 0.0505464 (tol =
#> 0.001, component 1)Now we prep the data using the draw function in merTools. Here we
draw the average observation from the model frame. We then wiggle the
data by expanding the dataframe to include the same observation repeated
but with different values of the variable specified by the var
parameter. Here, we expand the dataset to all values of btype, situ,
and Anger subsequently.
# Select the average case
newData <- draw(fmVA, type = "average")
newData <- wiggle(newData, varlist = "btype",
valueslist = list(unique(VerbAgg$btype)))
newData <- wiggle(newData, var = "situ",
valueslist = list(unique(VerbAgg$situ)))
newData <- wiggle(newData, var = "Anger",
valueslist = list(unique(VerbAgg$Anger)))
head(newData, 10)
#> r2 Anger Gender btype situ id item
#> 1 N 20 F curse other 149 S3WantCurse
#> 2 N 20 F scold other 149 S3WantCurse
#> 3 N 20 F shout other 149 S3WantCurse
#> 4 N 20 F curse self 149 S3WantCurse
#> 5 N 20 F scold self 149 S3WantCurse
#> 6 N 20 F shout self 149 S3WantCurse
#> 7 N 11 F curse other 149 S3WantCurse
#> 8 N 11 F scold other 149 S3WantCurse
#> 9 N 11 F shout other 149 S3WantCurse
#> 10 N 11 F curse self 149 S3WantCurseThe next step is familiar – we simply pass this new dataset to
predictInterval in order to generate predictions for these
counterfactuals. Then we plot the predicted values against the
continuous variable, Anger, and facet and group on the two categorical
variables situ and btype
respectively.
plotdf <- predictInterval(fmVA, newdata = newData, type = "probability",
stat = "median", n.sims = 1000)
plotdf <- cbind(plotdf, newData)
ggplot(plotdf, aes(y = fit, x = Anger, color = btype, group = btype)) +
geom_point() + geom_smooth(aes(color = btype), method = "lm") +
facet_wrap(~situ) + theme_bw() +
labs(y = "Predicted Probability")