hlmer: lmer wrapper to produce HLM7-style output
In jadahlke/hlmer: HLM7-Style Output from LME4 Analyses

Description Usage Arguments Value Examples

This function is a wrapper for lmer() to formulate a mixed-effects linear model based on user-supplied variables. In addition to the output from lmer(), hlmer() also provides estimates of ICC statistics, random-effect reliability estimates, confidence intervals for fixed effects, and chi-square tests for random-effects variance. A key feature of hlmer() is that it can automate the process of centering predictors and creating variables from the cluster means of level-1 predictors to be included in level 2 of the model. The model_type argument can be used to specify one of four pre-formatted types of models (using arguments of 1, 2, 3, or 4) or to compute the complete model implied by other arguments (using a 0 argument). Variables that are cluster-mean centered within this function will be labeled with a "cwc" suffix (abbreviation for centered within cluster) and variables that are grand-mean centered within this function will be labeled with a "cgm" suffix (abbreviation for centered grand mean).

hlmer(y_lvl1, cluster, x_lvl1 = NULL, x_lvl2 = NULL, y_lvl2 = NULL,
  fixed_lvl1 = FALSE, center_lvl1 = NULL, center_lvl2 = FALSE,
  y_lvl1means = NULL, center_lvl1means = FALSE, conf_level = 0.95,
  cred_level = 0.95, model_type = 0, remove_missing = TRUE,
  check_lvl1_variance = TRUE, data, ...)

`y_lvl1`	Column label of `data` corresponding to the criterion variable for level-1 observations.
`cluster`	Column label of `data` corresponding to the cluster/group identification variable.
`x_lvl1`	Column label(s) of `data` corresponding to the predictor variable(s) for level-1 observations.
`x_lvl2`	Column label(s) of `data` corresponding to the predictor variable(s) for level-2 observations.
`y_lvl2`	Optional list of level-1 statistics to be explained by level-2 predictors. Acceptable inputs are a scalar value of "all" (indicates that all level 2 predictors should be used to predict all random effects), "intercepts" (indicates that all level 2 predictors should be used to predict random intercepts), "slopes" (indicates that all level 2 predictors should be used to predict all random slopes), or a list of vectors naming "Intercept" and/or `x_lvl1` random-effect variable names - vectors in this list must be named using `x_lvl2` variable names.
`fixed_lvl1`	Logical scalar or vector indicating which of the `x_lvl1` variables should be modeled as fixed effects (`TRUE`) or random effects (`FALSE`; default).
`center_lvl1`	Optional vector identifying the types of mean centering procedures to be applied to the `x_lvl1` variables. Options are "cluster" (within-cluster mean centering), "grand" (grand-mean centering), and "none" (no centering; default).
`center_lvl2`	Vector or scalar identifying the types of mean centering procedures to be applied to the `x_lvl2` variables. Options are `TRUE` (grand-mean centering) or `FALSE` (no centering; default).
`y_lvl1means`	Optional list of level-1 statistics to be explained by level-1 predictor mean values (only relevant when one or more level-1 predictors are cluster-mean centered). Acceptable formats for this argument are the same as for `y_lvl2`, with the exeption that lists supplied for this argument should contain vectors named using `x_lvl1` variable names.
`center_lvl1means`	Vector or scalar identifying the types of mean centering procedures to be applied to the means of `x_lvl1` variables. Options are `TRUE` (grand-mean centering) or `FALSE` (no centering; default). If this argument is supplied as a vector, it should have as many elements as there are cluster-mean centered level-1 predictors.
`conf_level`	Confidence level to use in constructing confidence bounds around fixed effects.
`cred_level`	Credibility level to use in constructing credibility bounds (ranges of plausible values for random coefficients) around random effects.
`model_type`	Numeric scalar indicating which of the following model types to run: (0) the complete model implied by the supplied arguments (default), (1) unconditional model (i.e,. random-effects ANOVA), (2) means-as-outcomes model (requrires that at least one level-2 predictor is available, either from specification using the `x_lvl2` argument or from cluster-mean centering at least one level-1 predictor using the `center_lvl1` argument), (3) random coefficients model (requires that at least one entry supplied for `fixed_lvl1` is `FALSE`), (5) slopes and/or intercepts as outcomes model (requires at least one level-2 predictor or cluster-mean centered level-1 predictor and/or at least one cross-level interaction specified using `y_lvl2` and `y_lvl1means`).
`remove_missing`	Logical scalar that determines whether cases with missing data should be omitted.
`check_lvl1_variance`	Logical scalar that determines whether clusters with no variance in level-1 predictors should be screened out.
`data`	Data frame, matrix, or tibble containing the data to use in the linear model.
`...`	Additional arugments to be passed to the `lme4::lmer()` function.

Output from the lmerTest::lmer() function augmented with ICC statistics, random-effects reliability estimates, confidence intervals for fixed effects, and chi-square tests for random-effects variance.

## Not run: 
## Unconditional model (Raudenbush and Bryk Table 4.2):
hlmer(y_lvl1 = "MATHACH", cluster = "ID", model_type = 1, data = hsb)

## Means-as-outcomes model (Raudenbush and Bryk Table 4.3):
hlmer(y_lvl1 = "MATHACH", cluster = "ID", x_lvl2 = "MEANSES",
y_lvl2 = "intercepts", model_type = 2, data = hsb)

## Random-coefficients model (Raudenbush and Bryk Table 4.4):
hlmer(y_lvl1 = "MATHACH", cluster = "ID", x_lvl1 = "SES",
center_lvl1 = "cluster", model_type = 3, data = hsb)

## Slopes and intercepts as outcomes model (Raudenbush and Bryk Table 4.5):
hlmer(y_lvl1 = "MATHACH", cluster = "ID", x_lvl1 = "SES",
x_lvl2 = "SECTOR", center_lvl1 = "cluster", y_lvl2 = "all",
y_lvl1means = "all", model_type = 4, data = hsb)

## For a more complex model, we can specify which level-2 predictors
## should be used to predict which level-1 random effects.
## In this TIMSS example, the level-1 predictor is "self_efy" and
## the level-2 predictors are "students" and "alg." If we want to
## predict level-1 intercepts using both level-2 predictors, but we
## only want to predict level-1 "self_efy" slopes using "students,"
## we can specify that by passing a list to "y_lvl2" of the form:
##
## y_lvl2 = list(students = c("Intercept", "self_efy"),
##               alg = "Intercept")
##
## This tells the program exactly which random effects to explain:
hlmer(y_lvl1 = "scores", cluster = "idteach",
      x_lvl1 = "self_efy", x_lvl2 = c("students", "alg"),
      center_lvl1 = "cluster", center_lvl2 = TRUE,
      y_lvl2 = list(students = c("Intercept", "self_efy"),
                    alg = "Intercept"),
      y_lvl1means = "intercepts", data = timss)

## End(Not run)