% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/OMEGA.R
\name{OMEGA}
\alias{OMEGA}
\title{McDonald's omega}
\source{
McDonald, R. P. (1978). Generalizability in factorable domains: ‘‘Domain
validity and generalizability’’. Educational and Psychological Measurement,
38, 75–79.

McDonald, R. P. (1985). Factor analysis and related methods. Hillsdale,
NJ: Erlbaum.

McDonald, R. P. (1999). Test theory: A unified treatment. Mahwah,
NJ: Erlbaum.

Rodriguez, A., Reise, S. P., & Haviland, M. G. (2016a). Applying bifactor
statistical indices in the evaluation of psychological measures. Journal of
Personality Assessment, 98, 223-237.

Rodriguez, A., Reise, S. P., & Haviland, M. G. (2016b). Evaluating
bifactor models: Calculating and interpreting statistical indices.
Psychological Methods, 21, 137-150.

Hancock, G. R., & Mueller, R. O. (2001). Rethinking construct reliability
within latent variable systems. In R. Cudeck, S. du Toit, & D. Sörbom (Eds.),
Structural equation modeling: Present and future—A Festschrift in honor of Karl
Jöreskog (pp. 195–216). Lincolnwood, IL: Scientific Software International.

Reise, S. P., Scheines, R., Widaman, K. F., & Haviland, M. G. (2013).
Multidimensionality and structural coefficient bias in structural equation
modeling: A bifactor perspective. Educational and Psychological Measurement,
73, 5–26.

Bonifay, W. E., Reise, S. P., Scheines, R., & Meijer, R. R. (2015).
When are multidimensional data unidimensional enough for structural equation
modeling?: An evaluation of the DETECT multidimensionality index. Structural
Equation Modeling, 22, 504—516.

Gignac, G. E. (2014). On the Inappropriateness of Using Items to
Calculate Total Scale Score Reliability via Coefficient Alpha for Multidimensional
Scales. European Journal of Psychological Assessment, 30, 130-139.
}
\usage{
OMEGA(
  model = NULL,
  type = c("EFAtools", "psych"),
  g_name = "g",
  group_names = NULL,
  add_ind = TRUE,
  factor_corres = NULL,
  var_names = NULL,
  fac_names = NULL,
  g_load = NULL,
  s_load = NULL,
  u2 = NULL,
  cormat = NULL,
  pattern = NULL,
  Phi = NULL,
  variance = c("correlation", "sums_load")
)
}
\arguments{
\item{model}{class \code{\link[=efa_schmid_leiman]{efa_schmid_leiman()}}, class \code{schmid}, or class
\code{lavaan} object. That is, an output object from \code{\link[=efa_schmid_leiman]{efa_schmid_leiman()}} or
\code{\link[psych:schmid]{psych::schmid()}}, or a \code{lavaan} fit object with a
single factor, second-order, or bifactor solution. If of class \code{lavaan},
only \code{g_name} needs to be specified additionally. If of class
\code{\link[=efa_schmid_leiman]{efa_schmid_leiman()}} or \code{schmid}, only the arguments \code{factor_corres}
and \code{cormat} need to be specified additionally.}

\item{type}{character. Either \code{"EFAtools"} (default) or \code{"psych"}
(see details)}

\item{g_name}{character. The name of the general factor from the lavaan solution.
This needs only be specified if \code{model} is a \code{lavaan} second-order
or bifactor solution. Default is "g".}

\item{group_names}{character. An optional vector of group names. The length
must correspond to the number of groups for which the \code{lavaan} model
was fitted.}

\item{add_ind}{logical. Whether additional indices (H index, ECV, PUC) should
be calculated or not (see details for these indices). If FALSE, only omegas
are returned. Default is \code{TRUE}.}

\item{factor_corres}{matrix. A logical matrix or a numeric matrix containing
0's and 1's that indicates which variable corresponds to which group factor.
Must have the same dimensions as the matrix of group factor loadings from the
SL solution. Cross-loadings are allowed here. See examples for use.}

\item{var_names}{character. A vector with subtest names in the order
of the rows from the SL solution. This needs only be specified if \code{model}
is left \code{NULL}.}

\item{fac_names}{character. An optional vector of group factor names in the
order of the columns of the SL solution. If left \code{NULL}, names of the
group factors from the entered solution are taken.}

\item{g_load}{numeric. A vector of general factor loadings from an SL solution.
This needs only be specified if \code{model} is left \code{NULL}.}

\item{s_load}{matrix. A matrix of group factor loadings from an SL solution.
This needs only be specified if \code{model} is left \code{NULL}.}

\item{u2}{numeric. A vector of uniquenesses from an SL solution. This needs
only be specified if \code{model} is left \code{NULL}.}

\item{cormat}{matrix. A correlation matrix to be used when
\code{variance = "correlation"}. If left \code{NULL} and an \code{\link[=efa_schmid_leiman]{efa_schmid_leiman()}}
output is entered in \code{model}, the correlation matrix is taken from the
output. If left \code{NULL} and a \code{\link[psych:schmid]{psych::schmid()}}
output is entered, the correlation matrix will be found based on the pattern
matrix and Phi from the \code{\link[psych:schmid]{psych::schmid()}} output
using \code{\link[psych:factor.model]{psych::factor.model()}}.
If left \code{NULL} and model is also left \code{NULL}, the correlation matrix
is found based on the pattern matrix and Phi entered. However, if the
correlation matrix is available, \code{cormat} should be specified instead
of \code{Phi} and \code{pattern}.}

\item{pattern}{matrix. Pattern coefficients from an oblique factor solution.
This needs only be specified if \code{model} is left \code{NULL},
\code{variance = "correlation"} and \code{cormat} is also left \code{NULL}.}

\item{Phi}{matrix. Factor intercorrelations from an oblique factor solution.
This needs only be specified if \code{model} is left \code{NULL},
\code{variance = "correlation"} and \code{cormat} is also left \code{NULL}.}

\item{variance}{character. If \code{"correlation"} (default), then total
variances for the whole scale as well as for the subscale composites are
calculated based on the correlation
matrix. If \code{"sums_load"}, then total variances are calculated using the
squared sums of general factor loadings and group factor loadings and
the sum of uniquenesses (see details).}
}
\value{
If found for an SL or \code{lavaan} second-order or bifactor solution
without multiple groups:
A matrix with omegas for the whole scale and for the subscales and (only if
\code{add_ind = TRUE}) with the H index, ECV, and PUC.
\item{tot}{Omega total.}
\item{hier}{Omega hierarchical.}
\item{sub}{Omega subscale.}
\item{H}{H index.}
\item{ECV}{Explained common variance.}
\item{PUC}{Percent of uncontaminated correlations.}

If found for a \code{lavaan} single factor solution without multiple groups:
A (named) vector with omega total and (if \code{add_ind = TRUE}) the H index
for the single factor.

If found for a \code{lavaan} output from a multiple group analysis: A list
containing the output described above for each group.
}
\description{
\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#superseded}{\figure{lifecycle-superseded.svg}{options: alt='[Superseded]'}}}{\strong{[Superseded]}}

\code{OMEGA()} has been superseded by \code{\link[=efa_reliability]{efa_reliability()}}, which is the recommended
interface going forward. It remains available and unchanged so existing code
keeps working.

This function finds omega total, hierarchical, and subscale, as well as additional
model-based indices of interpretive relevance (H index, ECV, PUC)
from a Schmid-Leiman (SL) solution or lavaan single factor, second-order (see below),
or bifactor solution. The SL-based omegas can either be found from a
\code{\link[psych:schmid]{psych::schmid()}}, \code{\link[=efa_schmid_leiman]{efa_schmid_leiman()}}, or,
in a more flexible way, by leaving
\code{model = NULL} and specifying additional arguments. The \code{type} argument selects
how variables are assigned to group factors, and can reproduce the assignment
\code{\link[psych:omega]{psych::omega()}} makes.
}
\details{
\subsection{What this function does}{

All types of McDonald's omegas (total, hierarchical, and subscale; McDonald,
1978, 1985, 1999) are calculated for
the general factor as well as for the subscales / group factors (see, e.g.,
Gignac, 2014; Rodriguez et al., 2016a, 2016b). Omegas refer to the correlation
between a factor and a unit-weighted composite score and thus the
true score variance in a unit-weighted composite based on the respective
indicators. Omega total is the total true score variance in a composite.
Omega hierarchical is the true score variance in a composite that is attributable
to the general factor, and omega subscale is the true score variance in a
composite attributable to all subscales / group factors (for the whole scale)
or to the specific subscale / group factor (for subscale composites).

Accordingly, on a subscale row the \code{hier} column reports the share of that
subscale's composite variance due to the general factor and the \code{sub} column
the share due to the subscale-specific factor; the latter corresponds to the
omega hierarchical subscale of Rodriguez et al. (2016a, 2016b).

The H index (also construct reliability or replicability index) is the
correlation between an optimally-weighted composite score
and a factor (Hancock & Mueller, 2001; Rodriguez et al., 2016a, 2016b). It, too,
can be calculated for the whole scale / general factor as well as for the
subscales / group factors. Low values indicate that a latent variable is not well
defined by its indicators.

The ECV (Rodriguez et al., 2016a, 2016b) is the ratio of the
variance explained by the general factor and the variance explained by the
general factor and the group factors.

The PUC (Bonifay et al., 2015; Reise et al., 2013, Rodriguez et al., 2016a,
2016b) refers to the proportion
of correlations in the underlying correlation matrix that is not contaminated
by variance of both the general factor and the group factors (i.e., correlations
between indicators from different group factors, which reflect only general
factor variance). The higher the PUC, the more similar a general factor from
a multidimensional model will be to the single factor from a unidimensional
model.
}

\subsection{How to use this function}{

If \code{model} is a \code{lavaan} second-order or bifactor solution,
only the name of the general factor from the lavaan model needs to be specified
additionally with the \code{g_name} argument. It is then determined whether this
general factor is a second-order factor (second-order model with one second-order
factor assumed) or a breadth factor (bifactor model assumed). Please note that
this function only works for second-order models if they contain no more than
one second-order factor. In case of a second-order solution, a
Schmid-Leiman transformation is performed on the first- and second-order loadings
and omega coefficients are obtained from the transformed (orthogonalized) solution
(see \code{\link[=efa_schmid_leiman]{efa_schmid_leiman()}} for more information on Schmid-Leiman transformation).
There is also the possibility to enter a \code{lavaan} single factor solution.
In this case, \code{g_name} is not needed. Finally, if a solution from a
\code{lavaan} multiple group analysis is entered, the indices are computed for
each group. For \code{lavaan} input the composite variances entering the omegas are
model-implied: they are computed from the fitted loadings and the fitted residual
covariance matrix, and count any freed residual covariance as well as the residual
variances. The coefficients thus coincide with the observed-score versions when the
model fits perfectly. The omegas split a composite's variance into a general part and one part
per group factor, which needs uncorrelated latent variables: fit a bifactor model
with \code{orthogonal = TRUE} (not \code{lavaan}'s default) and leave the covariances between
a second-order model's first-order factors at zero. A fit whose factors correlate is
rejected rather than scored as though they did not.
The type argument is not evaluated if \code{model} is of class
\code{lavaan}.

If \code{model} is of class \code{\link[=efa_schmid_leiman]{efa_schmid_leiman()}} or
\code{\link[psych:schmid]{psych::schmid()}} only the
\code{type} and, depending on the type (see below), the \code{factor_corres}
arguments need to be specified additionally. If model is of class
\code{\link[psych:schmid]{psych::schmid()}} and \code{variance = "correlation"}
(default), it is
recommended to also provide the original correlation matrix in \code{cormat}
to get more accurate results. Otherwise, the correlation matrix will be found
based on the pattern matrix and Phi from the
\code{\link[psych:schmid]{psych::schmid()}} output
using the \code{\link[psych:factor.model]{psych::factor.model()}} function.

If \code{model = NULL}, the arguments \code{type}, \code{factor_corres}
(depending on the type, see below), \code{var_names}, \code{g_load}, \code{s_load},
and \code{u2} and either \code{cormat} (recommended) or \code{Phi} and
\code{pattern} need to be specified. If \code{Phi} and \code{pattern} are
specified instead of \code{cormat}, the correlation matrix is found using
the \code{\link[psych:factor.model]{psych::factor.model()}} function.

The only difference between \code{type = "EFAtools"} and \code{type = "psych"}
is the determination of variable-to-factor correspondences. \code{type = "psych"}
derives them as \code{\link[psych:omega]{psych::omega()}} does, by
taking the highest
group factor loading for each variable as the relevant group factor loading.
To do this, \code{factor_corres} must be left \code{NULL}.

Both settings score a composite by the true score variance the model attributes
to it, counting every factor its variables load on; they differ only in the
variance that is divided into. \code{variance = "correlation"} uses the composite's
observed variance, giving the observed-score form of omega; \code{"sums_load"} uses its
model-implied variance, which partitions exactly into omega hierarchical plus omega
subscale on the whole-scale row. The two settings agree up to model misfit, and
differ mainly in the whole-scale omega subscale, which counts all group-factor
variance under \code{"sums_load"} but only the assigned subscale composites under
\code{"correlation"}.
}
}
\examples{
\donttest{
## Use with lavaan outputs
if (requireNamespace("lavaan", quietly = TRUE)) {

# Create and fit bifactor model in lavaan (assume all variables have SDs of 1)
mod <- 'F1 =~ V1 + V2 + V3 + V4 + V5 + V6
        F2 =~ V7 + V8 + V9 + V10 + V11 + V12
        F3 =~ V13 + V14 + V15 + V16 + V17 + V18
        g =~ V1 + V2 + V3 + V4 + V5 + V6 + V7 + V8 + V9 + V10 + V11 + V12 +
             V13 + V14 + V15 + V16 + V17 + V18'
fit_bi <- lavaan::cfa(mod, sample.cov = test_models$baseline$cormat,
                      sample.nobs = 500, estimator = "ml", orthogonal = TRUE)

# Compute omegas and additional indices for bifactor solution
OMEGA(fit_bi, g_name = "g")

# Compute only omegas
OMEGA(fit_bi, g_name = "g", add_ind = FALSE)

# Create and fit second-order model in lavaan (assume all variables have SDs of 1)
mod <- 'F1 =~ V1 + V2 + V3 + V4 + V5 + V6
        F2 =~ V7 + V8 + V9 + V10 + V11 + V12
        F3 =~ V13 + V14 + V15 + V16 + V17 + V18
        g =~ F1 + F2 + F3'
fit_ho <- lavaan::cfa(mod, sample.cov = test_models$baseline$cormat,
                      sample.nobs = 500, estimator = "ml")

# Compute omegas and additional indices for second-order solution
OMEGA(fit_ho, g_name = "g")
}
}

## Use with an output from the SL function, with type EFAtools
efa_mod <- efa_fit(test_models$baseline$cormat, N = 500, n_factors = 3,
                   estimator = "PAF", rotation = "promax")
sl_mod <- efa_schmid_leiman(efa_mod, estimator = "PAF")

# Indicator-to-factor correspondences from a salience threshold (here: .20):
factor_corres_1 <- sl_mod$sl[, c("F1", "F2", "F3")] >= .2

OMEGA(sl_mod, type = "EFAtools", factor_corres = factor_corres_1)

## Use with an output from the psych::schmid function, with type psych for
## OMEGA
schmid_mod <- psych::schmid(test_models$baseline$cormat, nfactors = 3,
                            n.obs = 500, fm = "pa", rotate = "Promax")
# Find correlation matrix from phi and pattern matrix from psych::schmid output
OMEGA(schmid_mod, type = "psych")
# Use specified correlation matrix
OMEGA(schmid_mod, type = "psych", cormat = test_models$baseline$cormat)

## Manually specify components (useful if omegas should be computed for a SL
## or bifactor solution found with another program)
## As an example, we extract the elements from an SL output here. This gives
## the same results as in the second example above.

factor_corres <- matrix(c(rep(0, 12), rep(1, 6), rep(0, 6), rep(1, 6),
                        rep(0, 6), rep(1, 6), rep(0, 12)), ncol = 3,
                        byrow = FALSE)

OMEGA(model = NULL, type = "EFAtools", var_names = rownames(sl_mod$sl),
      g_load = sl_mod$sl[, "g"], s_load = sl_mod$sl[, c("F1", "F2", "F3")],
      u2 = sl_mod$sl[, "u2"], cormat = test_models$baseline$cormat,
      factor_corres = factor_corres)

}
\seealso{
\code{\link[=efa_reliability]{efa_reliability()}} for the same coefficients in a tidy, long-format
result.
}
