Package 'r2mlm'

Compute R-squared values for multilevel models, automatically inputting parameter estimates.

Description

r2mlm reads in a multilevel model (MLM) object generated using lmer or nlme, and outputs all relevant R-squared measures from the Rights and Sterba (2019) framework of multilevel model R-squared measures, which can be visualized together as a set using the outputted bar chart decompositions of outcome variance. That is, when predictors are cluster-mean-centered, all R-squared measures from Rights & Sterba (2019) Table 1 and decompositions from Rights & Sterba (2019) Figure 1 are outputted. When predictors are not cluster-mean-centered, the total R-squared measures from Rights & Sterba (2019) Table 5, as well as bar chart decompositions are outputted. Any number of level-1 and/or level-2 predictors is supported. Any of the level-1 predictors can have random slopes.

Usage

r2mlm(model, bargraph = TRUE)

Arguments

model	A model generated using lmer or nlme. Note that models using lmer must specify random effects at the end of the model, like so: outcome ~ 1 + fixed_effects + (random_effects | cluster_variable). Anything else (e.g., outcome ~ 1 + (random_effects | cluster_variable) + fixed_effects) will not work.
bargraph	Optional bar graph output, default is TRUE.

Details

r2mlm first determines whether a given model was generated using lmer or nlme, then passes the model to helper functions that pull the raw data and parameter estimates from the model, and pass that information to r2mlm_manual.

Previous MLM literature has offered two perspectives on how to treat variance attributable to random intercepts and slopes, called the “marginal” and “conditional” approaches (e.g., Edwards et al., 2008; Orelien & Edwards, 2008; Vonesh & Chinchilli, 1997; Wang & Schaalje, 2009; Xu, 2003). In the marginal approach, all variance attributable to predictors via random slope variation and attributable to cluster means via random intercept variation (i.e., sources “v” and “m”) is treated as unexplained. In the conditional approach, variance attributable to predictors via random slope variation and/or attributable to cluster mean variation is treated as explained. This package offers researchers access to both the marginal and conditional approaches. There are 5 marginal measures: f1_total, f2_total, f_total, f1_within, and f2_between. The other 7 measures are conditional: v_total, m_total, fv_total, fvm_total, v_within, f1v_within, and m_between.

Value

If the input is a valid model, then the output will be a list and associated graphical representation of R-squared decompositions. If the model is not valid, it will return an error prompting the user to input a valid model.

See Also

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

Other r2mlm single model functions: r2mlm3_manual(), r2mlm_ci(), r2mlm_long_manual(), r2mlm_manual()

Examples

# Using lme4 for your model

# The "bobyqa" optimizer is required for this particular model to converge

model_lme4 <- lmer(satisfaction ~ 1 + salary_c + control_c + salary_m + control_m +
s_t_ratio + (1 + salary_c + control_c| schoolID), data = teachsat, REML =
TRUE, control = lmerControl(optimizer = "bobyqa"))

r2mlm(model_lme4)

# Using nlme for your model

model_nlme <- lme(satisfaction ~ 1 + salary_c + control_c + salary_m +
                  control_m + s_t_ratio,
                  random = ~ 1 + salary_c + control_c | schoolID,
                  data = teachsat,
                  method = "REML",
                  control = lmeControl(opt = "optim"))

r2mlm(model_nlme)

---

Compute confidence intervals for R-squared in multilevel models.

Description

r2mlm_ci reads in a multilevel model (MLM) object generated using lmer or nlme along with bootstrap specifications and returns the upper and lower bounds of confidence intervals for all R-squared measures available in the r2mlm framework.

Usage

r2mlm_ci(model, nsim, boottype, confinttype, level = 0.95, progress = T)

Arguments

