# R/ECV_Indices.R In BifactorIndicesCalculator: Bifactor Indices Calculator

#### Documented in ECV_GSECV_SGECV_SSIECV

#' ECV_SS
#'
#' Computes an ECV index for all factors which can be interpreted as the proportion of common
#' variance of the items in each factor which is due to that factor;
#' \code{ECV_SS} should be read 'ECV of a specific factor with respect to itself.' Here, ECV is computed
#' only with respect to items which load on the factor. Note that \code{ECV_SS} of the general factor
#' is simply the ECV. Stucky and Edelen (2015, p. 201) do not refer to this form of ECV. In the Excel
#' version of the bifactor indices calculator (Dueber, 2017), this index is referred to as
#' 'ECV (NEW).' \code{ECV_SS} is useful in that it can be computed when there is no general factor, such
#' as in a two-tier model, and interpreted in the same way as ECV for general factors.
#'
#' \code{ECV_SS} is called by \code{\link{bifactorIndices}} and the various convenience functions
#' for exploratory models and/or Mplus output,
#' which are the only functions in this package intended for casual users.
#'
#' @param Lambda is a matrix of factor loadings. Be sure that all factors have the same variance
#'  before calling this function.
#'
#' @return A vector of ECVs for all factors
#'
#' @examples
#' Lambda <- matrix(c(.82, .10,   0,   0,
#'                    .77, .35,   0,   0,
#'                    .79, .32,   0,   0,
#'                    .66, .39,   0,   0,
#'                    .51,   0, .71,   0,
#'                    .56,   0, .43,   0,
#'                    .68,   0, .13,   0,
#'                    .60,   0, .50,   0,
#'                    .83,   0,   0, .47,
#'                    .60,   0,   0, .27,
#'                    .78,   0,   0, .28,
#'                    .55,   0,   0, .75),
#'                    ncol = 4, byrow = TRUE)
#' colnames(Lambda) <- c("General", "SF1", "SF2", "SF3")
#' ECV_SS(Lambda)
#'
#'
#' @references
#' Dueber, D. M. (2017). Bifactor Indices Calculator: A Microsoft Excel-based tool to calculate various indices relevant to bifactor CFA models. \doi{10.13023/edp.tool.01}
#'
#' Stucky, B. D., & Edelen, M. O. (2015). Using hierarchical IRT models to create unidimensional measures from multidimensional data. In S. P. Reise & D. A. Revicki (Eds.), \emph{Handbook of item response theory modeling: Applications to typical performance assessment} (pp.183-206). New York: Routledge.
#'
#' @export
#'
#'
ECV_SS <- function(Lambda) {
ECV_SS_C <- function(Fac, Lambda) {
## Isolate the items which load on the chosen factor FAC
inFactor <- Lambda[,Fac] != 0
L2 = Lambda^2
## Compute the appropriate ratio of sums
sum(L2[,Fac]*inFactor)/sum(L2*inFactor)
}
ECV_results <- sapply(1:ncol(Lambda), ECV_SS_C, Lambda)
names(ECV_results) <- colnames(Lambda)
ECV_results
}

