% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/item.noninvar.R
\name{item.noninvar}
\alias{item.noninvar}
\title{Effect Size Measure of Measurement Non-Invariance, dMACS}
\usage{
item.noninvar(data = NULL, ..., object = NULL, model = NULL, group = NULL,
              ref = NULL, pooled = TRUE, signed = FALSE, cluster = NULL,
              long = FALSE, ordered = FALSE, rescov = NULL, rescov.long = TRUE,
              ident = c("marker", "var", "effect"),
              estimator = c("ML", "MLM", "MLMV", "MLMVS", "MLF", "MLR",
                            "GLS", "WLS", "DWLS", "WLSM", "WLSMV",
                            "ULS", "ULSM", "ULSMV", "DLS", "PML"),
              missing = c("listwise", "pairwise", "fiml", "two.stage",
                          "robust.two.stage", "doubly.robust"),
              print = c("all", "summary", "dmacs", "bias"),
              digits = 3, as.na = NULL, write = NULL, append = TRUE,
              check = TRUE, output = TRUE)
}
\arguments{
\item{data}{a data frame. If \code{model = NULL}, confirmatory factor
analysis based on a measurement model with one factor
labeled \code{f} comprising all variables in the data frame
specified in \code{data} for evaluating between-group
measurement non-invariance for the grouping variable
specified in the argument \code{group} is conducted.
Longitudinal measurement non-invariance evaluation can
only be conducted by specifying the model using the argument
\code{model}. Note that the cluster variable is excluded
from \code{data} when specifying \code{cluster}. If \code{model}
is specified, the data frame needs to contain all variables
used in the argument \code{model} and the cluster variable
when specifying the name of the cluster variable in the
argument \code{cluster}.}

\item{...}{an expression indicating the variable names in \code{data},
e.g., \code{item.noninvar(dat, x1, x2, x2, group = "group")}.
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{object}{an object of class lavaan, i.e., a fitted latent variable
model. Between-group measurement non-invariance is evaluated
when specifying a fitted multiple-group model, while
longitudinal measurement non-invariance is evaluated
when specifying a fitted single-group model with at least
two latent variables each representing a factor at different
time points.}

\item{model}{a character vector specifying a measurement model with
one factor, or a list of character vectors for specifying
a measurement model with more than one factor for
evaluating between-group measurement non-invariance
when \code{long = FALSE} or a list of character vectors
for specifying a measurement model with one factor for
each time of measurement for evaluating longitudinal
measurement non-invariance when specifying \code{long = TRUE}.
For example, \code{model = c("x1", "x2", "x3", "x4")}
for specifying a measurement model with one factor
labeled \code{f} comprising four indicators, or
\code{model = list(factor1 = c("x1", "x2", "x3", "x4"),
factor2 = c("x5", "x6", "x7", "x8"))} for specifying a
measurement model with two latent factors labeled
\code{factor1} and \code{factor2} each comprising four
indicators for evaluating between-group measurement
non-invariance, or
\code{model = list(time1 = c("ax1", "ax2", "ax3", "ax4"),
time2 = c("bx1", "bx2", "bx3", "bx4"),
time3 = c("cx1", "cx2", "cx3", "cx4"))} for specifying
a longitudinal measurement model with three time points
comprising four indicators at each time point. This
function cannot evaluate longitudinal measurement
invariance for a measurement model with more than one
factor. Note that the name of each list element is used
to label factors, i.e., all list elements need to be
named, otherwise factors are labeled with \code{"f1", "f2", "f3"}
when \code{long = FALSE} and with \code{"t1", "t2", "t3"}
when \code{long = TRUE} and so on.}

\item{group}{either a character string indicating the variable name
of the grouping variable in the data frame specified
in \code{data} or a vector representing the groups for
conducting multiple-group analysis to evaluate
between-group measurement non-invariance. Note that when
specifying a grouping variable with more than two groups,
the function compares each group with the reference group
specified in the argument \code{ref}.}

\item{ref}{a numeric value or character string indicating the name of
the reference group or reference time point. By default,
the the first group or time point is used as reference.}

\item{pooled}{logical: if \code{TRUE} (default), the item-level pooled
standard deviation is used in the denominator of the
effect size measure, if \code{FALSE} the item-level
standard deviation of the reference group or reference time point is used.}

\item{signed}{logical: if \code{TRUE}, the signed dMACS is computed
that incorporates the unsquared differences between
groups or time points illustrating the direction of
the differences and allowing effects in opposite
directions to cancel out (see Nye et al., 2019).}

\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). Note that this option is not available
when evaluating measurement invariance for ordered categorical
indicators by specifying \code{ordered = TRUE).}}