model	A model generated using lmer or nlme. Note that models using lmer must specify random effects at the end of the model, like so: outcome ~ 1 + fixed_effects + (random_effects | cluster_variable). Anything else (e.g., outcome ~ 1 + (random_effects | cluster_variable) + fixed_effects) will not work.
nsim	The number of bootstrapping iterations to use for the bootstrapped sampling distribution. Common values are 500 and 1000.
boottype	A character vector for the type of bootstrapping to perform. Options are parametric and residual. Parametric bootstrapping assumes normally distributed residuals, whereas residual does not.
confinttype	A character vector for the type of confidence interval to calculate. Options are norm (for normal), basic, and perc (for percentile).
level	The desired confidence level, defaults to 0.95, yielding a 95 confidence interval.
progress	TRUE/FALSE for printing progress bar or not, defaults to TRUE.

Details

Note that bootstrapping confidence intervals for many R-squared values at once is computationally intensive, and as a result runs somewhat slowly. For this reason, the progress bar displays by default.

Value

If the input is a valid model, then the output will be a list of R-squared confidence intervals for all 12 measures estimated by the r2mlm function.

See Also

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

Other r2mlm single model functions: r2mlm3_manual(), r2mlm_long_manual(), r2mlm_manual(), r2mlm()

Examples

## Not run: 
# The "bobyqa" optimizer is required for this particular model to converge

model_lme4 <- lmer(satisfaction ~ 1 + salary_c + control_c + salary_m + control_m +
s_t_ratio + (1 + salary_c + control_c| schoolID), data = teachsat, REML =
TRUE, control = lmerControl(optimizer = "bobyqa"))

r2mlm_ci(model = model_lme4,
         nsim = 100,
         boottype = c("residual"),
         confinttype = c("perc"),
         level = 0.95,
         progress = TRUE)

## End(Not run)

---

Compute R-squared differences between two multilevel models, automatically inputting parameter estimates.

Description

r2mlm_comp reads in two multilevel models (MLMs) (generated using lmer or nlme) under comparison (designated Model A and Model B), and outputs all R-squared measures in the Rights and Sterba (2019) framework for both models, as well as R-squared differences between the two models. Definitions of these R-squared difference measures are provided in Rights & Sterba (2020) Table 1; importantly, to detect the impact of a specific kind of term (e.g., the kind of term added to Model A to form Model B), a particular target single-source R-squared difference measure from this framework is used. For instructions on how to identify which target single-source R-squared difference measure to interpret to detect the impact of which kind of term that distinguishes Model A from B, see Rights and Sterba (2020) Table 2. Additionally, this function produces side-by-side graphical comparisons of the R-squared measures for Model A vs. Model B that can be used to visualize changes in each measure across models. This function assumes all level-1 predictors are cluster-mean-centered, for reasons described in Rights & Sterba (2020). Any number of level-1 and/or level-2 predictors is supported and any of the level-1 predictors can have random slopes. This function can be used with either the hierarchical or the simultaneous model-building approach described in Rights and Sterba (2020). This function can be used with either nested or non-nested model comparisons (in which R-squared estimates for Model A are subtracted from those for Model B).

Usage

r2mlm_comp(modelA, modelB, data = NULL, bargraph = TRUE)

Arguments

modelA, modelB	Models generated using lmer or nlme. Note that models using lmer must specify random effects at the end of the model, like so: outcome ~ 1 + fixed_effects + (random_effects | cluster_variable). Anything else (e.g., outcome ~ 1 + (random_effects | cluster_variable) + fixed_effects) will not work.
data	Optional argument, only needed if models are not hierarchical. Dataset with rows denoting observations and columns denoting variables.
bargraph	Optional bar graph output, default is TRUE.

Details

Assumes that both models are fit with lmer or both models are fit with nlme.

Value

If the inputs are valid models, then the output will be a list and associated graphical representation of R-squared decompositions. If the models are not valid, the function will return an error prompting the user to input valid models.

See Also

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

Rights, J. D., & Sterba, S. K. (2020). New recommendations on the use of R-squared differences in multilevel model comparisons. Multivariate Behavioral Research. <doi:10.1080/00273171.2019.1660605>

Other r2mlm model comparison functions: r2mlm_comp_manual()

Examples

# Using lme4 for your model
# The "bobyqa" optimizer is required for these particular models to converge

## Not run:  # Model A, no "salary" components included