#' ECV_SG
#'
#' Computes an ECV index for all factors which can be interpreted as the proportion of
#' common variance of all items which is due to the specific factor;
#' \code{ECV_SG} should be read 'ECV of a specific factor with respect to the general
#' factor.' Here,
#' ECV is computed with respect to the items of the general factor using the specific factor loadings in
#' the numerator; Stucky and Edelen (2015, p. 199)
#' refer to this index simply as 'specific-dimension ECV.' Note that \code{ECV_SG} of the general factor
#' is simply the ECV. In the Excel version of the Bifactor
#' Indices Calculator (Dueber, 2017), this form of ECV is referred to as 'ECV (S&E).'
#
#' \code{ECV_SG} is called by \code{\link{bifactorIndices}} and the various convenience functions
#' for exploratory models and/or Mplus output,
#' which are the only functions in this package intended for casual users.
#'
#' @param Lambda is a matrix of factor loadings. Be sure that all factors have the same
#' variance before calling this function.
#'
#' @return A vector of ECVs for all factors
#'
#' @examples
#' Lambda <- matrix(c(.82, .10,   0,   0,
#'                    .77, .35,   0,   0,
#'                    .79, .32,   0,   0,
#'                    .66, .39,   0,   0,
#'                    .51,   0, .71,   0,
#'                    .56,   0, .43,   0,
#'                    .68,   0, .13,   0,
#'                    .60,   0, .50,   0,
#'                    .83,   0,   0, .47,
#'                    .60,   0,   0, .27,
#'                    .78,   0,   0, .28,
#'                    .55,   0,   0, .75),
#'                    ncol = 4, byrow = TRUE)
#' colnames(Lambda) <- c("General", "SF1", "SF2", "SF3")
#' ECV_GS(Lambda)
#'
#' @references
#' Dueber, D. M. (2017). Bifactor Indices Calculator: A Microsoft Excel-based tool to
#' calculate various indices relevant to bifactor CFA models. \doi{10.13023/edp.tool.01}
#'
#' Stucky, B. D., & Edelen, M. O. (2015). Using hierarchical IRT models to create
#' unidimensional measures from multidimensional data. In S. P. Reise & D. A. Revicki
#' (Eds.), \emph{Handbook of item response theory modeling: Applications to typical
#' performance assessment} (pp.183-206). New York: Routledge.
#'
#' @export
#'
#'

ECV_SG <- function(Lambda) {
if (is.null(getGen(Lambda))) return(NULL)
ECV_SG_C <- function(Fac, Lambda) {
## Make a matrix of logical vectors for non-zero elements of Lambda.
inFactor <- Lambda[,Fac] != 0
L2 <- Lambda^2
## Compute the appropriate ratio of sums
sum(L2[,Fac]*inFactor)/sum(L2)
}
ECV_results <- sapply(1:ncol(Lambda), ECV_SG_C, Lambda)
names(ECV_results) <- colnames(Lambda)
ECV_results
}

#' ECV_GS
#'
#' Computes an ECV index for all factors which can be interpreted as the proportion of common
#' variance of the items in each specific factor which is due to the general factor;
#' \code{ECV_GS} should be read 'ECV of the general factor with respect to a specific
#' factor.' Here, ECV is
#' computed only with respect to the items of a specific factor using the general factor
#' Stucky and Edelen (2015, p. 201) refer to this index as the 'within-domain ECV' for the
#' specific factor. In the
#' Excel version of the bifactor indices calculator (Dueber, 2017), this index is not computed.
#'
#' \code{ECV_GS} is called by \code{\link{bifactorIndices}} and the various convenience functions
#' for exploratory models and/or Mplus output,
#' which are the only functions in this package intended for casual users.
#'
#' @param Lambda is a matrix of factor loadings. Be sure that all factors have the same variance
#' before calling this function.
#'
#' @return A vector of ECVs for all factors
#'
#' @examples
#' Lambda <- matrix(c(.82, .10,   0,   0,
#'                    .77, .35,   0,   0,
#'                    .79, .32,   0,   0,
#'                    .66, .39,   0,   0,
#'                    .51,   0, .71,   0,
#'                    .56,   0, .43,   0,
#'                    .68,   0, .13,   0,
#'                    .60,   0, .50,   0,
#'                    .83,   0,   0, .47,
#'                    .60,   0,   0, .27,
#'                    .78,   0,   0, .28,
#'                    .55,   0,   0, .75),
#'                    ncol = 4, byrow = TRUE)
#' colnames(Lambda) <- c("General", "SF1", "SF2", "SF3")
#' ECV_GS(Lambda)
#'
#' @references
#' Dueber, D. M. (2017). Bifactor Indices Calculator: A Microsoft Excel-based tool to calculate
#' various indices relevant to bifactor CFA models. \doi{10.13023/edp.tool.01}
#'
#' Stucky, B. D., & Edelen, M. O. (2015). Using hierarchical IRT models to create unidimensional
#' measures from multidimensional data. In S. P. Reise & D. A. Revicki (Eds.), \emph{Handbook of item
#' response theory modeling: Applications to typical performance assessment} (pp.183-206).
#' New York: Routledge.
#'
#' @export
#'
#'

