% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/multilevel.cor.R
\name{multilevel.cor}
\alias{multilevel.cor}
\title{Within-Group and Between-Group Correlation Matrix}
\usage{
multilevel.cor(data, ..., cluster, estimator = c("ML", "MLR"), constr.var = FALSE,
               optim.method = c("nlminb", "em"), optim.switch = TRUE,
               missing = c("listwise", "fiml"), sig = FALSE, alpha = 0.05,
               print = c("all", "cor", "se", "stat", "p"), split = FALSE,
               order = 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, write = NULL, append = TRUE, check = TRUE,
               output = TRUE)
}
\arguments{
\item{data}{a data frame.}

\item{...}{an expression indicating the variable names in \code{data},
e.g., \code{multilevel.cor(dat, x1, x2, x3)}. Note that
the operators \code{+}, \code{-}, \code{~},
\code{:}, \code{::}, and \code{!} can also be used to
select variables, see 'Details' in the \code{\link{df.subset}}
function.}

\item{cluster}{either a character string indicating the variable name of
the cluster variable in \code{data}, or a
vector representing the nested grouping structure (i.e.,
group or cluster variable).}

\item{estimator}{a character string indicating the estimator to be used, i.e.,
\code{"ML"} for maximum likelihood with conventional
standard errors and \code{"MLR"} for maximum likelihood with
Huber-White robust standard errors. The default setting
depends on the argument \code{sig}, i.e., \code{"ML"} is
used when specifying \code{sig = FALSE} (default) and
\code{"MLR"} is used when specifying \code{sig = TRUE}.}

\item{constr.var}{logical: if \code{TRUE}, inequality constraints are imposed
for the variance parameters at the between level, i.e., variances are constrained
to be greater than 0.}

\item{optim.method}{a character string indicating the optimizer, i.e., \code{"nlminb"}
(default) for the unconstrained and bounds-constrained
quasi-Newton method optimizer and \code{"em"} for the
Expectation Maximization (EM) algorithm.}

\item{optim.switch}{logical: if \code{TRUE} (default), model estimation switches
to Expectation Maximization (EM) algorithm (\code{"em"})
if the quasi-Newton optimization (\code{"nlminb"} (default))
does not converge.}

\item{missing}{a character string indicating how to deal with missing
data, i.e., \code{"listwise"} for listwise deletion or
\code{"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.}

\item{sig}{logical: if \code{TRUE}, statistically significant
correlation coefficients are shown in boldface on the
console. Note that standard errors, z test statistics, and
significance values not provided in the return object when
\code{sig = FALSE} (default).}

\item{alpha}{a numeric value between 0 and 1 indicating the significance
level at which correlation coefficients are printed
boldface when \code{sig = TRUE}.}

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

\item{split}{logical: if \code{TRUE}, output table is split in
within-group and between-group correlation matrix.}

\item{order}{logical: if \code{TRUE}, variables in the output table are
ordered, so that variables specified in the argument
\code{between} are shown first.}

\item{tri}{a character string indicating which triangular of the
matrix to show on the console when \code{split = TRUE},
i.e., \code{both} for upper and \code{upper} for the upper
triangular.}

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

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

\item{digits}{an integer value indicating the number of decimal places
to be used for displaying correlation coefficients.}

\item{p.digits}{an integer value indicating the number of decimal places
to be used for displaying \emph{p}-values.}

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

\item{write}{a character string naming a file for writing the output into
either a text file with file extension \code{".txt"} (e.g.,
\code{"Output.txt"}) or Excel file with file extension
\code{".xlsx"}  (e.g., \code{"Output.xlsx"}). If the file
name does not contain any file extension, an Excel file will
be written.}

\item{append}{logical: if \code{TRUE} (default), output will be appended
to an existing text file with extension \code{.txt} specified
in \code{write}, if \code{FALSE} existing text file will be
overwritten.}

\item{check}{logical: if \code{TRUE} (default), argument specification is checked.}

\item{output}{logical: if \code{TRUE} (default), output is shown on the console.}
}
\value{
Returns an object of class \code{misty.object}, which is a list with following
entries:
  \item{\code{call}}{function call}
  \item{\code{type}}{type of analysis}
  \item{\code{data}}{data frame specified in \code{data} including the group variable
                     specified in \code{cluster}}
  \item{\code{args}}{specification of function arguments}
  \item{\code{model.fit}}{fitted lavaan object (\code{mod.fit})}
  \item{\code{result}}{list with result tables, i.e., \code{summary} for the
                       specification of the estimation method and missing data
                       handling in lavaan, \code{wb.cor} for the within- and
                       between-group correlations, \code{wb.se} for the standard
                       error of the within- and between-group correlations,
                       \code{wb.stat} for the test statistic of within- and between-group
                       correlations, \code{wb.p} for the significance value of
                       the within- and between-group correlations, \code{with.cor}
                       for the within-group correlations, \code{with.se} for the
                       standard error of the within-group correlations, \code{with.stat}
                       for the test statistic of within-group correlations, \code{with.p}
                       for the significance value of the within-group correlations,
                       \code{betw.cor} for the between-group correlations, \code{betw.se}
                       for the standard error of the between-group correlations,
                       \code{betw.stat} for the test statistic of between-group
                       correlations, \code{betw.p} for the significance value of
                       the between-group correlations}
}
\description{
This function computes the within-group and between-group correlation matrix by
calling the \code{sem} function in the R package \pkg{lavaan} and provides standard
errors, z test statistics, and significance values (\emph{p}-values) for testing
the hypothesis H0: \eqn{\rho} = 0 for all pairs of variables within and between
groups. By default, the function computes the within-group and between-group
correlation matrix without standard errors, z test statistics, and significance
value.
}
\details{
\describe{
\item{\strong{Within-Group and Between-Group Variables}}{The function automatically
identifies (1) variables in the data frame specified in \code{data} that are
measured at the individual level and modeled only at the within level and (2)
variables in the data frame specified in \code{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 cluster.}
\item{\strong{Estimation Method and Missing Data Handling}}{The default setting
for the argument \code{estimator} is depending on the setting of the argument
\code{sig}. If \code{sig = FALSE} (default), maximum likelihood estimation
(\code{estimator = "ML"}) is used, while maximum likelihood with Huber-White
robust standard errors (\code{estimator = "MLR"}) that are robust against
non-normality is used when \code{sig = TRUE}. In the presence of missing data,
full information maximum likelihood (FIML) method (\code{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 will be resolved by switching to listwise deletion
(\code{missing = "listwise"}).}
\item{\strong{Optimizer}}{The lavaan package uses a quasi-Newton optimization
method (\code{"nlminb"}) by default. If the optimizer does not converge, model
estimation switches to the Expectation Maximization (EM) algorithm (\code{"em"})
if the argument \code{optim.switch} is specified as \code{TRUE} (default).}
\item{\strong{Statistical Significance}}{Statistically significant correlation
coefficients can be shown in boldface on the console by specifying \code{sig = TRUE}.
However, this option is not supported when using R Markdown, i.e., the argument
\code{sig} will switch to \code{FALSE}.}
\item{\strong{Adjustment Method for Multiple Testing }}{Adjustment method for
multiple testing when specifying the argument \code{p.adj} is applied to
the within-group and between-group correlation matrix separately.}
}
}
\note{
The function uses the functions \code{sem}, \code{lavInspect},
\code{lavMatrixRepresentation}, \code{lavTech}, \code{parameterEstimates},
and \code{standardizedsolution} provided in the R package \pkg{lavaan} by
Yves Rosseel (2012).
}
\examples{
\dontrun{

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

#————————————————————————————————————————————————————————————————————————————
# Cluster variable specification

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

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

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

#————————————————————————————————————————————————————————————————————————————
# Example 2: All variables modeled at both the within and between level
# Highlight statistically significant result at alpha = 0.05
multilevel.cor(Demo.twolevel, y1, y2, y3, sig = TRUE, cluster = "cluster")

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

# Example 4: Print correlation coefficients, standard errors, z test statistics,
# and p-values
multilevel.cor(Demo.twolevel, y1, y2, y3, cluster = "cluster", sig = TRUE, print = "all")

# Example 5: Print correlation coefficients and p-values
# significance values with Bonferroni correction
multilevel.cor(Demo.twolevel, y1, y2, y3, cluster = "cluster", sig = TRUE,
               print = c("cor", "p"), p.adj = "bonferroni")

#————————————————————————————————————————————————————————————————————————————
# Example 6: 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",
               between = c("w1", "w2"))

# Example 7: Show variables specified in the argument 'between' first
multilevel.cor(Demo.twolevel, y1, y2, y3, w1, w2, cluster = "cluster",
               between = c("w1", "w2"), order = TRUE)

#————————————————————————————————————————————————————————————————————————————
# Example 8: 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 9a: Write Results into a text file
multilevel.cor(Demo.twolevel, y1, y2, y3, cluster = "cluster",
               write = "Multilevel_Correlation.txt")

# Example 9b: Write Results into a Excel file
multilevel.cor(Demo.twolevel, y1, y2, y3, cluster = "cluster",
               write = "Multilevel_Correlation.xlsx")
}
}
\references{
Hox, J., Moerbeek, M., & van de Schoot, R. (2018). \emph{Multilevel analysis:
Techniques and applications} (3rd. ed.). Routledge.

Snijders, T. A. B., & Bosker, R. J. (2012). \emph{Multilevel analysis: An
introduction to basic and advanced multilevel modeling} (2nd ed.). Sage
Publishers.
}
\seealso{
\code{\link{write.result}}, \code{\link{multilevel.descript}},
\code{\link{multilevel.icc}}, \code{\link{cluster.scores}}
}
\author{
Takuya Yanagida \email{takuya.yanagida@univie.ac.at}
}