\item{long}{logical: if \code{TRUE}, longitudinal measurement
non-invariance evaluation is conducted. The longitudinal
measurement model is specified by using the argument
\code{model}. Note that this function can only deal with a
measurement model with one factor at each time point when
investigating longitudinal measurement non-invariance.
Moreover, this function can only evaluate either between-group
or longitudinal measurement non-invariance, but not both
at the same time.}

\item{ordered}{logical: if \code{TRUE}, all indicator variables of the
measurement model are treated as ordered categorical
variables. Note that the function only supports delta
parameterization. Also note that all indicators variables
need to have the same number of response categories.
Accordingly, zero cell counts are not allowed, e.g., zero
observations for a response category of an indicator within
a group when investigating between-group measurement
non-invariance or zero observations for a response category
of an indicator at a time point when investigating longitudinal
measurement non-invariance.}

\item{rescov}{a character vector or a list of character vectors for
specifying residual covariances, e.g., \code{rescov = c("x1", "x2")}
for specifying a residual covariance between items \code{x1}
and \code{x2}, or \code{rescov = list(c("x1", "x2"), c("x3", "x4"))}
for specifying residual covariances between items \code{x1}
and \code{x2}, and items \code{x3} and \code{x4}.}

\item{rescov.long}{logical: if \code{TRUE} (default), residual covariances
between parallel indicators are estimated across time
when evaluating longitudinal measurement non-invariance
(\code{long = TRUE}), i.e., residual variances of the
same indicators that are measured at different time points
are correlated across all possible time points. Note that
residual covariances should be estimated even if the parameter
estimates are statistically not significant since
indicator-specific systematic variance is likely to correlate
with itself over time (Little, 2013, p. 164).}

\item{ident}{a character string indicating the method used for identifying
and scaling latent variables, i.e., \code{"marker"} for
the marker variable method fixing the first factor
loading of the latent variable to 1 and fixing the
first intercept to 0, \code{"var"} (default) for the
fixed variance method fixing the variance of the latent
variable to 1 and the latent mean to 0, or \code{"effect"}
for the effects-coding method using equality constraints
so that the average of the factor loading of the latent
variable equals 1 and the sum of intercepts equals 0.
Note that measurement non-invariance evaluation for
ordered categorical indicators can only be conducted
based on the fixed variance method (\code{"var"}).}

\item{estimator}{a character string indicating the estimator to be used
(see 'Details' in the help page of the \code{item.cfa()}
function). By default, \code{"MLR"} is used for CFA
models with continuous indicators and \code{"WLSMV"}
is used for CFA models with ordered categorical
indicators. Note that the estimators
\code{"ML", "MLM", "MLMV", "MLMVS", "MLF"} and
\code{"MLR"} are not available when \code{ordered = TRUE}.}

