betamertree: Beta Mixed-Effects Regression Trees

In glmertree: Generalized Linear Mixed Model Trees

Beta Mixed-Effects Regression Trees

Description

Model-based recursive partitioning based on mixed-effects beta regression.

Usage

betamertree(formula, data, family = NULL, weights = NULL, cluster = NULL, 
  ranefstart = NULL, offset = NULL, REML = TRUE, joint = TRUE, 
  abstol = 0.001, maxit = 100, dfsplit = TRUE, verbose = FALSE, 
  plot = FALSE, glmmTMB.control = glmmTMB::glmmTMBControl(), ...)

Arguments

formula	formula specifying the response variable and a three-part right-hand-side describing the regressors, random effects, and partitioning variables, respectively. For details see below.
data	data.frame to be used for estimating the model tree.
family	currently not used. The default beta distribution parameterization of package betareg is used, see also ?glmmTMB::beta_family.
weights	numeric. An optional numeric vector of weights. Can be a name of a column in data or a vector of length nrow(data).
cluster	currently not used.
ranefstart	currently not used.
offset	optional numeric vector to be included in the linear predictor with a coeffcient of one. Note that offset can be a name of a column in data or a a numeric vector of length nrow(data).
joint	currently not used. Fixed effects from the tree are always (re-)estimated jointly along with the random effects.
abstol	numeric. The convergence criterion used for estimation of the model. When the difference in log-likelihoods of the random-effects model from two consecutive iterations is smaller than abstol, estimation of the model tree has converged.
maxit	numeric. The maximum number of iterations to be performed in estimation of the model tree.
dfsplit	logical or numeric. as.integer(dfsplit) is the degrees of freedom per selected split employed when extracting the log-likelihood.
verbose	Should the log-likelihood value of the estimated random-effects model be printed for every iteration of the estimation?
plot	Should the tree be plotted at every iteration of the estimation? Note that selecting this option slows down execution of the function.
REML	logical scalar. Should the fixed-effects estimates be chosen to optimize the REML criterion (as opposed to the log-likelihood)? Will be passed to funtion glmmTMB(). See glmmTMB for details.
glmmTMB.control	list. An optional list with control parameters to be passed to glmmTMB(). See glmmTMBControl for details.
...	Additional arguments to be passed to lmtree() or glmtree(). See mob_control documentation for details.

Details

Experimental function.

Function betamertree aims to learn a tree where each terminal node is associated with different fixed-effects regression coefficients, while adjusting for global random effects (such as a random intercept). It is a generalization of the ideas underlying function glmertree, to allow for detection of subgroups with different fixed-effects parameter estimates, keeping the random effects constant throughout the tree (i.e., random effects are estimated globally). The estimation algorithm iterates between (1) estimation of the tree given an offset of random effects, and (2) estimation of the random effects given the tree structure. See Fokkema et al. (2018) for a detailed description.

Where glmertree uses function glmtree from package partykit to find the subgroups, and function glmer from package lme4 to estimate the mixed-effects model, betamertree uses function betatree from package betareg to find the subgroups, and function glmmTMB from package package glmmTMB to estimate the mixed-effects model.

The code is experimental and will change in future versions.

Value

The function returns a list with the following objects:

tree	The final betatree.
glmmTMB	The final glmmTMB random-effects model.
ranef	The corresponding random effects of glmmTMB.
varcorr	The corresponding VarCorr(glmmTMB).
variance	The corresponding attr(VarCorr(glmmTMB), "sc")^2.
data	The dataset specified with the data argument including added auxiliary variables .ranef and .tree from the last iteration.
loglik	The log-likelihood value of the last iteration.
iterations	The number of iterations used to estimate the betamertree.
maxit	The maximum number of iterations specified with the maxit argument.
ranefstart	The random effects used as an offset, as specified with the ranefstart argument.
formula	The formula as specified with the formula argument.
randomformula	The formula as specified with the randomformula argument.
abstol	The prespecified value for the change in log-likelihood to evaluate convergence, as specified with the abstol argument.
mob.control	A list containing control parameters passed to betatree(), as specified with ....
glmmTMB.control	A list containing control parameters passed to glmmTMB(), as specified in the control argument of function glmmTMB.
joint	Whether the fixed effects from the tree were (re-)estimated jointly along with the random effects, specified with the joint argument.

References

Fokkema M, Smits N, Zeileis A, Hothorn T, Kelderman H (2018). “Detecting Treatment-Subgroup Interactions in Clustered Data with Generalized Linear Mixed-Effects Model Trees”. Behavior Research Methods, 50(5), 2016-2034. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.3758/s13428-017-0971-x")}

See Also

glmmTMB, betatree

Examples

if (require("betareg") && require("glmmTMB")) {
## load example data
data("ReadingSkills", package = "betareg")
## add random noise (not associated with reading scores)
set.seed(1071)
ReadingSkills$x1 <- rnorm(nrow(ReadingSkills))
ReadingSkills$x2 <- runif(nrow(ReadingSkills))
ReadingSkills$x3 <- factor(rnorm(nrow(ReadingSkills)) > 0)
ReadingSkills$gr <- factor(rep(letters[1:5], length.out = nrow(ReadingSkills))) 

## Fit beta mixed-effects regression tree 
betamer_form <- accuracy ~ iq | gr | dyslexia + x1 + x2 + x3
bmertree <- betamertree(betamer_form, data = ReadingSkills, minsize = 10)
VarCorr(bmertree)
fixef(bmertree)
coef(bmertree)
plot(bmertree)
plot(bmertree, type = "simple")
predict(bmertree, newdata = ReadingSkills[1:5,])
predict(bmertree) ## see ?predict.glmmmTMB for other arguments that can be passed
residuals(bmertree) ## see ?residuals.glmmmTMB for other arguments that can be passed
}

glmertree documentation built on Sept. 9, 2023, 9:07 a.m.