multilevel.omega: Multilevel Composite Reliability

Description

This function computes point estimate and Monte Carlo confidence interval for the multilevel composite reliability defined by Lai (2021) for a within-cluster construct, shared cluster-level construct, and configural cluster construct by calling the cfa function in the R package lavaan.

Usage

multilevel.omega(..., data = NULL, cluster, rescov = NULL,
                 const = c("within", "shared", "config"),
                 fix.resid = NULL, optim.method = c("nlminb", "em"),
                 missing = c("listwise", "fiml"), nrep = 100000, seed = NULL,
                 conf.level = 0.95, print = c("all", "omega", "item"),
                 digits = 2, as.na = NULL, write = NULL, append = TRUE,
                 check = TRUE, output = TRUE)

Value

call: function call
type: type of analysis
data: data frame specified in x including the group variable specified in cluster
args: specification of function arguments
model: specified model
model.fit: fitted lavaan object (mod.fit)
check: results of the convergence and model identification check
result: list with result tables, i.e., omega for the coefficient omega including Monte Carlo confidence interval and itemstat for descriptive statistics

Arguments

...: a matrix or data frame. Multilevel confirmatory factor analysis based on a measurement model with one factor at the Within level and one factor at the Between level comprising all variables in the matrix or data frame is conducted. Note that the cluster variable specified in cluster is excluded from x when specifying the argument cluster using the variable name of the cluster variable. Alternatively, an expression indicating the variable names in data e.g., multilevel.omega(x1, x2, x3, data = dat, cluster = "cluster"). Note that the operators ., +, -, ~, :, ::, and ! can also be used to select variables, see 'Details' in the df.subset function.
data: a data frame when specifying one or more variables in the argument .... Note that the argument is NULL when specifying a matrix or data frame for the argument ....
cluster: either a character string indicating the variable name of the cluster variable in ... or data, or a vector representing the nested grouping structure (i.e., group or cluster variable).
rescov: a character vector or a list of character vectors for specifying residual covariances at the Within level, e.g. rescov = c("x1", "x2") for specifying a residual covariance between indicators x1 and x2 at the Within level or rescov = list(c("x1", "x2"), c("x3", "x4")) for specifying residual covariances between indicators x1 and x2, and indicators x3 and x4 at the Within level. Note that residual covariances at the Between level cannot be specified using this function.
const: a character string indicating the type of construct(s), i.e., "within" for within-cluster constructs, "shared" for shared cluster-level constructs, and "config" (default) for configural cluster constructs.
fix.resid: a character vector for specifying residual variances to be fixed at 0 at the Between level, e.g., fix.resid = c("x1", "x3") to fix residual variances of indicators x1 and x2 at the Between level at 0. Note that it is also possible to specify fix.resid = "all" which fixes all residual variances at the Between level at 0 in line with the strong factorial measurement invariance assumption across cluster.
optim.method: a character string indicating the optimizer, i.e., "nlminb" (default) for the unconstrained and bounds-constrained quasi-Newton method optimizer and "em" for the Expectation Maximization (EM) algorithm.
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.
nrep: an integer value indicating the number of Monte Carlo repetitions for computing confidence intervals.
seed: a numeric value specifying the seed of the random number generator for computing the Monte Carlo confidence interval.
conf.level: a numeric value between 0 and 1 indicating the confidence level of the interval.
print: a character vector indicating which results to show, i.e. "all" (default), for all results "omega" for omega, and "item" for item statistics.
digits: an integer value indicating the number of decimal places to be used for displaying results. Note that loglikelihood, information criteria and chi-square test statistic is printed with digits minus 1 decimal places.
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.
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, convergence and model identification is checked.
output: logical: if TRUE (default), output is shown.

Author

Takuya Yanagida takuya.yanagida@univie.ac.at

References

Lai, M. H. C. (2021). Composite reliability of multilevel data: It’s about observed scores and construct meanings. Psychological Methods, 26(1), 90–102. https://doi.org/10.1037/met0000287

Rosseel, Y. (2012). lavaan: An R Package for Structural Equation Modeling. Journal of Statistical Software, 48, 1-36. https://doi.org/10.18637/jss.v048.i02

Venables, W. N., Ripley, B. D. (2002).Modern Applied Statistics with S (4th ed.). Springer. https://www.stats.ox.ac.uk/pub/MASS4/.

Examples

Run this code

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

#-------------------------------------------------------------------------------
# Cluster variable specification

# Example 1a: Cluster variable 'cluster' in 'x'
multilevel.omega(Demo.twolevel[,c("y1", "y2", "y3", "y4", "cluster")], cluster = "cluster")

# Example 1b: Cluster variable 'cluster' not in 'x'
multilevel.omega(Demo.twolevel[,c("y1", "y2", "y3", "y4")], cluster = Demo.twolevel$cluster)

# Example 1c: Alternative specification using the 'data' argument
multilevel.omega(y1:y4, data = Demo.twolevel, cluster = "cluster")

#-------------------------------------------------------------------------------
# Type of construct

# Example 2a: Within-Cluster Construct
multilevel.omega(Demo.twolevel[,c("y1", "y2", "y3", "y4")],
                 cluster = Demo.twolevel$cluster, const = "within")

# Example 2b: Shared Cluster-Level Construct
multilevel.omega(Demo.twolevel[,c("y1", "y2", "y3", "y4")],
                 cluster = Demo.twolevel$cluster, const = "shared")

# Example 2c: Configural Construct
multilevel.omega(Demo.twolevel[,c("y1", "y2", "y3", "y4")],
                 cluster = Demo.twolevel$cluster, const = "config")

#-------------------------------------------------------------------------------
# Residual covariance at the Within level and residual variance at the Between level

# Example 3a: Residual covariance between "y4" and "y5" at the Within level
multilevel.omega(Demo.twolevel[,c("y1", "y2", "y3", "y4")],
                 cluster = Demo.twolevel$cluster, const = "config",
                 rescov = c("y3", "y4"))

# Example 3b: Residual variances of 'y1' at the Between level fixed at 0
multilevel.omega(Demo.twolevel[,c("y1", "y2", "y3", "y4")],
                 cluster = Demo.twolevel$cluster, const = "config",
                 fix.resid = c("y1", "y2"), digits = 3)

#----------------------------------------------------------------------------
# Write results

# Example 4a: Write results into a text file
multilevel.omega(Demo.twolevel[,c("y1", "y2", "y3", "y4")],
                 cluster = Demo.twolevel$cluster, write = "Multilevel_Omega.txt")

# Example 4b: Write results into an Excel file
multilevel.omega(Demo.twolevel[,c("y1", "y2", "y3", "y4")],
                 cluster = Demo.twolevel$cluster, write = "Multilevel_Omega.xlsx")

# Example 4b: Assign results into an object and write results into an Excel file
mod <- multilevel.omega(Demo.twolevel[,c("y1", "y2", "y3", "y4")],
                        cluster = Demo.twolevel$cluster, output = FALSE)

# Write results into an Excel file
write.result(mod, "Multilevel_Omega.xlsx")
}

Run the code above in your browser using DataLab