Package 'MLMES' reference manual

Title:	Model-Based Effect Sizes for Multilevel Models
Description:	Computes model-based effect sizes for fixed-effect coefficients in multilevel (hierarchical) models. The coefficient effect sizes are standardized mean differences from zero (d) and unique variance-explained measures (squared semi-partial correlations, sr2). The package also reports variance components and level-specific and total R-squared values. It supports 2-level and 3-level linear and binary logistic models fitted with 'lme4' (Bates et al., 2015) <doi:10.18637/jss.v067.i01>, and 2-level Gaussian and Bernoulli models fitted with 'brms' (Bürkner, 2017) <doi:10.18637/jss.v080.i01>. Sanders, Konold, and Cheng (in press), "Model-based effect sizes for multilevel linear regression coefficients," Methodology: European Journal of Research Methods for the Behavioral and Social Sciences, describe the 2-level linear-model methods.
Authors:	Yijun Cheng [aut, cre], Elizabeth A. Sanders [aut], Timothy R. Konold [aut], Zhigang Zhang [aut], Zixie Zheng [aut]
Maintainer:	Yijun Cheng <[email protected]>
License:	GPL-3
Version:	0.1.2
Built:	2026-09-20 09:03:02 UTC
Source:	https://github.com/cran/MLMES

Three-Level Student Achievement Dataset

Description

A processed subset of the Achieve data used in Chapter 4, "Level-3 and Higher Models," of Finch, Bolin, and Kelley (2024). The data contain 10,320 students (L1) nested within 568 classrooms (L2), which are nested within 160 schools (L3).

Usage

data("achieve_3L_data")
data("achieve_3L_data")

Format

A data frame with 10,320 observations on 9 variables:

geread: General reading achievement score (outcome)
z_gevocab_CMC: General vocabulary score, classroom-mean-centered and standardized (L1)
gender_eff: Effect-coded gender: original code 1 = -1 and original code 2 = 1 (L1)
z_gemath_agg_CMC: Classroom mean mathematics achievement, school-mean-centered and standardized (L2)
z_ptratio_CMC: Pupil-teacher ratio, school-mean-centered and standardized (L2)
z_ses_GMC: School socioeconomic status, grand-mean-centered and standardized (L3)
school: School identifier (L3 unit)
class: Classroom code within school
school_class: Unique classroom identifier (L2 unit)

Details

Continuous predictors were centered according to their model level and then standardized. The student vocabulary score was centered within classrooms; classroom mean mathematics achievement and pupil-teacher ratio were centered within schools; and school socioeconomic status was centered at the grand mean. Only the variables used in the package examples are retained.

Source

https://www.mlminr.com/data-sets

References

Finch, W. H., Bolin, J. E., & Kelley, K. (2024). Multilevel modeling using R (3rd ed.). Chapman & Hall/CRC. doi:10.1201/b23166

Coefficient Effect Sizes for 3-Level Binary Logistic Multilevel Models

Description

Computes the standardized mean difference from zero ( $d$ ) and unique variance-explained ( $sr^2$ ) for each fixed-effect coefficient in a 3-level binary logistic model fitted with lme4::glmer. Effect sizes are based on latent variance.

Usage

glmerES_3L(model, verbose = TRUE)
glmerES_3L(model, verbose = TRUE)

Arguments

model

A 3-level model fitted with lme4::glmer, using the binomial family and logit link.

verbose

Logical; if TRUE (default), prints a note explaining column abbreviations.

Details

The standardized mean difference and squared semi-partial correlation follow the definitions used for linear models, but their denominators are based on latent variance. L1 predictors should be centered within L2 units, and L2 predictors should be centered within L3 units. Continuous predictors should be z-scored after centering, and categorical predictors should be effect-coded.

Value

A data frame with coefficient estimates and model-based effect sizes:

Variable: Predictor name.
Level: Predictor level: 1, 2, or 3.
RS_L2: Random-slope status at L2: 1 = yes, 0 = no.
RS_L3: Random-slope status at L3: 1 = yes, 0 = no.
Coeff: Unstandardized logit coefficient.
SE: Standard error.
z: z statistic.
p: p value.
d_lev: Standardized mean difference using level-specific variance.
d_L1_L2: Standardized mean difference using L1 and L2 variance; reported for L1 predictors.
d_L2_L3: Standardized mean difference using L2 and L3 variance; reported for L2 predictors.
d_tot: Standardized mean difference using total variance.
sr2_lev: Unique proportion of level-specific variance explained.
sr2_L1_L2: Unique proportion of L1 and L2 variance explained; reported for L1 predictors.
sr2_L2_L3: Unique proportion of L2 and L3 variance explained; reported for L2 predictors.
sr2_tot: Unique proportion of total variance explained.

References

Sanders, E. A., Konold, T. R., & Cheng, Y. (in press). Model-based effect sizes for multilevel linear regression coefficients. Methodology: European Journal of Research Methods for the Behavioral and Social Sciences.

McCulloch, C. E., Searle, S. R., & Neuhaus, J. M. (2008). Generalized, linear, and mixed models (2nd ed.). Wiley.

Bates, D., Mächler, M., Bolker, B., & Walker, S. (2015). Fitting linear mixed-effects models using lme4. Journal of Statistical Software, 67(1), 1–48. doi:10.18637/jss.v067.i01

Examples

data("achieve_3L_data")

cutvalue_read <- stats::quantile(achieve_3L_data$geread, probs = 0.40)
achieve_binary <- transform(
  achieve_3L_data,
  geread_pass = as.integer(geread >= cutvalue_read)
)

three_level_logit_fit <- lme4::glmer(
  geread_pass ~ z_gevocab_CMC + gender_eff +
    z_gemath_agg_CMC + z_ptratio_CMC + z_ses_GMC +
    (1 | school_class) + (1 | school),
  data = achieve_binary,
  family = binomial,
  control = lme4::glmerControl(
    optimizer = "bobyqa",
    optCtrl = list(maxfun = 2e5)
  )
)