modelA_lme4 <- lmer(satisfaction ~ 1 + control_c + control_m + s_t_ratio + (1
+ control_c | schoolID), data = teachsat, REML = TRUE, control =
lmerControl(optimizer = "bobyqa"))

# Model B, full model with "salary" components included

modelB_lme4 <- lmer(satisfaction ~ 1 + salary_c + control_c + salary_m +
control_m + s_t_ratio + (1 + salary_c + control_c | schoolID), data =
teachsat, REML = TRUE, control = lmerControl(optimizer = "bobyqa"))

# Compare models
r2mlm_comp(modelA_lme4, modelB_lme4)

# Compare models, optional data argument specified
r2mlm_comp(modelA_lme4, modelB_lme4, teachsat)

# Using nlme for your model

# Model A, no "salary" components included

modelA_nlme <- lme(satisfaction ~ 1 + control_c + control_m + s_t_ratio,
                  random = ~ 1 + control_c | schoolID,
                  data = teachsat,
                  method = "REML",
                  control = lmeControl(opt = "optim"))

# Model B, full model with "salary" components included

modelB_nlme <- lme(satisfaction ~ 1 + salary_c + control_c + salary_m +
                  control_m + s_t_ratio,
                  random = ~ 1 + salary_c + control_c | schoolID,
                  data = teachsat,
                  method = "REML",
                  control = lmeControl(opt = "optim"))

# Compare models
r2mlm_comp(modelA_nlme, modelB_nlme)

# Compare models, optional data argument specified
r2mlm_comp(modelA_nlme, modelB_nlme, teachsat)

## End(Not run)

---

Compute R-squared differences between two multilevel models, manually inputting parameter estimates.

Description

r2mlm_comp_manual reads in raw data and multilevel model (MLM) parameter estimates from two separate models under comparison (designated Model A and Model B), and outputs all R-squared measures in the Rights and Sterba (2019) framework for both models, as well as R-squared differences between the two models. Definitions of these R-squared difference measures are provided in Rights & Sterba (2020) Table 1; importantly, to detect the impact of a specific kind of term (e.g., the kind of term added to Model A to form Model B), a particular target single-source R-squared difference measure from this framework is used. For instructions on how to identify which target single-source R-squared difference measure to interpret to detect the impact of which kind of term that distinguishes Model A from B, see Rights and Sterba (2020) Table 2. Additionally, this function produces side-by-side graphical comparisons of the R-squared measures for Model A vs. Model B that can be used to visualize changes in each measure across models. This function assumes all level-1 predictors are cluster-mean-centered for reasons described in Rights & Sterba (2020). Any number of level-1 and/or level-2 predictors is supported and any of the level-1 predictors can have random slopes. This function can be used with either the hierarchical or the simultaneous model-building approach described in Rights and Sterba (2020). This function can also be used with either nested or non-nested model comparisons (in which R-squared estimates for Model A are subtracted from those for Model B).

Usage

r2mlm_comp_manual(
  data,
  within_covs_modA,
  between_covs_modA,
  random_covs_modA,
  gamma_w_modA,
  gamma_b_modA,
  Tau_modA,
  sigma2_modA,
  within_covs_modB,
  between_covs_modB,
  random_covs_modB,
  gamma_w_modB,
  gamma_b_modB,
  Tau_modB,
  sigma2_modB,
  bargraph = TRUE
)

Arguments

data	Dataset with rows denoting observations and columns denoting variables.
within_covs_modA, within_covs_modB	List of numbers corresponding to the columns in the dataset of the level-1 predictors used in the MLM (if none used, set to NULL).
between_covs_modA, between_covs_modB	List of numbers corresponding to the columns in the dataset of the level-2 predictors used in the MLM (if none used, set to NULL).
random_covs_modA, random_covs_modB	List of numbers corresponding to the columns in the dataset of the level-1 predictors that have random slopes in the MLM (if no random slopes, set to NULL).
gamma_w_modA, gamma_w_modB	Vector of fixed slope estimates for all level-1 predictors, to be entered in the order of the predictors listed by within_covs (if none, set to NULL).
gamma_b_modA, gamma_b_modB	Vector of fixed intercept estimate (if applicable; see has_intercept below) and fixed slope estimates for all level-2 predictors, to be entered intercept first (if applicable) followed by level-2 slopes in the order listed by between_covs (if none, set to NULL).
Tau_modA, Tau_modB	Random effect covariance matrix; note that 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 by random_covs).
sigma2_modA, sigma2_modB	Level-1 residual variance.
bargraph	Optional bar graph output, default is TRUE.

