glmertree (version 0.2-4)

betamertree: 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(), ...)

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.

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.

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. tools:::Rd_expr_doi("10.3758/s13428-017-0971-x")

See Also

glmmTMB, betatree

Examples

# \donttest{
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
}
# }