multilevel.r2.manual: R-Squared Measures for Multilevel and Linear Mixed Effects Models by Rights and Sterba (2019), Manually Inputting Parameter Estimates

Description

This function computes R-squared measures by Rights and Sterba (2019) for multilevel and linear mixed effects models by manually inputting parameter estimates.

Usage

multilevel.r2.manual(data, within = NULL, between = NULL, random = NULL,
                     gamma.w = NULL, gamma.b = NULL, tau, sigma2,
                     intercept = TRUE, center = TRUE, digits = 3,
                     plot = FALSE, gray = FALSE, start = 0.15, end = 0.85,
                     color = c("#D55E00", "#0072B2", "#CC79A7", "#009E73", "#E69F00"),
                     filename = NULL, width = NA, height = NA,
                     units = c("in", "cm", "mm", "px"), dpi = 600,
                     write = NULL, append = TRUE, check = TRUE, output = TRUE)

Value

Returns an object of class misty.object, which is a list with following entries:

call: function call
type: type of analysis
data: matrix or data frame specified in data
plot: ggplot2 object for plotting the results
args: specification of function arguments
result: list with result tables, i.e., decomp for the decomposition, total for total R2 measures, within for the within-cluster R2 measures, and between

for the between-cluster R2 measures.

Arguments

data: a matrix or data frame with the level-1 and level-2 predictors and outcome variable used in the model.
within: a character vector with the variable names in data or numeric vector with numbers corresponding to the columns in data of the level-1 predictors used in the model. If none used, set to NULL.
between: a character vector with the variable names in data or numeric vector with numbers corresponding to the columns in data of the level-2 predictors used in the model. If none used, set to NULL.
random: a character vector with the variable names in data or numeric vector with numbers corresponding to the columns in data of the level-1 predictors that have random slopes in the model. If no random slopes specified, set to NULL.
gamma.w: a numeric vector of fixed slope estimates for all level-1 predictors, to be entered in the order of the predictors listed in the argument within.
gamma.b: a numeric vector of the intercept and fixed slope estimates for all level-2predictors, to be entered in the order of the predictors listed in the argument between. Note that the first element is the parameter estimate for the intercept if intercept = TRUE.
tau: a matrix indicating the random effects covariance matrix, the first row/column denotes the intercept variance and covariances (if intercept is fixed, set all to 0) and each subsequent row/column denotes a given random slope's variance and covariances (to be entered in the order listed in the argument random).
sigma2: a numeric value indicating the level-1 residual variance.
intercept: logical: if TRUE (default), the first element in the gamma.b is assumed to be the fixed intercept estimate; if set to FALSE, the first element in the argument gamma.b is assumed to be the first fixed level-2 predictor slope.
center: logical: if TRUE (default), all level-1 predictors are assumed to be cluster-mean-centered and the function will output all decompositions; if set to FALSE, function will output only the total decomposition.
digits: an integer value indicating the number of decimal places to be used.
plot: logical: if TRUE, bar chart showing the decomposition of scaled total, within-cluster, and between-cluster outcome variance into five (total), three (within-cluster), and two (between-cluster) proportions is drawn. Note that the ggplot2 package is required to draw the bar chart.
gray: logical: if TRUE, graphical parameter to draw the bar chart in gray scale.
start: a numeric value between 0 and 1, graphical parameter to specify the gray value at the low end of the palette.
end: a numeric value between 0 and 1, graphical parameter to specify the gray value at the high end of the palette.
color: a character vector, graphical parameter indicating the color of bars in the bar chart in the following order: Fixed slopes (Within), Fixed slopes (Between), Slope variation (Within), Intercept variation (Between), and Residual (Within). By default, colors from the colorblind-friendly palettes are used.
filename: a character string indicating the filename argument including the file extension in the ggsave function. Note that one of ".eps", ".ps", ".tex", ".pdf" (default), ".jpeg", ".tiff", ".png", ".bmp", ".svg" or ".wmf" needs to be specified as file extension in the file argument. Note that plots can only be saved when plot = TRUE.
width: a numeric value indicating the width argument (default is the size of the current graphics device) in the ggsave function.
height: a numeric value indicating the height argument (default is the size of the current graphics device) in the ggsave function.
units: a character string indicating the units argument (default is in) in the ggsave function.
dpi: a numeric value indicating the dpi argument (default is 600) in the ggsave function.
write: a character string naming a text file with file extension ".txt" (e.g., "Output.txt") for writing the output into a text file.
append: logical: if TRUE (default), output will be appended to an existing text file with extension .txt specified in write, if FALSE existing text file will be overwritten.
check: logical: if TRUE (default), argument specification is checked.
output: logical: if TRUE (default), output is shown on the console.