Value

If the inputs are valid models, then the output will be a list and associated graphical representation of R-squared decompositions.

See Also

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

Rights, J. D., & Sterba, S. K. (2020). New recommendations on the use of R-squared differences in multilevel model comparisons. Multivariate Behavioral Research. <doi:10.1080/00273171.2019.1660605>

Other r2mlm model comparison functions: r2mlm_comp()

Examples

# Model A: no "salary" components included

modelA <- lmer(satisfaction ~ 1 + control_c + control_m + s_t_ratio + (1 +
control_c | schoolID), data = teachsat, REML = TRUE, control =
lmerControl(optimizer = "bobyqa"))

# Model B: full model with "salary" components included

modelB <- lmer(satisfaction ~ 1 + salary_c + control_c + salary_m + control_m
+ s_t_ratio + (1 + salary_c + control_c | schoolID), data = teachsat, REML =
TRUE, control = lmerControl(optimizer = "bobyqa"))

r2mlm_comp_manual(data = teachsat,
                  within_covs_modA = c(4),
                  between_covs_modA = c(6, 8),
                  random_covs_modA = c(4),
                  gamma_w_modA = c(0.314410),
                  gamma_b_modA = c(6.892046, 0.059464, -0.037376),
                  Tau_modA = matrix(c(0.559, 0.0105, 0.0105, 0.0273),
                                    2, 2),
                  sigma2_modA = 1.19295,
                  within_covs_modB = c(5, 4),
                  between_covs_modB = c(7, 6, 8),
                  random_covs_modB = c(5, 4),
                  gamma_w_modB = c(0.074485, 0.310800),
                  gamma_b_modB = c(4.352652, 0.036759, 0.027532, -0.035250),
                  Tau_modB = matrix(c(0.387, 0.0000646, 0.00625,
                                      0.0000646, 0.00277, -0.000333,
                                      0.00625, -0.000333, 0.0285), 3, 3),
                 sigma2_modB = 0.550311)

---

Compute R-squared values for longitudinal multilevel models, manually inputting parameter estimates.

Description

r2mlm_long_manual takes as input raw data and multilevel model (MLM) parameter estimates and outputs all relevant R-squared measures as well as an accompanying bar chart. This function extends the r2mlm_manual function by allowing researchers to input heteroscedastic variance estimates, and by providing level-specific measures for non-cluster-mean-centered models.

Usage

r2mlm_long_manual(
  data,
  covs,
  random_covs,
  clusterID,
  gammas,
  Tau,
  sigma2,
  bargraph = TRUE
)

Arguments

data	Dataset with rows denoting observations and columns denoting variables
covs	list of predictors in the dataset that have fixed components of slopes included in the model (if none, set to NULL)
random_covs	list of predictors in the dataset that have random components of slopes included in the model (if none, set to NULL)
clusterID	variable name in dataset corresponding to cluster (e.g., person) identification
gammas	vector containing estimated fixed components of all slopes, listed in the order specified in covs (if none, set to NULL)
Tau	random effect covariance matrix; the first row and the first column denote the intercept variance and covariances and each subsequent row/column denotes a given random slope’s variance and covariances (to be entered in the order listed by random_covs)
sigma2	level-1 residual variance; can be entered as a single number, or as a set of numbers, for example corresponding to different residual variances at individual timepoints; if entered as a set of numbers, function will assume equal weights and take the raw average of these to estimate the expectation of the error variance
bargraph	Optional bar graph output, default is TRUE.

Details

