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

In misty: Miscellaneous Functions 'T. Yanagida'

Within-Group and Between-Group Correlation Matrix

Description

This function computes the within-group and between-group correlation matrix by calling the sem function in the R package lavaan 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. By default, the function provides the within-group and between-group correlation matrix. Statistically significant correlations can be highlighted by specifying the argument color.

Usage

multilevel.cor(data, ..., cluster, estimator = c("ML", "MLR"), constr.var = FALSE,
               optim.method = c("nlminb", "em"), optim.switch = TRUE,
               print = c("all", "summary", "cor", "se", "stat", "p"), split = FALSE,
               order = FALSE, tri = c("both", "lower", "upper"), tri.lower = TRUE,
               missing = c("listwise", "fiml"), alpha = 0.05,
               color = "default", style = c("regular", "bold", "italic"),
               p.adj = c("none", "bonferroni", "holm", "hochberg", "hommel",
                         "BH", "BY", "fdr"),
               digits = 2, p.digits = 3, as.na = NULL, write = NULL,
               append = TRUE, check = TRUE, output = TRUE)

Arguments

data	a data frame.
...	an expression indicating the variable names in data, e.g., multilevel.cor(dat, x1, x2, x3). Note that the operators +, -, ~, :, ::, and ! can also be used to select variables, see 'Details' in the df.subset function.
cluster	either a character string indicating the variable name of the cluster variable in data, or a vector representing the nested grouping structure (i.e., group or cluster variable).
estimator	a character string indicating the estimator to be used, i.e., "ML" for maximum likelihood with conventional standard errors and "MLR" for maximum likelihood with Huber-White robust standard errors. The default setting depends on the argument color, i.e., "ML" is used when specifying color = "default" (default) and "MLR" is used when specifying a color for the argument color.
constr.var	logical: if TRUE, inequality constraints are imposed for the variance parameters at the between level, i.e., variances are constrained to be greater than 0.
optim.method	a character string indicating the optimizer, i.e., "nlminb" for the unconstrained and bounds-constrained quasi-Newton method optimizer and "em" for the Expectation Maximization (EM) algorithm. By default, the optimizer "nlminb" is used with complete data or when using listwise deletion for missing data handling, while the optimizer "em" is used when using for full information maximum likelihood (FIML) method for missing data handling.
optim.switch	logical: if TRUE (default), model estimation switches to Expectation Maximization (EM) algorithm ("em") if the quasi-Newton optimization ("nlminb") does not converge.
print	a character string or character vector indicating which results to show on the console, i.e. "all" for all results, "summary" for a summary of the specification of the estimation method and missing data handling in lavaan, "cor" (default) for correlation coefficients, "se" for standard errors, "stat" for z test statistics, and "p" for p-values. By default, the function only prints the within-group and between-group correlation matrix.
split	logical: if TRUE, output table is split in within-group and between-group correlation matrix.
order	logical: if TRUE, variables in the output table are ordered, so that variables specified in the argument between are shown first.
tri	a character string indicating which triangular of the matrix to show on the console when split = TRUE, i.e., both for upper 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.
missing	a character string indicating how to deal with missing data, i.e., "listwise" for listwise deletion or "fiml" (default) for full information maximum likelihood (FIML) method. Note that it takes longer to estimate models while using FIML and using FIML is prone to issues with model convergence, these issues might be resolved by switching to listwise deletion.
alpha	a numeric value between 0 and 1 indicating the significance level at which correlation coefficients are printed boldface when when specifying the argument color.
color	a character string indicating the text color for highlighting statistically significant correlation coefficients , i.e., "default" (default) for the default text color without color coding and various text colors for highlighting like "red", "b.red", "green", "b.green", "blue", or "b.blue", see the help page of the chr.color function. Note that this option is not supported when using R Markdown and when writing the output into a text file (.txt).
style	a character vector indicating the font style for statistically significant correlation coefficients, i.e., "regular" (default) for regular text, "bold" for bold text, and "italic" for italic text. Note that the font style "bold" and "italic" can be combined, i.e., style = c("bold", "italic") provides a bold and italic text. Note that the argument color needs to be specified to change the style of the text, e.g. color = "black" and style = "bold" to for bold text.
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 data but not to cluster.
write	a character string naming a file for writing the output into either a text file with file extension ".txt" (e.g., "Output.txt") or Excel file with file extension ".xlsx" (e.g., "Output.xlsx"). If the file name does not contain any file extension, an Excel file will be written.
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.

Details

Within-Group and Between-Group Variables

The function automatically identifies (1) variables in the data frame specified in data that are measured at the individual level and modeled only at the within level and (2) variables in the data frame specified in data that are measured at the cluster level and modeled only at the between level. The former variables have no variance in the between part of the model (i.e., ICC(1) is 0 e.g. due to centering within clusters), while the latter variables do not have any variance within clusters.

Estimation Method

The default setting for the argument estimator is depending on the setting of the argument color. If color = "default" (default), maximum likelihood estimation (estimator = "ML") is used, while maximum likelihood with Huber-White robust standard errors (estimator = "MLR") that are robust against non-normality is used when when specifying a color for the argument color.

Missing Data Handling