Author

Jason D. Rights, Sonya K. Sterba, Jessica K. Flake, and Takuya Yanagida

Details

A number of R-squared measures for multilevel and linear mixed effects models have been developed in the methodological literature (see Rights & Sterba, 2018). R-squared measures by Rights and Sterba (2019) provide an integrative framework of R-squared measures for multilevel and linear mixed effects models with random intercepts and/or slopes. Their measures are based on partitioning model implied variance from a single fitted model, but they provide a full partitioning of the total outcome variance to one of five specific sources. See the help page of the multilevel.r2 function for more details.

References

Rights, J. D., & Cole, D. A. (2018). Effect size measures for multilevel models in clinical child and adolescent research: New r-squared methods and recommendations. Journal of Clinical Child and Adolescent Psychology, 47, 863-873. https://doi.org/10.1080/15374416.2018.1528550

Rights, J. D., & Sterba, S. K. (2019). Quantifying explained variance in multilevel models: An integrative framework for defining R-squared measures. Psychological Methods, 24, 309-338. https://doi.org/10.1037/met0000184

Examples

Run this code

if (FALSE) {

# Load misty and lme4 package
misty::libraries(misty, lme4)

# Load data set "Demo.twolevel" in the lavaan package
data("Demo.twolevel", package = "lavaan")

#-------------------------------------------------------------------------------

Demo.twolevel <- center(Demo.twolevel, x2, type = "CWC", cluster = "cluster")

# Compute group means, cluster.scores() from the misty package
Demo.twolevel <- cluster.scores(Demo.twolevel, x2, cluster = "cluster", name = "x2.b")

# Estimate random intercept model using the lme4 package
mod1 <- lmer(y1 ~ x2.c + x2.b + w1 + (1| cluster), data = Demo.twolevel,
             REML = FALSE, control = lmerControl(optimizer = "bobyqa"))

# Estimate random intercept and slope model using the lme4 package
mod2 <- lmer(y1 ~ x2.c + x2.b + w1 + (1 + x2.c | cluster), data = Demo.twolevel,
             REML = FALSE, control = lmerControl(optimizer = "bobyqa"))

#-------------------------------------------------------------------------------
# Example 1: Random intercept model

# Fixed slope estimates
fixef(mod1)

# Random effects variance-covariance matrix
as.data.frame(VarCorr(mod1))

# R-squared measures according to Rights and Sterba (2019)
multilevel.r2.manual(data = Demo.twolevel,
                     within = "x2.c", between = c("x2.b", "w1"),
                     gamma.w = 0.41127956,
                     gamma.b = c(0.01123245, -0.08269374, 0.17688507),
                     tau = 0.9297401,
                     sigma2 = 1.813245794)

#-------------------------------------------------------------------------------
# Example 2: Random intercept and slope model

# Fixed slope estimates
fixef(mod2)

# Random effects variance-covariance matrix
as.data.frame(VarCorr(mod2))

# R-squared measures according to Rights and Sterba (2019)
multilevel.r2.manual(data = Demo.twolevel,
                     within = "x2.c", between = c("x2.b", "w1"), random = "x2.c",
                     gamma.w = 0.41127956,
                     gamma.b = c(0.01123245, -0.08269374, 0.17688507),
                     tau = matrix(c(0.931008649, 0.004110479, 0.004110479, 0.017068857), ncol = 2),
                     sigma2 = 1.813245794)
}

Run the code above in your browser using DataLab