This function reads in raw data as well as parameter estimates from the researcher’s previously fit longitudinal growth model (hence, any software program can have been used to fit the researcher’s longitudinal growth model prior to the use of this R function, so long as parameter estimates from the fitted model are recorded; note that this function accommodates non-longitudinal models as well). This function then outputs R-squared measures as well as variance decompositions and associated bar charts outlined in Rights & Sterba (2021). This function allows researchers to input heteroscedastic residual variance by including multiple estimates, for example, corresponding to individual timepoints. Users need not specify if predictors are person-mean-centered or not—the function will automatically output total, within-person, and between-person variance attributable to each potential source of explained variance (f1, f2, v1, v2, and m). Note, however, that the interpretations of these sources differ for person-mean-centered versus non-person-mean-centered models and that variance attributable to v2 will necessarily be 0 for person-mean-centered models.

Value

If the input is valid, then the output will be a list and associated graphical representation of R-squared decompositions. If the input is not valid, it will return an error.

See Also

Rights, J. D., & Sterba, S. K. (2021). Effect size measures for longitudinal growth analyses: Extending a framework of multilevel model R-squareds to accommodate heteroscedasticity, autocorrelation, nonlinearity, and alternative centering strategies. New Directions for Child and Adolescent Development, 2021, 65– 110. <doi:10.1002/cad.20387>

Other r2mlm single model functions: r2mlm3_manual(), r2mlm_ci(), r2mlm_manual(), r2mlm()

Examples

# Removing cluster-mean-centering from the teachsat dataset, for
# demonstration purposes

teachsat$salary <- teachsat$salary_c + 2
uncentered_model <- lmer(satisfaction ~ salary + (1 | schoolID), data = teachsat)

r2mlm_long_manual(data = teachsat,
                  covs = c("salary"),
                  random_covs = NULL,
                  clusterID = "schoolID",
                  gammas = c(0.07430),
                  Tau = as.matrix(Matrix::bdiag(VarCorr(uncentered_model))),
                  sigma2 = getME(uncentered_model, "sigma")^2,
                  bargraph = TRUE)

---

Compute R-squared values for multilevel models, manually inputting parameter estimates.

Description

r2mlm_manual takes as input raw data and parameter estimates from a multilevel model, and outputs all relevant R-squared measures from the Rights and Sterba (2019) framework of R-squared measures for multilevel models, which can be visualized together as a set using the outputted bar chart decompositions of outcome variance. That is, when predictors are cluster-mean-centered, all R-squared measures from Rights & Sterba (2019) Table 1 and decompositions from Rights & Sterba (2019) Figure 1 are outputted. When predictors are not cluster-mean-centered, the total R-squareds from Rights & Sterba (2019) Table 5, as well as bar chart decompositions are outputted. Any number of level-1 and/or level-2 predictors is supported. Any of the level-1 predictors can have random slopes.

Usage

r2mlm_manual(
  data,
  within_covs,
  between_covs,
  random_covs,
  gamma_w,
  gamma_b,
  Tau,
  sigma2,
  has_intercept = TRUE,
  clustermeancentered = TRUE,
  bargraph = TRUE
)

Arguments

data	Dataset with rows denoting observations and columns denoting variables.
within_covs	List of numbers corresponding to the columns in the dataset of the level-1 predictors used in the MLM (if none used, set to NULL).
between_covs	List of numbers corresponding to the columns in the dataset of the level-2 predictors used in the MLM (if none used, set to NULL).
random_covs	List of numbers corresponding to the columns in the dataset of the level-1 predictors that have random slopes in the MLM (if no random slopes, set to NULL).
gamma_w	Vector of fixed slope estimates for all level-1 predictors, to be entered in the order of the predictors listed by within_covs (if none, set to NULL).
gamma_b	Vector of fixed intercept estimate (if applicable; see has_intercept below) and fixed slope estimates for all level-2 predictors, to be entered intercept first (if applicable) followed by level-2 slopes in the order listed by between_covs (if none, set to NULL).
Tau	Random effect covariance matrix; note that 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 by random_covs).
sigma2	Level-1 residual variance.
has_intercept	If set to TRUE, the first element of gamma_b is assumed to be the fixed intercept estimate; if set to FALSE, the first element of gamma_b is assumed to be the first fixed level- 2 predictor slope; set to TRUE by default.
clustermeancentered	If set to TRUE, all level-1 predictors (indicated by the within_covs list) are assumed to be cluster-mean-centered and function will output all decompositions; if set to FALSE, function will output only total decompositions (see Description above); set to TRUE by default.
bargraph	Optional bar graph output, default is TRUE.