glmerES_3L(three_level_logit_fit)

data("achieve_3L_data")

cutvalue_read <- stats::quantile(achieve_3L_data$geread, probs = 0.40)
achieve_binary <- transform(
  achieve_3L_data,
  geread_pass = as.integer(geread >= cutvalue_read)
)

three_level_logit_fit <- lme4::glmer(
  geread_pass ~ z_gevocab_CMC + gender_eff +
    z_gemath_agg_CMC + z_ptratio_CMC + z_ses_GMC +
    (1 | school_class) + (1 | school),
  data = achieve_binary,
  family = binomial,
  control = lme4::glmerControl(
    optimizer = "bobyqa",
    optCtrl = list(maxfun = 2e5)
  )
)

glmerES_3L(three_level_logit_fit)

R-Squared Measures for 3-Level Binary Logistic Multilevel Models

Description

Returns latent-scale R-squared values for the variance sources in a 3-level binary logistic model fitted with lme4::glmer.

Usage

glmerRsq_3L(model, verbose = TRUE)
glmerRsq_3L(model, verbose = TRUE)

Arguments

model

A 3-level model fitted with lme4::glmer, using the binomial family and logit link.

verbose

Logical; if TRUE (default), prints a note explaining column abbreviations.

Details

Rows beginning with FE, L1_RS, L2_RS, or RI give R-squared values for the indicated variance source. Rows containing total combine fixed- and random-effects variance sources across levels.

Value

A data frame with R-squared values for each variance source or combination of sources:

Effect: Variance source or combination of sources.
TotalRsq: Proportion of total latent variance explained.
L1Rsq: Proportion of L1 latent variance explained.
L2Rsq: Proportion of L2 latent variance explained.
L3Rsq: Proportion of L3 latent variance explained.

References

McCulloch, C. E., Searle, S. R., & Neuhaus, J. M. (2008). Generalized, linear, and mixed models (2nd ed.). Wiley.

Bates, D., Mächler, M., Bolker, B., & Walker, S. (2015). Fitting linear mixed-effects models using lme4. Journal of Statistical Software, 67(1), 1–48. doi:10.18637/jss.v067.i01

Examples

data("achieve_3L_data")

cutvalue_read <- stats::quantile(achieve_3L_data$geread, probs = 0.40)
achieve_binary <- transform(
  achieve_3L_data,
  geread_pass = as.integer(geread >= cutvalue_read)
)

three_level_logit_fit <- lme4::glmer(
  geread_pass ~ z_gevocab_CMC + gender_eff +
    z_gemath_agg_CMC + z_ptratio_CMC + z_ses_GMC +
    (1 | school_class) + (1 | school),
  data = achieve_binary,
  family = binomial,
  control = lme4::glmerControl(
    optimizer = "bobyqa",
    optCtrl = list(maxfun = 2e5)
  )
)

glmerRsq_3L(three_level_logit_fit)

data("achieve_3L_data")

cutvalue_read <- stats::quantile(achieve_3L_data$geread, probs = 0.40)
achieve_binary <- transform(
  achieve_3L_data,
  geread_pass = as.integer(geread >= cutvalue_read)
)

three_level_logit_fit <- lme4::glmer(
  geread_pass ~ z_gevocab_CMC + gender_eff +
    z_gemath_agg_CMC + z_ptratio_CMC + z_ses_GMC +
    (1 | school_class) + (1 | school),
  data = achieve_binary,
  family = binomial,
  control = lme4::glmerControl(
    optimizer = "bobyqa",
    optCtrl = list(maxfun = 2e5)
  )
)

glmerRsq_3L(three_level_logit_fit)

Variance Components for 3-Level Binary Logistic Multilevel Models

Description

Returns the latent-scale variance components used to calculate model-based effect sizes for a 3-level binary logistic model fitted with lme4::glmer.

Usage

glmerVarComp_3L(model, verbose = TRUE)
glmerVarComp_3L(model, verbose = TRUE)

Arguments

model

A 3-level model fitted with lme4::glmer, using the binomial family and logit link.

verbose

Logical; if TRUE (default), prints a note explaining column abbreviations.

Details

The mean response probability is approximated from the model intercept and random-effects variance following McCulloch, Searle, and Neuhaus (2008). Observation-level variance is then calculated as $1 / \{\bar p(1 - \bar p)\}$ .

Value

A data frame with rows for L1, L2, L3, and all variance sources:

levels: Variance level: L1, L2, L3, or All.
FE_Var: Fixed-effects variance.
L1_Resid_Var: Observation-level variance.
L1_RS_L2_Var: Variance from L1 slopes varying across L2 units.
L1_RS_L3_Var: Variance from L1 slopes varying across L3 units. When an L1 and an L2 predictor both have random slopes at L3, their slope contributions covary, and the full L3 slope variance exceeds the sum of the two separate variances by twice that covariance. This component includes one copy of the covariance and L2_RS_Var includes the other, so the two together account for the full L3 slope variance. Under the cluster-mean centering the framework assumes, the covariance is exactly zero and this term is the plain variance.
L2_RI_Var: Conditional L2 random-intercept variance.
L2_RS_Var: Variance from L2 slopes varying across L3 units. Includes the second copy of the covariance described under L1_RS_L3_Var.
L3_RI_Var: Conditional L3 random-intercept variance.
TotVar: Variance for the specified level.
SD: Square root of TotVar.

References

McCulloch, C. E., Searle, S. R., & Neuhaus, J. M. (2008). Generalized, linear, and mixed models (2nd ed.). Wiley.

Bates, D., Mächler, M., Bolker, B., & Walker, S. (2015). Fitting linear mixed-effects models using lme4. Journal of Statistical Software, 67(1), 1–48. doi:10.18637/jss.v067.i01

Examples

data("achieve_3L_data")

cutvalue_read <- stats::quantile(achieve_3L_data$geread, probs = 0.40)
achieve_binary <- transform(
  achieve_3L_data,
  geread_pass = as.integer(geread >= cutvalue_read)
)