\item{missing}{a character string indicating how to deal with missing
data, i.e., \code{"listwise"} for listwise deletion,
\code{"pairwise"} for pairwise deletion, \code{"fiml"}
for full information maximum likelihood method, \code{"two.stage"}
for two-stage maximum likelihood method, \code{"robust.two.stage"}
for robust two-stage maximum likelihood method, and
\code{"doubly-robust"} for doubly-robust method (see 'Details'
in the help page of the\code{item.cfa()} function). By
default, \code{"fiml"} is used for CFA models with continuous
indicators and \code{"listwise"} is used for CFA models
with ordered categorical indicators given that \code{"fiml"}
is not available for a limited-information estimator used
to estimate the CFA model with ordered categorical
indicators.}

\item{print}{a character string or character vector indicating which
results to show on the console, i.e. \code{"all"} for all
results, \code{"summary"} for a summary of the specification,
\code{"dmacs"} for the effect sizes measure dMACS, and
\code{"bias"} for the expected bias in the mean and variance
of the total score. By default, a summary of the specification
and the effect size measure dMACS are printed.}

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

\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{group} or \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 and convergence and model identification
checks are conducted for all estimated models.}

\item{output}{logical: if \code{TRUE} (default), output is shown.}
}
\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 including all variables used in the analysis, i.e.,
                   indicators for the factor, grouping variable and cluster
                   variable}
\item{\code{args}}{specification of function arguments}
\item{\code{model}}{model specification for the for the configural invariance model}
\item{\code{model.fit}}{fitted lavaan object of the configural invariance model}
\item{\code{check}}{list with the results of the convergence and model identification
                    check for the configural invariance model}