ECV_GS <- function(Lambda) {

ECV_GS_C <- function(Fac, Lambda, genFac) {
## Make a matrix of logical vectors for non-zero elements of Lambda.
inFactor <- Lambda[,Fac] != 0
L2 <- Lambda^2
## Compute the appropriate ratio of sums
sum(L2[,genFac]*inFactor)/sum(L2*inFactor)
}
## ECV_GS only makes sense when there is a general factor
if (is.null(getGen(Lambda))) return(NULL)
genFac <- getGen(Lambda)

ECV_results <- sapply(1:ncol(Lambda), ECV_GS_C, Lambda, genFac)
names(ECV_results) <- colnames(Lambda)
ECV_results
}

#' IECV
#'
#' Computes an ECV index for each item which can be interpreted as the proportion of common
#' variance of that item due to the general factor. Stucky and Edelen (2015, p. 201) define
#' I-ECV, which is also computed in the Excel version of the bifactor indices calculator
#' (Dueber, 2017).
#'
#' \code{IECV} is called by \code{\link{bifactorIndices}} and the various convenience functions
#' for exploratory models and/or Mplus output,
#' which are the only functions in this package intended for casual users.
#'
#' @param Lambda is a matrix of factor loadings. Be sure that all factors have the same variance
#' before calling this function.
#'
#' @return A vector of item ECVs
#'
#' @examples
#' Lambda <- matrix(c(.82, .10,   0,   0,
#'                    .77, .35,   0,   0,
#'                    .79, .32,   0,   0,
#'                    .66, .39,   0,   0,
#'                    .51,   0, .71,   0,
#'                    .56,   0, .43,   0,
#'                    .68,   0, .13,   0,
#'                    .60,   0, .50,   0,
#'                    .83,   0,   0, .47,
#'                    .60,   0,   0, .27,
#'                    .78,   0,   0, .28,
#'                    .55,   0,   0, .75),
#'                    ncol = 4, byrow = TRUE)
#' colnames(Lambda) <- c("General", "SF1", "SF2", "SF3")
#' IECV(Lambda)
#'
#' @references
#' Dueber, D. M. (2017). Bifactor Indices Calculator: A Microsoft Excel-based tool to calculate
#' various indices relevant to bifactor CFA models. \doi{10.13023/edp.tool.01}
#'
#' Stucky, B. D., & Edelen, M. O. (2015). Using hierarchical IRT models to create unidimensional
#' measures from multidimensional data. In S. P. Reise & D. A. Revicki (Eds.), \emph{Handbook of item
#' response theory modeling: Applications to typical performance assessment} (pp.183-206).
#' New York: Routledge.
#'
#' @export
#'
#'

IECV <- function(Lambda) {

## Compute IECV for single item
IECV_C <- function(Item, Lambda, genFac) {
L2 <- Lambda^2
IECV <- L2[Item, genFac]/sum(L2[Item,])
names(IECV) <- rownames(Lambda)[Item]
IECV
}

## I-ECV only makes sense when there is a general factor
if (is.null(getGen(Lambda))) return(NULL)
genFac <- getGen(Lambda)
IECV_results <- sapply(1:nrow(Lambda), IECV_C, Lambda, genFac)
names(IECV_results) <- rownames(Lambda)
IECV_results
}


## Try the BifactorIndicesCalculator package in your browser

Any scripts or data that you put into this service are public.

BifactorIndicesCalculator documentation built on May 13, 2021, 1:08 a.m.