three_level_logit_fit <- lme4::glmer(
  geread_pass ~ z_gevocab_CMC + gender_eff +
    z_gemath_agg_CMC + z_ptratio_CMC + z_ses_GMC +
    (1 | school_class) + (1 | school),
  data = achieve_binary,
  family = binomial,
  control = lme4::glmerControl(
    optimizer = "bobyqa",
    optCtrl = list(maxfun = 2e5)
  )
)

glmerVarComp_3L(three_level_logit_fit)

data("achieve_3L_data")

cutvalue_read <- stats::quantile(achieve_3L_data$geread, probs = 0.40)
achieve_binary <- transform(
  achieve_3L_data,
  geread_pass = as.integer(geread >= cutvalue_read)
)

three_level_logit_fit <- lme4::glmer(
  geread_pass ~ z_gevocab_CMC + gender_eff +
    z_gemath_agg_CMC + z_ptratio_CMC + z_ses_GMC +
    (1 | school_class) + (1 | school),
  data = achieve_binary,
  family = binomial,
  control = lme4::glmerControl(
    optimizer = "bobyqa",
    optCtrl = list(maxfun = 2e5)
  )
)

glmerVarComp_3L(three_level_logit_fit)

High School and Beyond (HSB) Dataset

Description

Cross-sectional data on math achievement and sociodemographic characteristics for 7,185 students from 160 U.S. high schools. Students (L1) are nested within schools (L2). The data include the original variables and the centered, effect-coded, and z-scored predictors used in the package examples.

Usage

data("hsb_data")
data("hsb_data")

Format

A data frame with 7,185 observations on 27 variables:

school: School identifier (level-2 unit)
size: School size
sector: School sector (1 = Catholic, 0 = public)
disclim: Disciplinary climate
himinty: Indicator for more than 40 percent minority enrollment (1 = yes, 0 = no)
student: Student identifier
minority: Minority status (1 = yes, 0 = no)
female: Female indicator (1 = yes, 0 = no)
ses: Socioeconomic status
mathach: Mathematics achievement score (outcome)
minority_eff: Minority status, effect-coded
female_eff: Female indicator, effect-coded
minority_eff_CMC: Minority status, effect-coded and cluster-mean-centered (L1)
female_eff_CMC: Female indicator, effect-coded and cluster-mean-centered (L1)
ses_CMC: SES, cluster-mean-centered (L1)
z_ses_CMC: SES, cluster-mean-centered and z-scored (L1)
mathach_agg: School-aggregated math achievement
ses_agg: School-aggregated SES
sqrt_size: Square root of school size
sector_eff: School sector, effect-coded (L2)
himinty_eff: High minority enrollment, effect-coded (L2)
ses_agg_GMC: Aggregated SES, grand-mean-centered (L2)
sqrt_size_GMC: Square root of school size, grand-mean-centered (L2)
disclim_GMC: Disciplinary climate, grand-mean-centered (L2)
z_ses_agg_GMC: Aggregated SES, grand-mean-centered and z-scored (L2)
z_sqrt_size_GMC: Square root of school size, grand-mean-centered and z-scored (L2)
z_disclim_GMC: Disciplinary climate, grand-mean-centered and z-scored (L2)

References

Raudenbush, S. W., & Bryk, A. S. (2002). Hierarchical linear models: Applications and data analysis methods (2nd ed.). Thousand Oaks, CA: Sage Publications.

Coefficient Effect Sizes for 2-Level Linear Multilevel Models

Description

Computes two model-based effect sizes for each fixed-effect coefficient in a 2-level hierarchical linear model fitted with lme4::lmer: the standardized mean difference from zero ( $d$ ) and unique variance-explained ( $sr^2$ ). Each effect size is reported relative to level-specific variance and total variance.

Usage

lmerES(model, verbose = TRUE)
lmerES(model, verbose = TRUE)

Arguments

model

A 2-level linear model fitted with lme4::lmer.

verbose

Logical; if TRUE (default), prints a note explaining column abbreviations.

Details

The standardized mean difference expresses a coefficient relative to the model-implied standard deviation of the outcome. The squared semi-partial correlation gives the proportion of outcome variance uniquely explained by a predictor after accounting for its shared variance with the other predictors. Level-specific effect sizes use variance sources associated with the predictor level; total effect sizes use all L1 and L2 variance sources.

Degrees of freedom and p values are taken from summary(model). Fit the model with lmerTest::lmer, or convert an existing lme4::lmer model with lmerTest::as_lmerModLmerTest, to report these values. For an lme4::lmer model, the df and p columns contain NA.

L1 predictors should be cluster-mean-centered. Continuous L1 and L2 predictors should be z-scored after centering, and categorical predictors should be effect-coded. When the model is fitted by maximum likelihood (REML = FALSE), finite-sample bias corrections are applied before the effect sizes are calculated.

Value

A data frame with coefficient estimates and model-based effect sizes:

Variable: Predictor name.
Level: Predictor level: 1 or 2.
RS: Random-slope status: 1 = yes, 0 = no.
Coeff: Unstandardized coefficient estimate.
SE: Standard error.
t: t statistic.
df: Degrees of freedom, when available.
p: p value, when available.
d_lev: Standardized mean difference using level-specific variance.
d_tot: Standardized mean difference using total variance.
sr2_lev: Unique proportion of level-specific variance explained.
sr2_tot: Unique proportion of total variance explained.

References

Bates, D., Mächler, M., Bolker, B., & Walker, S. (2015). Fitting linear mixed-effects models using lme4. Journal of Statistical Software, 67(1), 1–48. doi:10.18637/jss.v067.i01

Kuznetsova, A., Brockhoff, P. B., & Christensen, R. H. B. (2017). lmerTest package: Tests in linear mixed effects models. Journal of Statistical Software, 82(13), 1–26. doi:10.18637/jss.v082.i13

Examples

data("hsb_data")