\item{\code{result}}{list with result tables, i.e., \code{summary} for the
                     summary of the specification and \code{noninvar} for the
                     dMACS effect size measure, expected bias in the mean total
                     score, and expected bias in the variance of the total score}
}
\description{
This function computes the effect size measure dMACS by Nye and Drasgow (2011)
and the signed dMACS by Nye et al. (2019) for evaluating the magnitude and the
direction of between-group and longitudinal measurement non-invariance or
non-equivalence for continuous and ordered categorical items and also computes
the expected bias in the mean and variance of the total score.
}
\details{
Nye and Drasgow (2011) introduced the effect size measure \eqn{d_{MACS}} (Mean
and Covariance Structure) for evaluating measurement non-invariance at the item
level on a standardized metric similar to Cohen's \emph{d} (1988) or Glass's (1976)
measures:
\describe{
\item{\strong{Effect Size Measure \eqn{d_{MACS}}}}{\eqn{d_{MACS}} (Nye & Drasgow,
2011)  ranging \eqn{[0, \infty]} is based on the predicted response \eqn{\hat{X}_{iR}}
to an item \eqn{i} for an individual in the reference group (or reference time point)
\eqn{R} and the corresponding response \eqn{\hat{X}_{iF}} for an individual in
the focal group (or focal time point) \eqn{F}:

\deqn{\hat{X}_{iR} = \tau_{iR} + \lambda_{iR}\xi}
\deqn{\hat{X}_{iF} = \tau_{iF} + \lambda_{iF}\xi}

where \eqn{\tau_{iR}} and \eqn{\tau_{iF}} are the intercepts, \eqn{\lambda_{iR}}
and \eqn{\lambda_{iF}} are the factor loadings of item \eqn{i} in the reference
and focal group, and \eqn{\xi} is the score on the latent variable.

The effect size evaluating the magnitude of measurement non-invariance is a weighted
average difference in predicted responses in standardized metric defined as:

\deqn{d_{MACS} = \frac{1}{SD_{iP}} \sqrt{\int (\hat{X}_{iR} - \hat{X}_{iF}|\xi)^2 f_F(\xi)d\xi }}

where \eqn{SD_{iP}} is the pooled within-group standard deviation of item \eqn{i}
across reference and focal group given by

\deqn{SD_{iP} = \frac{(N_R - 1)SD_R + (N_F - 1)SD_F}{(N_R - 1) + (N_F - 1)}}

Note that \eqn{f_F(\xi)} is the distribution of the latent trait \eqn{\xi} in the focal
group, which is assumed to have a normal distribution with a mean and variance
estimated from the latent factor in the focal group.}

\item{\strong{Effect Size Measure \eqn{d_{MACS\_Signed}}}}{\eqn{d_{MACS\_Signed}}
(Nye et al., 2019) ranging \eqn{[-\infty, \infty]} incorporates the unsquared
differences between predicted response to an item \eqn{i} between two groups:

\deqn{d_{MACS\_Signed} = \frac{1}{SD_{iP}} \int (\hat{X}_{iR} - \hat{X}_{iF}|\xi) f_F(\xi)d\xi }

Note that \eqn{d_{MACS\_Signed}} provides complementary information to the unsigned
version by (1) capturing the direction of the difference and (2) allowing
cancellation of effects in opposite direction.}

\item{\strong{Guidelines for Interpreting Effect Size Measure \eqn{d_{MACS}} and \eqn{d_{MACS\_Signed}}}}{
The effect size measures \eqn{d_{MACS}} and \eqn{d_{MACS\_Signed}} represent the
differences in both the factor loadings and the intercepts across two groups
and can be interpreted based on following guidelines (see Nye et al., 2019):

  \itemize{
    \item{\emph{Effect Size Measure \eqn{d_{MACS}}}}:
      \itemize{
        \item Results of a simulation study provided benchmarks for interpreting \eqn{d_{MACS}}:
          \itemize{
            \item Small effect: \eqn{0.20}
            \item Medium effect: \eqn{0.40}
            \item Large effect: \eqn{0.70}
          }
        \item The simulation study operationalized effect sizes empirically based on
              a literature review of journals in organizational behavior and entrepreneurship:
          \itemize{
            \item Difference in standardized factor loadings: 0.10 (small), 0.20 (medium), and 0.30 (large)
            \item Difference in intercept: 0.25 (small), 0.50 (medium), and 0.75 (large)
          }
        \item Results also showed that when the sample size (\eqn{n_g = 250}) and/or
        the number of items (\eqn{k = 8}) were small, \eqn{d_{MACS}} can become
        greater than 0.20 due to poorly estimated model parameters.

      }
      Note that \eqn{d_{MACS}} does not provide information about the direction of
      the effect, i.e., it is unclear which group the item is biased against.

    \item{\emph{Effect Size Measure \eqn{d_{MACS\_Signed}}}}:
          \itemize{
        \item Results of a simulation study provided benchmarks for interpreting \eqn{d_{MACS\_Signed}}:
          \itemize{
            \item Small effect: \eqn{|0.40|}
            \item Medium effect: \eqn{|0.60|}
            \item Large effect: \eqn{|0.80|}
          }
        \item Simulation study investigated the practical importance of non-invariance
        when no true latent mean difference exist between groups, i.e., false positive
        results due to non-invariance:
          \itemize{
            \item \eqn{d_{MACS\_Signed}} = |0.40| in one out of eight items results
                  in Cohen's \eqn{d} ~ 0.13 and a .13 probability for finding
                  statistically significant differences due to non-invariance.
            \item \eqn{d_{MACS\_Signed}} = |0.60| in one out of eight items results
                  in Cohen's \eqn{d} ~ 0.26 and a .85 probability for finding
                  statistically significant differences due to non-invariance.
            \item \eqn{d_{MACS\_Signed}} = |0.80| in one out of eight items results
                  in Cohen's \eqn{d} ~ 0.26 and a 1.00 probability for finding
                  statistically significant differences due to non-invariance.
            }
        }
    }

  }
  \item{\strong{Practical Consequences of Measurement Non-Invariance}}{
  The practical consequences of non-invariance can be investigated by computing
  the amount of the observed mean and variance difference of a scale between
  groups that can be attributed to non-invariance:

  \deqn{\Delta mean(x_s) = \sum_{1}^{n}\int (\hat{X}_{iR} - \hat{X}_{iF}|\xi) f_F(\xi)d\xi}
  \deqn{\Delta var(x_s) = 2C_i\lambda_{iR} \phi_F + C_i^2\phi_F}

  where \eqn{X_s} is the scale score, \eqn{\lambda_{iR}} is the factor loading of
  item \eqn{i} in the reference group, \eqn{C_i} is the difference
  between the factor loading for item \eqn{i} in the reference and focal groups,
  and \eqn{\phi_F} is the variance of the latent factor in the focal group.
  According to these formula, two items with high \eqn{d_{MACS\_Signed}} in
  opposite directions can have no impact on \eqn{\Delta mean(x_s)} and
  \eqn{\Delta var(x_s)} due to the cancellation effect.

  Note that with fewer items in the scale, the practical importance of a single
  item with high \eqn{d_{MACS\_Signed}} would increase, while a single non-invariant
  item in a longer measure would have less practical importance. For example,
  the practical importance of a single non-invariant item with a \eqn{d_{MACS\_Signed} = 0.40}
  in a 30-item measure would correspond to a Cohen’s \emph{d} value of 0.05 and
  a .14 probability of a statistically significant mean differences in the absence
  of a true differences between groups. That is, the same cutoffs used for an 8-item
  measure might not apply to a 30-item measure. Moreover, a measure with more than
  one non-invariant item would have a greater chance of distorting research outcomes.

  In summary, the findings in Nye et al. (2019) suggest that a more nuanced
  interpretation of the effect size of non-invariance may be required. Accordingly,
  Lai et al. (2025) notet that cutoff values should be used with caution as the
  interpretation of the magnitude of non-invariance should be based on many other
  factors, such as the construct of interest, the grouping variables, the main
  usage of the instrument, the context of the measurement, and so on.
  }
}
}
\note{
This function is based on modified copies of the functions \code{dmacs_summary}
\code{dmacs_summary_single}, \code{item_dmacs}, \code{expected_value},
\code{delta_mean_item} and \code{delta_var} from the \pkg{dmacs} package by
David Dueber.
}
\examples{
\dontrun{
# Load data set "HolzingerSwineford1939" in the lavaan package
data("HolzingerSwineford1939", package = "lavaan")

#————————————————————————————————————————————————————————————————————————————
# Between-Group Measurement Non-Invariance: Continuous Indicators

#···················
# Measurement model with one factor

# Example 1a: Model specification using the argument '...'
item.noninvar(HolzingerSwineford1939, x1, x2, x3, x4, group = "school")

# Example 1b: Alternative model specification without using the argument '...'
item.noninvar(HolzingerSwineford1939[, c("x1", "x2", "x3", "x4")],
              group = HolzingerSwineford1939$school)

# Example 1c: Alternative model specification without using the argument '...'
item.noninvar(HolzingerSwineford1939[, c("x1", "x2", "x3", "x4", "school")], group = "school")

# Example 1d: Alternative model specification using the argument 'model'
item.noninvar(HolzingerSwineford1939, model = c("x1", "x2", "x3", "x4"), group = "school")

# Example 1e: Estimate model and specify the 'object' argument
model <- 'f =~ x1 + x2 + x3 + x4'

fit <- cfa(model, data = HolzingerSwineford1939, group = "school", std.lv = TRUE)
item.noninvar(object = fit)

#···················
# Measurement model with two factors

# Example 2a: Model specification using the argument 'model'
item.noninvar(HolzingerSwineford1939,
              model = list(c("x1", "x2", "x3", "x4"), c("x5", "x6", "x7", "x8")),
              group = "school")

# Example 2b: Model specification using the argument 'model'
model <- 'f1 =~ x1 + x2 + x3 + x4
          f2 =~ x5 + x6 + x7 + x8'

#···················
# Signed dMACS and reference group

# Example 3a: Signed dMACS
item.noninvar(HolzingerSwineford1939, x1, x2, x3, x4, group = "school", signed = TRUE)

# Example 3b: Specify reference group and use SD of the reference group
item.noninvar(HolzingerSwineford1939, x1, x2, x3, x4, group = "school",
              ref = "Pasteur", pooled = FALSE)

#..................
# Residual covariances

# Example 4a: One residual covariance
item.noninvar(HolzingerSwineford1939, model = c("x1", "x2", "x3", "x4"),
              rescov = c("x3", "x4"), group = "school")

# Example 4b: Two residual covariances
item.noninvar(HolzingerSwineford1939, model = c("x1", "x2", "x3", "x4"),
              rescov = list(c("x1", "x4"), c("x3", "x4")), group = "school")

#..................
# Print argument

# Example 5: Request all results
item.noninvar(HolzingerSwineford1939, model = c("x1", "x2", "x3", "x4"),
              group = "school", print = "all")

#————————————————————————————————————————————————————————————————————————————
# Longitudinal Measurement Non-Invariance: Continuous Indicators

# Example 6: Two time points with three indicators at each time point
item.noninvar(HolzingerSwineford1939,
              model = list(c("x1", "x2", "x3"), c("x5", "x6", "x7")), long = TRUE)

#————————————————————————————————————————————————————————————————————————————
# Between-Group Measurement Non-Invariance: Ordered Categorical Indicators
#
# Note that the example analysis for ordered categorical indicators cannot be
# conduct as the data set 'data' is not available.

# Example 7: Two groups
item.noninvar(data, item1, item2, item3, item4, group = "two.group", ordered = TRUE)

#————————————————————————————————————————————————————————————————————————————
# Longitudinal Measurement Non-Invariance: Ordered Categorical Indicators

# Example 8: Two Time Points
item.noninvar(data, model = list(c("aitem1", "aitem2", "aitem3"),
                                 c("bitem1", "bitem2", "bitem3")),
              long = TRUE, ordered = TRUE)

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

# Example 9a: Write Results into a text file
item.noninvar(HolzingerSwineford1939, model = c("x1", "x2", "x3", "x4"),
              group = "school", print = "all", write = "Non-Invariance.txt", output = FALSE)

# Example 9b: Write Results into an Excel file
item.noninvar(HolzingerSwineford1939, model = c("x1", "x2", "x3", "x4"),
              group = "school", print = "all", write = "Non-Invariance.xlsx", output = FALSE)
}
}
\references{
Cohen, J. (1988). \emph{Statistical power analysis for the behavioral sciences}
(2nd ed.). Lawrence Erlbaum.

Dueber D (2026). \emph{dmacs: Measurement Nonequivalence Effect Size Calculator}.
R package version 0.1.0.9002. https://github.com/ddueber/dmacs

Glass, G. V. (1976). Primary, secondary, and meta-analysis of research.
\emph{Educational Researcher, 5}, 3-8.

Lai, M. H. C., Zhang, Y., Ozcan, M., Tse, W. W. Y., & Miles, A. (2025).
fMACS: Generalizing dMACS effect size for measurement noninvariance with
multiple groups and multiple grouping variables.
\emph{Structural Equation Modeling: A Multidisciplinary Journal, 32}(4),
638-646. https://doi.org/10.1080/10705511.2025.2484812

Nye, C. D., Bradburn, J., Olenick, J., Bialko, C., & Drasgow, F. (2019).
How big are my effects? Examining the magnitude of the effect sizes in studies
of measurement equivalence. \emph{Organizational Research Methods, 22}(3), 678–709.
https://doi.org/10.1177/1094428118761122

Nye, C., & Drasgow, F. (2011). Effect size indices for analyses of
measurement equivalence: Understanding the practical importance of
differences between groups. \emph{Journal of Applied Psychology, 96}(5),
966-980.
}
\seealso{
\code{\link{item.invar}}, \code{\link{item.cfa}}, \code{\link{multilevel.invar}}
}
\author{
Takuya Yanagida
}