In the presence of missing data, full information maximum likelihood (FIML) method (missing = "fiml") is used by default. Note that FIML method cannot deal with within-group variables that have no variance within some clusters. In this cases, the function will switch to listwise deletion. Using FIML method might result in issues with model convergence, which might be resolved by switching to listwise deletion (missing = "listwise").

Optimizer

The lavaan package uses a quasi-Newton optimization method ("nlminb") by default. If the optimizer does not converge, model estimation switches to the Expectation Maximization (EM) algorithm ("em") if the argument optim.switch is specified as TRUE (default).

Statistical Significance

Statistically significant correlation coefficients can be shown color coded on the console by specifying the argument color. However, this option is not supported when using R Markdown.

Adjustment Method for Multiple Testing

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

Value

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

call	function call
type	type of analysis
data	data frame specified in data including the group variable specified in cluster
args	specification of function arguments
model.fit	fitted lavaan object (mod.fit)
result	list with result tables, i.e., summary for the specification of the estimation method and missing data handling in lavaan, wb.cor for the within- and between-group correlations, wb.se for the standard error of the within- and between-group correlations, wb.stat for the test statistic of within- and between-group correlations, wb.p for the significance value of the within- and between-group correlations, with.cor for the within-group correlations, with.se for the standard error of the within-group correlations, with.stat for the test statistic of within-group correlations, with.p for the significance value of the within-group correlations, betw.cor for the between-group correlations, betw.se for the standard error of the between-group correlations, betw.stat for the test statistic of between-group correlations, betw.p for the significance value of the between-group correlations

Note

The function uses the functions sem, lavInspect, lavMatrixRepresentation, lavTech, parameterEstimates, and standardizedsolution provided in the R package lavaan by Yves Rosseel (2012).

Author(s)

Takuya Yanagida [e-mail]

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

write.result, multilevel.descript, multilevel.icc, cluster.scores

Examples

## Not run: 

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

#————————————————————————————————————————————————————————————————————————————
# Cluster Variable Specification

# Example 1a: Specification using the argument '...'
multilevel.cor(Demo.twolevel, y1, y2, y3, cluster = "cluster")

# Example 1b: Alternative specification with cluster variable 'cluster' in 'data'
multilevel.cor(Demo.twolevel[, c("y1", "y2", "y3", "cluster")], cluster = "cluster")

# Example 1c: Alternative specification with cluster variable 'cluster' not in 'data'
multilevel.cor(Demo.twolevel[, c("y1", "y2", "y3")], cluster = Demo.twolevel$cluster)

#————————————————————————————————————————————————————————————————————————————
# Arguments 'color', 'style', 'split', 'print', and 'p.adj'

# Example 2a: Highlight statistically significant result in bright red
multilevel.cor(Demo.twolevel, y1, y2, y3, cluster = "cluster", color = "b.red")

# Example 2b: Highlight statistically significant result in boldface
multilevel.cor(Demo.twolevel, y1, y2, y3, cluster = "cluster", color = "black",
               style = "bold")

# Example 3: Split output table in within-group and between-group correlation matrix
multilevel.cor(Demo.twolevel, y1, y2, y3, cluster = "cluster", split = TRUE,
               color = "green", style = "bold")

# Example 4a: Print summary of the lavaan specification and all results
multilevel.cor(Demo.twolevel, y1, y2, y3, cluster = "cluster", print = "all")

# Example 4b: Print summary of the lavaan specification and correlation coefficients
multilevel.cor(Demo.twolevel, y1, y2, y3, cluster = "cluster", print = c("summary", "cor"))

# Example 5: Significance values with Bonferroni correction
multilevel.cor(Demo.twolevel, y1, y2, y3, cluster = "cluster", print = c("cor", "p"),
               p.adj = "bonferroni")

#————————————————————————————————————————————————————————————————————————————
# Variables Measured at the Within and Cluster Level

# Example 6a: Variables "y1", "y2", and "y2" modeled at both the within and between level
#             Variables "w1" and "w2" modeled at the cluster level
multilevel.cor(Demo.twolevel, y1, y2, y3, w1, w2, cluster = "cluster")

# Example 6b: Print cluster level variables first
multilevel.cor(Demo.twolevel, y1, y2, y3, w1, w2, cluster = "cluster", order = TRUE)

#————————————————————————————————————————————————————————————————————————————
# lavaan Model and Summary of the Estimated Model

# Example 7: lavaan model and summary of the multilevel model used to compute
#             the within-group and between-group correlation matrix
mod <- multilevel.cor(Demo.twolevel, y1, y2, y3, cluster = "cluster", output = FALSE)

# lavaan model syntax
mod$model

# Fitted lavaan object
lavaan::summary(mod$model.fit, standardized = TRUE)

#————————————————————————————————————————————————————————————————————————————
# Write Results

# Example 8a: Write Results into a text file
multilevel.cor(Demo.twolevel, y1, y2, y3, cluster = "cluster",
               write = "Multilevel_Correlation.txt")

# Example 8b: Write Results into a Excel file
multilevel.cor(Demo.twolevel, y1, y2, y3, cluster = "cluster",
               write = "Multilevel_Correlation.xlsx")

## End(Not run)

misty documentation built on Aug. 2, 2026, 9:06 a.m.