if (requireNamespace("lmerTest", quietly = TRUE)) {
  hsb_m1c <- lmerTest::lmer(mathach ~
      minority_eff_CMC + female_eff_CMC + z_ses_CMC +
      z_ses_agg_GMC +
      z_sqrt_size_GMC + sector_eff + z_disclim_GMC + himinty_eff +
      (1 + minority_eff_CMC + female_eff_CMC + z_ses_CMC | school),
    data = hsb_data, REML = FALSE,
    control = lme4::lmerControl(optimizer = "bobyqa",
                                optCtrl = list(maxfun = 2e5)))

  lmerES(hsb_m1c)
}

data("hsb_data")

if (requireNamespace("lmerTest", quietly = TRUE)) {
  hsb_m1c <- lmerTest::lmer(mathach ~
      minority_eff_CMC + female_eff_CMC + z_ses_CMC +
      z_ses_agg_GMC +
      z_sqrt_size_GMC + sector_eff + z_disclim_GMC + himinty_eff +
      (1 + minority_eff_CMC + female_eff_CMC + z_ses_CMC | school),
    data = hsb_data, REML = FALSE,
    control = lme4::lmerControl(optimizer = "bobyqa",
                                optCtrl = list(maxfun = 2e5)))

  lmerES(hsb_m1c)
}

Coefficient Effect Sizes for 3-Level Linear Multilevel Models

Description

Computes two model-based effect sizes for each fixed-effect coefficient in a 3-level hierarchical linear model fitted with lme4::lmer: the standardized mean difference from zero ( $d$ ) and unique variance-explained ( $sr^2$ ). Effect sizes are reported relative to level-specific, adjacent-level, and total variance where applicable.

Usage

lmerES_3L(model, verbose = TRUE)
lmerES_3L(model, verbose = TRUE)

Arguments

model

A 3-level linear model fitted with lme4::lmer.

verbose

Logical; if TRUE (default), prints a note explaining column abbreviations.

Details

L1 predictors should be centered within L2 units, and L2 predictors should be centered within L3 units. Continuous predictors should be z-scored after centering, and categorical predictors should be effect-coded. When the model is fitted by maximum likelihood (REML = FALSE), finite-sample bias corrections are applied before the effect sizes are calculated.

Value

A data frame with coefficient estimates and model-based effect sizes:

Variable: Predictor name.
Level: Predictor level: 1, 2, or 3.
RS_L2: Random-slope status at L2: 1 = yes, 0 = no.
RS_L3: Random-slope status at L3: 1 = yes, 0 = no.
Coeff: Unstandardized coefficient estimate.
SE: Standard error.
t: t statistic.
df: Degrees of freedom, when available.
p: p value, when available.
d_lev: Standardized mean difference using level-specific variance.
d_L1_L2: Standardized mean difference using L1 and L2 variance; reported for L1 predictors.
d_L2_L3: Standardized mean difference using L2 and L3 variance; reported for L2 predictors.
d_tot: Standardized mean difference using total variance.
sr2_lev: Unique proportion of level-specific variance explained.
sr2_L1_L2: Unique proportion of L1 and L2 variance explained; reported for L1 predictors.
sr2_L2_L3: Unique proportion of L2 and L3 variance explained; reported for L2 predictors.
sr2_tot: Unique proportion of total variance explained.

References

Bates, D., Mächler, M., Bolker, B., & Walker, S. (2015). Fitting linear mixed-effects models using lme4. Journal of Statistical Software, 67(1), 1–48. doi:10.18637/jss.v067.i01

Kuznetsova, A., Brockhoff, P. B., & Christensen, R. H. B. (2017). lmerTest package: Tests in linear mixed effects models. Journal of Statistical Software, 82(13), 1–26. doi:10.18637/jss.v082.i13

Examples

data("achieve_3L_data")

three_level_fit <- lmerTest::lmer(
  geread ~ z_gevocab_CMC + gender_eff +
    z_gemath_agg_CMC + z_ptratio_CMC + z_ses_GMC +
    (1 | school_class) + (1 | school),
  data = achieve_3L_data,
  REML = FALSE
)

lmerES_3L(three_level_fit)

data("achieve_3L_data")

three_level_fit <- lmerTest::lmer(
  geread ~ z_gevocab_CMC + gender_eff +
    z_gemath_agg_CMC + z_ptratio_CMC + z_ses_GMC +
    (1 | school_class) + (1 | school),
  data = achieve_3L_data,
  REML = FALSE
)

lmerES_3L(three_level_fit)

R-Squared Measures for 2-Level Linear Multilevel Models

Description

Returns R-squared values for the variance sources in a 2-level hierarchical linear model fitted with lme4::lmer. Level-specific values use the variance sources associated with L1 or L2; total values use all L1 and L2 variance sources.

Usage

lmerRsq(model, verbose = TRUE)
lmerRsq(model, verbose = TRUE)

Arguments

model

A 2-level linear model fitted with lme4::lmer.

verbose

Logical; if TRUE (default), prints a note explaining column abbreviations.

Details

Rows beginning with FE_L1, FE_L2, RS_L1, or RI_L2 give R-squared values for a single variance source. Rows beginning with FE_total, FE_RS_total, or FE_RS_RI_total combine the indicated fixed- and random-effects variance sources.

Value

A data frame with R-squared values for each variance source or combination of sources:

Effect: Variance source or combination of sources.
TotalRsq: Proportion of total variance explained.
L1Rsq: Proportion of L1 variance explained.
L2Rsq: Proportion of L2 variance explained.

References

Bates, D., Mächler, M., Bolker, B., & Walker, S. (2015). Fitting linear mixed-effects models using lme4. Journal of Statistical Software, 67(1), 1–48. doi:10.18637/jss.v067.i01

Examples

data("hsb_data")

hsb_m1c <- lme4::lmer(mathach ~
    minority_eff_CMC + female_eff_CMC + z_ses_CMC +
    z_ses_agg_GMC +
    z_sqrt_size_GMC + sector_eff + z_disclim_GMC + himinty_eff +
    (1 + minority_eff_CMC + female_eff_CMC + z_ses_CMC | school),
  data = hsb_data, REML = FALSE,
  control = lme4::lmerControl(optimizer = "bobyqa",
                              optCtrl = list(maxfun = 2e5)))

