misty (version 0.4.3)

multilevel.cor: Within-Group and Between-Group Correlation Matrix

Description

This function computes the within-group and between-group correlation matrix using the lavaan package and provides standard errors, z test statistics, and significance values (p-values) for testing the hypothesis H0: \(\rho\) = 0 for all pairs of variables within and between groups.

Usage

multilevel.cor(x, cluster, within = NULL, between = NULL, estimator = c("ML", "MLR"),
               na.omit = TRUE, sig = TRUE, alpha = 0.05,
               print = c("all", "cor", "se", "stat", "p"), split = FALSE,
               tri = c("both", "lower", "upper"), tri.lower = TRUE,
               p.adj = c("none", "bonferroni", "holm", "hochberg", "hommel",
                         "BH", "BY", "fdr"),
               digits = 2, p.digits = 3, as.na = NULL, check = TRUE,
               output = TRUE)

Arguments

x

a matrix or data frame.

cluster

a vector representing the nested grouping structure (i.e., group or cluster variable).

within

a character vector representing variables that are measured on the within level and modeled only on the within level. Variables not mentioned in within or between are measured on the within level and will be modeled on both the within and between level.

between

a character vector representing variables that are measured on the between level and modeled only on the between level. Variables not mentioned in within or between are measured on the within level and will be modeled on both the within and between level.

estimator

a character string indicating the estimator to be used: "ML" for maximum likelihood and "MLR" (default) for maximum likelihood with Huber-White robust standard errors. Note that incomplete cases are removed listwise (i.e., na.omit = TRUE) when using "MLR", whereas full information maximum likelihood (FIML) is used to deal with missing data when using "ML" when specifying na.omit = FALSE.

na.omit

logical: if TRUE, incomplete cases are removed before conducting the analysis (i.e., listwise deletion); if FALSE (default), full information maximum likelihood (FIML) is used when specifying estimator = "ML".

sig

logical: if TRUE (default), statistically significant correlation coefficients are shown in boldface on the console.

alpha

a numeric value between 0 and 1 indicating the significance level at which correlation coefficients are printed boldface when sig = TRUE.

print

a character string or character vector indicating which results to show on the console, i.e. "all" for all results, "cor" for correlation coefficients, "se" for standard errors, "z" for z test statistics, and "p" for p-values.

split

logical: if TRUE, output table is split in within-group and between-group correlation matrix.

tri

a character string indicating which triangular of the matrix to show on the console when split = TRUE, i.e., both for upper and lower triangular, lower (default) for the lower triangular, and upper for the upper triangular.

tri.lower

logical: if TRUE (default) and split = FALSE (default), within-group correlations are shown in the lower triangular and between-group correlation are shown in the upper triangular.

p.adj

a character string indicating an adjustment method for multiple testing based on p.adjust, i.e., none (default), bonferroni, holm, hochberg, hommel,BH, BY, or fdr.

digits

an integer value indicating the number of decimal places to be used for displaying correlation coefficients.

p.digits

an integer value indicating the number of decimal places to be used for displaying p-values.

as.na

a numeric vector indicating user-defined missing values, i.e. these values are converted to NA before conducting the analysis. Note that as.na() function is only applied to x but not to cluster.

check

logical: if TRUE, argument specification is checked.

output

logical: if TRUE, output is shown on the console.

Value

Returns an object of class misty.object, which is a list with following entries: function call (call), type of analysis (type), matrix or data frame specified in x (data), specification of function arguments (args), fitted lavaan object (mod.fit), and list with results (result).

Details

The specification of the within-group and between-group variables is in line with the syntax in Mplus. That is, the within argument is used to identify the variables in the matrix or data frame specified in x that are measured on the individual level and modeled only on the within level. They are specified to have no variance in the between part of the model. The between argument is used to identify the variables in the matrix or data frame specified in x that are measured on the cluster level and modeled only on the between level. Variables not mentioned in the arguments within or between are measured on the individual level and will be modeled on both the within and between level.

By default, the function uses robust maximum likelihood (estimator = "MLR"), i.e., maximum likelihood with Huber-White robust standard errors. When using estimator = "MLR", listwise deletion is used for missing data (na.omit = TRUE). Note that the lavaan version 0.6-9 supports full information maximum likelihood (FIML) in multilevel models for maximum likelihood (estimator = "ML"), but not for robust maximum likelihood (estimator = "MLR"). Moreover, FIML cannot be used when a within-group variables has no variance within some clusters. In this cases, listwise deletion is used even though estimator = "ML" and na.omit = FALSE was specified. Note that there might be issues in model convergence when using FIML (estimator = "ML" and na.omit = FALSE), which might be resolved when switching to listwise deletion (na.omit = TRUE).

lavaan package uses a quasi-Newton optimization method ("nlminb") by default. If the optimizer does not converge, model estimation will switch to the Expectation Maximization (EM) algorithm.

Statistically significant correlation coefficients are shown in boldface on the console (sig = TRUE). However, this option is not supported when using R Markdown, i.e., the argument sig will switch to FALSE.

Adjustment method for multiple testing when specifying the argument p.adj is applied to the within-group and between-broup correlation matrix separately.

References

Hox, J., Moerbeek, M., & van de Schoot, R. (2018). Multilevel analysis: Techniques and applications (3rd. ed.). Routledge.

Snijders, T. A. B., & Bosker, R. J. (2012). Multilevel analysis: An introduction to basic and advanced multilevel modeling (2nd ed.). Sage Publishers.

See Also

multilevel.descript, multilevel.icc, cluster.scores

Examples

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

#---------------------------
# All variables modeled on both the within and between level
multilevel.cor(Demo.twolevel[, c("y1", "y2", "y3")],
               cluster = Demo.twolevel$cluster)

# Split output table in within-group and between-group correlation matrix.
multilevel.cor(Demo.twolevel[, c("y1", "y2", "y3")],
               cluster = Demo.twolevel$cluster, split = TRUE)

# Print correlation coefficients, standard errors, z test statistics,
# and p-values
multilevel.cor(Demo.twolevel[, c("y1", "y2", "y3")],
               cluster = Demo.twolevel$cluster, print = "all")

# Print correlation coefficients and p-values
# significance values with Bonferroni correction
multilevel.cor(Demo.twolevel[, c("y1", "y2", "y3")],
               cluster = Demo.twolevel$cluster, print = c("cor", "p"),
               p.adj = "bonferroni")

#---------------------------
# Variables "y1", "y2", and "y2" modeled on both the within and between level
# Variables "w1" and "w2" modeled on the cluster level
multilevel.cor(Demo.twolevel[, c("y1", "y2", "y3", "w1", "w2")],
               cluster = Demo.twolevel$cluster,
               between = c("w1", "w2"))

#---------------------------
# Variables "y1", "y2", and "y2" modeled only on the within level
# Variables "w1" and "w2" modeled on the cluster level
multilevel.cor(Demo.twolevel[, c("y1", "y2", "y3", "w1", "w2")],
               cluster = Demo.twolevel$cluster,
               within = c("y1", "y2", "y3"), between = c("w1", "w2"))

# Summary of the multilevel model used to compute the within-group
# and between-group correlation matrix
mod <- multilevel.cor(Demo.twolevel[, c("y1", "y2", "y3")],
                      cluster = Demo.twolevel$cluster, output = FALSE)
lavaan::summary(mod$mod.fit, standardized = TRUE)
# }