Value

If the input is valid, then the output will be a list and associated graphical representation of R-squared decompositions. If the input is not valid, it will return an error.

See Also

Rights, J. D., & Sterba, S. K. (2019). Quantifying explained variance in multilevel models: An integrative framework for defining R-squared measures. Psychological Methods, 24(3), 309–338. <doi:10.1080/00273171.2019.1660605>

Other r2mlm single model functions: r2mlm3_manual(), r2mlm_ci(), r2mlm_long_manual(), r2mlm()

Examples

# The bobyqa optimizer is required for this model to converge in lme4

model <- lmer(satisfaction ~ 1 + salary_c + control_c + salary_m + control_m
+ s_t_ratio + (1 + salary_c + control_c | schoolID), data = teachsat, REML =
TRUE, control = lmerControl(optimizer = "bobyqa"))

r2mlm_manual(data = teachsat,
             within_covs = c(5, 4),
             between_covs = c(7, 6, 8),
             random_covs =  c(5, 4),
             gamma_w = c(0.074485, 0.310800),
             gamma_b = c(4.352652, 0.036759, 0.027532, -0.035250),
             Tau = matrix(c(0.387, 0.0000646,0.00625,
                            0.0000646, 0.00277, -0.000333,
                            0.00625, -0.000333, 0.0285), 3, 3),
             sigma2 = 0.55031,
             has_intercept = TRUE,
             clustermeancentered = TRUE)

---

Compute R-squared values for three-level multilevel models, manually inputting parameter estimates.

Description

r2mlm3_manual takes as input raw data and three-level multilevel model (MLM) parameter estimates and outputs all relevant R-squared measures as well as an accompanying bar chart.

Usage

r2mlm3_manual(
  data,
  l1_covs,
  l2_covs,
  l3_covs,
  random_covs12,
  random_covs13,
  random_covs23,
  gamma_1,
  gamma_2,
  gamma_3,
  Tau12,
  Tau13,
  Tau23,
  sigma2,
  clustermeancentered = TRUE,
  Tau2_noncmc = NULL,
  Tau3_noncmc = NULL,
  l2clusterID_noncmc = NULL,
  l3clusterID_noncmc = NULL,
  bargraph = TRUE
)

Arguments