lmerRsq(hsb_m1c)

data("hsb_data")

hsb_m1c <- lme4::lmer(mathach ~
    minority_eff_CMC + female_eff_CMC + z_ses_CMC +
    z_ses_agg_GMC +
    z_sqrt_size_GMC + sector_eff + z_disclim_GMC + himinty_eff +
    (1 + minority_eff_CMC + female_eff_CMC + z_ses_CMC | school),
  data = hsb_data, REML = FALSE,
  control = lme4::lmerControl(optimizer = "bobyqa",
                              optCtrl = list(maxfun = 2e5)))

lmerRsq(hsb_m1c)

R-Squared Measures for 3-Level Linear Multilevel Models

Description

Returns R-squared values for the variance sources in a 3-level hierarchical linear model fitted with lme4::lmer. Level-specific values use the variance sources associated with L1, L2, or L3; total values use all three levels.

Usage

lmerRsq_3L(model, verbose = TRUE)
lmerRsq_3L(model, verbose = TRUE)

Arguments

model

A 3-level linear model fitted with lme4::lmer.

verbose

Logical; if TRUE (default), prints a note explaining column abbreviations.

Details

Rows beginning with FE, L1_RS, L2_RS, or RI give R-squared values for the indicated variance source. Rows containing total combine fixed- and random-effects variance sources across levels.

Value

A data frame with R-squared values for each variance source or combination of sources:

Effect: Variance source or combination of sources.
TotalRsq: Proportion of total variance explained.
L1Rsq: Proportion of L1 variance explained.
L2Rsq: Proportion of L2 variance explained.
L3Rsq: Proportion of L3 variance explained.

References

Bates, D., Mächler, M., Bolker, B., & Walker, S. (2015). Fitting linear mixed-effects models using lme4. Journal of Statistical Software, 67(1), 1–48. doi:10.18637/jss.v067.i01

Examples

data("achieve_3L_data")

three_level_fit <- lme4::lmer(
  geread ~ z_gevocab_CMC + gender_eff +
    z_gemath_agg_CMC + z_ptratio_CMC + z_ses_GMC +
    (1 | school_class) + (1 | school),
  data = achieve_3L_data,
  REML = FALSE
)

lmerRsq_3L(three_level_fit)

data("achieve_3L_data")

three_level_fit <- lme4::lmer(
  geread ~ z_gevocab_CMC + gender_eff +
    z_gemath_agg_CMC + z_ptratio_CMC + z_ses_GMC +
    (1 | school_class) + (1 | school),
  data = achieve_3L_data,
  REML = FALSE
)

lmerRsq_3L(three_level_fit)

Variance Components for 2-Level Linear Multilevel Models

Description

Returns the variance components used to calculate model-based effect sizes for a 2-level hierarchical linear model fitted with lme4::lmer. The components are L1 and L2 fixed-effects variance, L1 random-slopes variance, conditional L2 random-intercept variance, and residual L1 variance.

Usage

lmerVarComp(model, verbose = TRUE)
lmerVarComp(model, verbose = TRUE)

Arguments

model

A 2-level linear model fitted with lme4::lmer.

verbose

Logical; if TRUE (default), prints a note explaining column abbreviations.

Details

Value

A data frame with rows for L1, L2, and all variance sources:

level: Variance level: L1, L2, or All.
FE_Var: Fixed-effects variance.
L1_Resid_Var: Residual L1 variance.
L1_RS_Var: L1 random-slopes variance.
L2_RI_Var: Conditional L2 random-intercept variance.
TotVar: Variance for the specified level.
SD: Square root of TotVar.

References

Bates, D., Mächler, M., Bolker, B., & Walker, S. (2015). Fitting linear mixed-effects models using lme4. Journal of Statistical Software, 67(1), 1–48. doi:10.18637/jss.v067.i01

Examples

data("hsb_data")

hsb_m1c <- lme4::lmer(mathach ~
    minority_eff_CMC + female_eff_CMC + z_ses_CMC +
    z_ses_agg_GMC +
    z_sqrt_size_GMC + sector_eff + z_disclim_GMC + himinty_eff +
    (1 + minority_eff_CMC + female_eff_CMC + z_ses_CMC | school),
  data = hsb_data, REML = FALSE,
  control = lme4::lmerControl(optimizer = "bobyqa",
                              optCtrl = list(maxfun = 2e5)))

lmerVarComp(hsb_m1c)

data("hsb_data")

hsb_m1c <- lme4::lmer(mathach ~
    minority_eff_CMC + female_eff_CMC + z_ses_CMC +
    z_ses_agg_GMC +
    z_sqrt_size_GMC + sector_eff + z_disclim_GMC + himinty_eff +
    (1 + minority_eff_CMC + female_eff_CMC + z_ses_CMC | school),
  data = hsb_data, REML = FALSE,
  control = lme4::lmerControl(optimizer = "bobyqa",
                              optCtrl = list(maxfun = 2e5)))

lmerVarComp(hsb_m1c)

Variance Components for 3-Level Linear Multilevel Models

Description

Returns the variance components used to calculate model-based effect sizes for a 3-level hierarchical linear model fitted with lme4::lmer. Components are reported for L1, L2, L3, and all variance sources.

Usage

lmerVarComp_3L(model, verbose = TRUE)
lmerVarComp_3L(model, verbose = TRUE)

Arguments

model

A 3-level linear model fitted with lme4::lmer.

verbose

Logical; if TRUE (default), prints a note explaining column abbreviations.

Details

This function extends the 2-level variance decomposition described by Sanders, Konold, and Cheng (in press) to three levels.

Value

A data frame with rows for L1, L2, L3, and all variance sources:

levels: Variance level: L1, L2, L3, or All.
FE_Var: Fixed-effects variance.
L1_Resid_Var: Residual L1 variance.
L1_RS_L2_Var: Variance from L1 slopes varying across L2 units.
L1_RS_L3_Var: Variance from L1 slopes varying across L3 units. When an L1 and an L2 predictor both have random slopes at L3, their slope contributions covary, and the full L3 slope variance exceeds the sum of the two separate variances by twice that covariance. This component includes one copy of the covariance and L2_RS_Var includes the other, so the two together account for the full L3 slope variance. Under the cluster-mean centering the framework assumes, the covariance is exactly zero and this term is the plain variance.
L2_RI_Var: Conditional L2 random-intercept variance.
L2_RS_Var: Variance from L2 slopes varying across L3 units. Includes the second copy of the covariance described under L1_RS_L3_Var.
L3_RI_Var: Conditional L3 random-intercept variance.
TotVar: Variance for the specified level.
SD: Square root of TotVar.

References

Bates, D., Mächler, M., Bolker, B., & Walker, S. (2015). Fitting linear mixed-effects models using lme4. Journal of Statistical Software, 67(1), 1–48. doi:10.18637/jss.v067.i01

Examples

data("achieve_3L_data")

three_level_fit <- lme4::lmer(
  geread ~ z_gevocab_CMC + gender_eff +
    z_gemath_agg_CMC + z_ptratio_CMC + z_ses_GMC +
    (1 | school_class) + (1 | school),
  data = achieve_3L_data,
  REML = FALSE
)

lmerVarComp_3L(three_level_fit)

data("achieve_3L_data")

three_level_fit <- lme4::lmer(
  geread ~ z_gevocab_CMC + gender_eff +
    z_gemath_agg_CMC + z_ptratio_CMC + z_ses_GMC +
    (1 | school_class) + (1 | school),
  data = achieve_3L_data,
  REML = FALSE
)

lmerVarComp_3L(three_level_fit)

Effect Sizes from 2-Level Bayesian Multilevel Models

Description

Computes model-based coefficient effect sizes, variance components, and R-squared values from posterior summaries of a 2-level model fitted with brms::brm.

Usage

brms_lmerVarComp(model, robust = TRUE, probs = 0.95, verbose = TRUE)

brms_lmerRsq(model, robust = TRUE, probs = 0.95, verbose = TRUE)

brms_lmerES(model, robust = TRUE, method = "HDI", probs = 0.95, verbose = TRUE)
brms_lmerVarComp(model, robust = TRUE, probs = 0.95, verbose = TRUE)

brms_lmerRsq(model, robust = TRUE, probs = 0.95, verbose = TRUE)

brms_lmerES(model, robust = TRUE, method = "HDI", probs = 0.95, verbose = TRUE)

Arguments

model

A 2-level Gaussian or Bernoulli model fitted with brms::brm.

robust

Logical; if TRUE (default), posterior locations are summarized by the median and posterior scales by the median absolute deviation.

probs

Numeric scalar giving the posterior interval probability. Default is 0.95.

verbose

Logical; if TRUE (default), prints a note explaining column abbreviations.

method

Character; method for computing credible intervals, passed to bayestestR::ci. Used for the coefficient intervals returned by brms_lmerES. Default is "HDI".

Details

These functions apply the 2-level variance-decomposition calculations to posterior point summaries. Use brms_lmerES_ci, brms_lmerVarComp_ci, or brms_lmerRsq_ci for intervals calculated from posterior draws.

For Bernoulli models, the effect sizes and variance components are on the latent scale. Observation-level variance is based on the mean response probability approximation described by McCulloch, Searle, and Neuhaus (2008).

Predictors should be centered, z-scored, and effect-coded as described in lmerES. All functions require brms; brms_lmerES also requires bayestestR.

Value

brms_lmerES returns coefficient posterior summaries, coefficient interval bounds, R-hat, and the columns d_lev, d_tot, sr2_lev, and sr2_tot. The effect sizes are calculated from posterior point summaries.

brms_lmerVarComp returns rows for L1, L2, and all variance sources, with columns level, L1_FE_Var, L1_Resid_Var, L1_RS_Var, L2_RI_Var, TotVar, and SD.

brms_lmerRsq returns Effect, TotalRsq, L1Rsq, and L2Rsq. R-squared values are proportions calculated from posterior point summaries.

References

Bürkner, P.-C. (2017). brms: An R package for Bayesian multilevel models using Stan. Journal of Statistical Software, 80(1), 1–28. doi:10.18637/jss.v080.i01

Makowski, D., Ben-Shachar, M. S., & Lüdecke, D. (2019). bayestestR: Describing effects and their uncertainty, existence and significance within the Bayesian framework. Journal of Open Source Software, 4(40), 1541. doi:10.21105/joss.01541

McCulloch, C. E., Searle, S. R., & Neuhaus, J. M. (2008). Generalized, linear, and mixed models (2nd ed.). Wiley.

Examples


if (requireNamespace("brms", quietly = TRUE) &&
    requireNamespace("bayestestR", quietly = TRUE)) {
  data("hsb_data")

  hsb_brm_m1c <- brms::brm(mathach ~
      minority_eff_CMC + female_eff_CMC + z_ses_CMC +
      z_ses_agg_GMC +
      z_sqrt_size_GMC + sector_eff + z_disclim_GMC + himinty_eff +
      (1 + minority_eff_CMC + female_eff_CMC + z_ses_CMC | school),
    data = hsb_data, family = gaussian(),
    chains = 2, iter = 2000, warmup = 1000, cores = 2, seed = 212931)

  brms_lmerVarComp(hsb_brm_m1c)
  brms_lmerES(hsb_brm_m1c)
  brms_lmerRsq(hsb_brm_m1c)
}