data	Dataset with rows denoting observations and columns denoting variables
l1_covs	Vector of numbers (or variable names) corresponding to the columns in the dataset of the level-1 predictors used in the MLM (if none used, set to NULL)
l2_covs	Vector of numbers (or variable names) corresponding to the columns in the dataset of the level-2 predictors used in the MLM (if none used, set to NULL)
l3_covs	Vector of numbers (or variable names) corresponding to the columns in the dataset of the level-3 predictors used in the MLM (if none used, set to NULL)
random_covs12	Vector of numbers (or variable names) corresponding to the columns in the dataset of the level-1 predictors that have random slopes across level-2 units in the MLM (if no such random slopes, set to NULL)
random_covs13	Vector of numbers (or variable names) corresponding to the columns in the dataset of the level-1 predictors that have random slopes across level-3 units in the MLM (if no such random slopes, set to NULL)
random_covs23	Vector of numbers (or variable names) corresponding to the columns in the dataset of the level-2 predictors that have random slopes across level-3 units in the MLM (if no such random slopes, set to NULL)
gamma_1	Vector of fixed slope estimates for all level-1 predictors, to be entered in the order of the predictors listed by l1_covs (if none, set to NULL)
gamma_2	Vector of fixed slope estimates for all level-2 predictors, to be entered in the order of the predictors listed by l2_covs (if none, set to NULL)
gamma_3	Vector of fixed slope estimates for all level-3 predictors, to be entered in the order of the predictors listed by l3_covs (if none, set to NULL)
Tau12	For cluster-mean-centered model results (set to NULL if entering non-cluster-mean-centered model results), this is the random effect covariance matrix with the first row/column denoting the intercept variance and covariances across level-2 units and each subsequent row/column denotes a given level-1 predictor’s random slope variance and covariances across level-2 units (to be entered in the order listed by random_covs12; if none, set to NULL)
Tau13	For cluster-mean-centered model results (set to NULL if entering non-cluster-mean-centered model results), this is the random effect covariance matrix with the first row/column denoting the intercept variance and covariances across level-3 units and each subsequent row/column denotes a given level-1 predictor’s random slope variance and covariances across level-3 units (to be entered in the order listed by random_covs13; if none, set to NULL)
Tau23	For cluster-mean-centered model results (set to NULL if entering non-cluster-mean-centered model results), this is the random effect covariance matrix with each row/column denoting a given level-2 predictor’s random slope variance and covariances across level-3 units (to be entered in the order listed by random_covs23; if none, set to NULL)
sigma2	Level-1 residual variance
clustermeancentered	By default, this argument is set to TRUE, indicating that cluster-mean-centered model results are being inputted. When instead entering non-cluster-mean-centered model results, set this argument to FALSE. Additionally, for non-cluster-mean-centered model results, random effect variances/covariances are to be entered in arguments Tau2_noncmc and Tau3_noncmc (defined below), rather than in the Tau12, Tau13, and Tau23 arguments used for cluster-mean-centered model results. Additionally, when entering non-cluster-mean-centered model results, user must specify l2clusterID_noncmc and l3clusterID_noncmc (neither of which are necessary for cluster-mean-centered model results). Function input is otherwise the same for cluster-mean-centered and non-cluster-mean-centered model results.
Tau2_noncmc	For non-cluster-mean-centered model results, this is the level-2 random effect covariance matrix; the first row/column denotes the intercept variance and covariances across level-2 units and each subsequent row/column denotes a given predictor’s random slope variance and covariances across level-2 units (to be entered in the order listed by randomcovsl2_noncmc; by default, this argument is set to NULL)
Tau3_noncmc	For non-cluster-mean-centered model results, this is the level-3 random effect covariance matrix; the first row/column denotes the intercept variance and covariances across level-3 units and each subsequent row/column denotes a given predictor’s random slope variance and covariances across level-3 units (to be entered in the order listed by randomcovsl2_noncmc; by default, this argument is set to NULL)
l2clusterID_noncmc	For non-cluster-mean-centered model results, this is the number (or variable name) corresponding to the column in the dataset containing the level-2 cluster identification (function assumes that each level-2 cluster ID is unique; by default, this argument is set to NULL)
l3clusterID_noncmc	For non-cluster-mean-centered model results, this is the number (or variable name) corresponding to the column in the dataset containing the level-3 cluster identification (function assumes that each level-3 cluster ID is unique; by default, this argument is set to NULL)
bargraph	Optional bar graph output, default is TRUE.

Details

This function can also accommodate two-level models. To input results for two-level models, set the following arguments equal to NULL: l3_covs, random_covs13, random_covs23, gamma_3, Tau13, Tau23.

Value

If the input is valid, then the output will be a list and associated graphical representation of R-squared decompositions. If the input is not valid, it will return an error.

See Also

Other r2mlm single model functions: r2mlm_ci(), r2mlm_long_manual(), r2mlm_manual(), r2mlm()

---

Teacher job satisfaction.

Description

A simulated dataset containing information about teacher job satisfaction. Teachers clustered within schools.

Usage

teachsat

Format

A data frame with 9000 rows and 8 columns:

schoolID

school identification number

teacherID

teacher identification number

satisfaction

teacher job satisfaction, 1-10 scale

control_c

school-mean-centered rating of teacher's reported control over curriculum

salary_c

school-mean-centered teacher's salary (in thousands of dollars)

control_m

school mean rating of teacher's reported control over curriculum

salary_m

school mean teacher's salary (in thousands of dollars)

s_t_ratio

student to teacher ratio for the school (number of students per teacher)

---