if (requireNamespace("brms", quietly = TRUE) &&
    requireNamespace("bayestestR", quietly = TRUE)) {
  data("hsb_data")

  hsb_brm_m1c <- brms::brm(mathach ~
      minority_eff_CMC + female_eff_CMC + z_ses_CMC +
      z_ses_agg_GMC +
      z_sqrt_size_GMC + sector_eff + z_disclim_GMC + himinty_eff +
      (1 + minority_eff_CMC + female_eff_CMC + z_ses_CMC | school),
    data = hsb_data, family = gaussian(),
    chains = 2, iter = 2000, warmup = 1000, cores = 2, seed = 212931)

  brms_lmerVarComp(hsb_brm_m1c)
  brms_lmerES(hsb_brm_m1c)
  brms_lmerRsq(hsb_brm_m1c)
}

Posterior Intervals for Effect Sizes from 2-Level Bayesian Models

Description

Computes posterior intervals for model-based coefficient effect sizes, variance components, and R-squared values from a 2-level model fitted with brms::brm.

Usage

brms_lmerVarComp_ci(
  model,
  robust = TRUE,
  method = "HDI",
  probs = 0.95,
  verbose = TRUE
)

brms_lmerRsq_ci(
  model,
  robust = TRUE,
  method = "HDI",
  probs = 0.95,
  verbose = TRUE
)

brms_lmerES_ci(
  model,
  robust = TRUE,
  method = "HDI",
  probs = 0.95,
  verbose = TRUE
)
brms_lmerVarComp_ci(
  model,
  robust = TRUE,
  method = "HDI",
  probs = 0.95,
  verbose = TRUE
)

brms_lmerRsq_ci(
  model,
  robust = TRUE,
  method = "HDI",
  probs = 0.95,
  verbose = TRUE
)

brms_lmerES_ci(
  model,
  robust = TRUE,
  method = "HDI",
  probs = 0.95,
  verbose = TRUE
)

Arguments

model

A 2-level Gaussian or Bernoulli model fitted with brms::brm.

robust

Logical; passed to the brms posterior summaries used during model setup. Default is TRUE.

method

Character; method for computing credible intervals, passed to bayestestR::ci. Default is "HDI".

probs

Numeric; probability for credible intervals. Default is 0.95.

verbose

Logical; if TRUE (default), prints a note explaining column abbreviations.

Details

Intervals are calculated from posterior draws of the corresponding quantities; the returned tables do not include point estimates. For Bernoulli models, the quantities are on the latent scale.

Predictors should be centered, z-scored, and effect-coded as described in lmerES. These functions require brms and bayestestR.

Value

brms_lmerES_ci returns Variable, Level, and RS, followed by lower and upper posterior interval bounds for d_lev, d_tot, sr2_lev, and sr2_tot.

brms_lmerVarComp_ci returns rows for L1, L2, and all variance sources, with lower and upper posterior interval bounds for each variance component, TotVar, and SD.

brms_lmerRsq_ci returns Effect and lower and upper posterior interval bounds for TotalRsq, L1Rsq, and L2Rsq. R-squared values are proportions.

References

Bürkner, P.-C. (2017). brms: An R package for Bayesian multilevel models using Stan. Journal of Statistical Software, 80(1), 1–28. doi:10.18637/jss.v080.i01

McCulloch, C. E., Searle, S. R., & Neuhaus, J. M. (2008). Generalized, linear, and mixed models (2nd ed.). Wiley.

Examples


if (requireNamespace("brms", quietly = TRUE) &&
    requireNamespace("bayestestR", quietly = TRUE)) {
  data("hsb_data")

  hsb_brm_m1c <- brms::brm(mathach ~
      minority_eff_CMC + female_eff_CMC + z_ses_CMC +
      z_ses_agg_GMC +
      z_sqrt_size_GMC + sector_eff + z_disclim_GMC + himinty_eff +
      (1 + minority_eff_CMC + female_eff_CMC + z_ses_CMC | school),
    data = hsb_data, family = gaussian(),
    chains = 2, iter = 2000, warmup = 1000, cores = 2, seed = 212931)

  brms_lmerVarComp_ci(hsb_brm_m1c)
  brms_lmerES_ci(hsb_brm_m1c)
  brms_lmerRsq_ci(hsb_brm_m1c)
}


if (requireNamespace("brms", quietly = TRUE) &&
    requireNamespace("bayestestR", quietly = TRUE)) {
  data("hsb_data")

  hsb_brm_m1c <- brms::brm(mathach ~
      minority_eff_CMC + female_eff_CMC + z_ses_CMC +
      z_ses_agg_GMC +
      z_sqrt_size_GMC + sector_eff + z_disclim_GMC + himinty_eff +
      (1 + minority_eff_CMC + female_eff_CMC + z_ses_CMC | school),
    data = hsb_data, family = gaussian(),
    chains = 2, iter = 2000, warmup = 1000, cores = 2, seed = 212931)

  brms_lmerVarComp_ci(hsb_brm_m1c)
  brms_lmerES_ci(hsb_brm_m1c)
  brms_lmerRsq_ci(hsb_brm_m1c)
}

Effect Sizes for 2-Level Binary Logistic Multilevel Models

Description

Computes model-based coefficient effect sizes, variance components, and R-squared values for a 2-level binary logistic model fitted with lme4::glmer. The calculations use a latent-scale variance decomposition.

Usage

glmerES(model, verbose = TRUE)

glmerVarComp(model, verbose = TRUE)

glmerRsq(model, verbose = TRUE)
glmerES(model, verbose = TRUE)

glmerVarComp(model, verbose = TRUE)

glmerRsq(model, verbose = TRUE)

Arguments

model

A fitted model object from lme4::glmer with 2-level structure and binomial family with logit link.

verbose

Logical; if TRUE (default), prints a note explaining column abbreviations.

Details

The standardized mean difference and squared semi-partial correlation follow the definitions used for linear models, but their denominators are based on latent variance. The mean response probability is approximated from the model intercept and random-effects variance following McCulloch, Searle, and Neuhaus (2008). Observation-level variance is then calculated as $1 / \{\bar p(1 - \bar p)\}$ .

L1 predictors should be cluster-mean-centered. Continuous L1 and L2 predictors should be z-scored after centering, and categorical predictors should be effect-coded.

Value

glmerES returns a data frame with the following columns:

Variable: Predictor name.
Level: Predictor level: 1 or 2.
RS: Random-slope status: 1 = yes, 0 = no.
Coeff: Unstandardized logit coefficient.
SE: Standard error.
z: z statistic.
p: p value.
d_lev, d_tot: Standardized mean differences using level-specific and total latent variance.
sr2_lev, sr2_tot: Unique proportions of level-specific and total latent variance explained.

glmerVarComp returns rows for L1, L2, and all variance sources, with columns level, L1_FE_Var, L1_Resid_Var, L1_RS_Var, L2_RI_Var, TotVar, and SD.

glmerRsq returns Effect, TotalRsq, L1Rsq, and L2Rsq. R-squared values are proportions.

References

McCulloch, C. E., Searle, S. R., & Neuhaus, J. M. (2008). Generalized, linear, and mixed models (2nd ed.). Wiley.

Bates, D., Mächler, M., Bolker, B., & Walker, S. (2015). Fitting linear mixed-effects models using lme4. Journal of Statistical Software, 67(1), 1–48. doi:10.18637/jss.v067.i01

Examples


data("hsb_data")

cutvalue_math <- quantile(hsb_data$mathach, probs = 0.40)
hsb_data$mathach_pass <- ifelse(hsb_data$mathach >= cutvalue_math, 1, 0)

hsb_glm_m1c <- lme4::glmer(mathach_pass ~
    minority_eff_CMC + female_eff_CMC + z_ses_CMC +
    z_ses_agg_GMC +
    z_sqrt_size_GMC + sector_eff + z_disclim_GMC + himinty_eff +
    (1 + minority_eff_CMC + female_eff_CMC + z_ses_CMC | school),
  data = hsb_data,
  family = binomial,
  control = lme4::glmerControl(optimizer = "bobyqa",
                               optCtrl = list(maxfun = 2e5)))

glmerES(hsb_glm_m1c)
glmerVarComp(hsb_glm_m1c)
glmerRsq(hsb_glm_m1c)


data("hsb_data")

cutvalue_math <- quantile(hsb_data$mathach, probs = 0.40)
hsb_data$mathach_pass <- ifelse(hsb_data$mathach >= cutvalue_math, 1, 0)

hsb_glm_m1c <- lme4::glmer(mathach_pass ~
    minority_eff_CMC + female_eff_CMC + z_ses_CMC +
    z_ses_agg_GMC +
    z_sqrt_size_GMC + sector_eff + z_disclim_GMC + himinty_eff +
    (1 + minority_eff_CMC + female_eff_CMC + z_ses_CMC | school),
  data = hsb_data,
  family = binomial,
  control = lme4::glmerControl(optimizer = "bobyqa",
                               optCtrl = list(maxfun = 2e5)))

glmerES(hsb_glm_m1c)
glmerVarComp(hsb_glm_m1c)
glmerRsq(hsb_glm_m1c)

Early Reading Growth Dataset

Description

Longitudinal data from 79 children who received an individual, phonics-based reading intervention in first grade. Children were assessed at four waves over three years, beginning in the fall of first grade. Repeated observations (L1) are nested within children (L2), and the data are in long format.

Usage

data("readgrowth_data")
data("readgrowth_data")

Format

A data frame with 316 observations on 18 variables:

schnum2: School identifier
subnum2: Child identifier (level-2 unit)
ppvty1_1: Receptive vocabulary, Peabody Picture Vocabulary Test standard score
rlny1_1: Rapid letter naming, Comprehensive Test of Phonological Processing raw score
yoppy1_1: Phonemic awareness, Yopp-Singer Test of Phoneme Segmentation raw score
ppvt_GMC: Receptive vocabulary (PPVT), grand-mean-centered (L2)
rln_GMC: Rapid letter naming, grand-mean-centered (L2)
yopp_GMC: Phonemic awareness (Yopp-Singer), grand-mean-centered (L2)
z_ppvt_GMC: Receptive vocabulary (PPVT), grand-mean-centered and z-scored (L2)
z_rln_GMC: Rapid letter naming, grand-mean-centered and z-scored (L2)
z_yopp_GMC: Phonemic awareness (Yopp-Singer), grand-mean-centered and z-scored (L2)
time: Time point
WR: Woodcock-Johnson Mastery Test Word Identification raw score (outcome)
Decode: Decoding score
Spell: Spelling score
TimeLin: Linear time regressor
Rate1: Piecewise rate regressor for growth during first grade (L1)
Rate2: Piecewise rate regressor for growth during grades 2 and 3 (L1)

References

Vadasy, P. F., Sanders, E. A., & Abbott, R. D. (2008). Effects of supplemental early reading intervention at 2-year follow up: Reading skill growth patterns and predictors. Scientific Studies of Reading, 12(1), 51–89. doi:10.1080/10888430701746906

Package 'MLMES'

Help Index

Three-Level Student Achievement Dataset

Description

Usage

Format

Details

Source

References

Coefficient Effect Sizes for 3-Level Binary Logistic Multilevel Models

Description

Usage

Arguments

Details

Value

References

See Also

Examples

R-Squared Measures for 3-Level Binary Logistic Multilevel Models

Description

Usage

Arguments

Details

Value

References

See Also

Examples

Variance Components for 3-Level Binary Logistic Multilevel Models

Description

Usage

Arguments

Details

Value

References

See Also

Examples

High School and Beyond (HSB) Dataset

Description

Usage

Format

References

Coefficient Effect Sizes for 2-Level Linear Multilevel Models

Description

Usage

Arguments

Details

Value

References

See Also

Examples

Coefficient Effect Sizes for 3-Level Linear Multilevel Models

Description

Usage

Arguments

Details

Value

References

See Also

Examples

R-Squared Measures for 2-Level Linear Multilevel Models

Description

Usage

Arguments

Details

Value

References

See Also

Examples

R-Squared Measures for 3-Level Linear Multilevel Models

Description

Usage

Arguments

Details

Value

References

See Also

Examples

Variance Components for 2-Level Linear Multilevel Models

Description

Usage