R/tssem.R

Defines functions tssemParaVar tssem2 wls .align.wls.filter .align.wls.acov tssem1 tssem1REM tssem1FEM

Documented in tssem1 tssem1FEM tssem1REM tssem2 tssemParaVar wls

tssem1FEM <- function(Cov, n, cor.analysis=TRUE, model.name=NULL,
                      cluster=NULL, suppressWarnings=TRUE, silent=TRUE,
                      run=TRUE, ...) {
  .check.cov.names(Cov)
  if (!is.list(Cov) || !length(Cov) ||
      any(!vapply(Cov, is.matrix, logical(1))))
    stop("'Cov' must be a nonempty list of covariance/correlation matrices.")
  if (length(Cov) != length(n))
    stop("Lengths of 'Cov' and 'n' are different.")
  Cov <- .align.study.matrices(Cov)

  ## Function to mark diagonals as NA when all correlation coefficients of the variable are NA
  ## assuming matrices are symmetric
  addDiagNA <- function(x) {
      add_NA <- function(y) {
          for(i in 1:nrow(y)) {
              ## All elements in the row except the diagonal are NA
              if (sum(is.na(y[, i]))==(nrow(y)-1)) y[i,i] <- NA
          }
          y
      }
      if (is.list(x)) lapply(x, add_NA) else add_NA(x)
  }
  ## Mark the diagonals as NA when all correlation coefficients are NA
  if (cor.analysis) Cov <- addDiagNA(Cov)
  empty <- which(vapply(Cov, function(x) all(is.na(diag(x))), logical(1)))
  if (length(empty))
    stop("Study ", paste(empty, collapse=", "), if (cor.analysis)
         " has no observed correlations; remove it from the correlation analysis." else
         " has no observed variances; remove it from the covariance analysis.")

  ## Smooth non-symmetric matrices probably due to rounding
  ## assuming no input error in the matrices
  if (is.list(Cov)) {
      Cov <- lapply(Cov, function(x) {x <- (x+t(x))/2; x})
  } else {
      Cov <- (Cov+t(Cov))/2
  }

  ## FEM can omit whole variables, but mxData cannot use a covariance matrix
  ## with a missing entry among the variables that remain in a study.
  if (any(vapply(Cov, function(x) {
    present <- !is.na(diag(x))
    anyNA(x[present, present, drop=FALSE])
  }, logical(1))))
    stop("Fixed-effects TSSEM requires complete correlations among variables present in each study; use method='REM' for partially missing correlations.")

  ## Split the data by cluster
  if (!is.null(cluster)) {
    data.cluster <- tapply(Cov, cluster, function(x) {x})
    n.cluster <- tapply(n, cluster, function(x) {x})
    out <- list()
    for (i in seq_along(data.cluster)) {
      ## Need to correct it to tssem1()
      out[[i]] <- tssem1FEM(data.cluster[[i]], n.cluster[[i]],
                           cor.analysis=cor.analysis, model.name=model.name,
                           suppressWarnings=suppressWarnings, silent=silent,
                           run=run, ...)
    }
    names(out) <- names(data.cluster)
    class(out) <- "tssem1FEM.cluster"
    out
  } else {
    no.groups <- length(Cov)
    no.var <- ncol(Cov[[1]])

    ## Get the original variable names
    original.names <- colnames(Cov[[1]])

    var.names <- paste("x", 1:no.var, sep = "")
    ## Convert variable labels to x1, x2, ...
    Cov <- lapply(Cov, function(x) {dimnames(x) <- list(var.names, var.names); x})
    total.n <- sum(n)

    ## Check positive definiteness of data
    ## Print warning rather than stop
    isPD <- is.pd(Cov)
    if (!all(isPD))
        warning(paste("Group ", (1:no.groups)[!isPD], " is not positive definite.", sep = ""))

    ## Prepare starting values based on covariance matrices
    sv <- .startValues(Cov, cor.analysis = FALSE)
      
    ## matrix of labels; only use the lower triangle
    ## Fixed a bug reported by John Ma when there are more than 120 variables by replacing " " with "_"  
    ps.labels <- outer(1:no.var, 1:no.var, function(x, y) paste0("s", x, "_", y))
    if (cor.analysis==TRUE) {
      S <- mxMatrix(type="Stand", nrow=no.var, ncol=no.var, free=TRUE, values=vechs(cov2cor(sv)),
                    labels=vechs(ps.labels), name="S")
    } else {
      ## Set lower bound on variances
      lbound <- matrix(NA, nrow=no.var, ncol=no.var)
      Diag(lbound) <- 0.00001
      S <- mxMatrix(type="Symm", nrow=no.var, ncol=no.var, free=TRUE, values=vech(sv),
                    labels=vech(ps.labels), lbound=lbound, name="S")
    }
      
    ## Index for missing variables: only check the diagonals only!!!
    miss.index <- lapply(Cov, function(x) { is.na(Diag(x)) })

    ## complete.index <- NULL
    ## for (i in no.groups:1) {
    ##     if (sum(!miss.index[[i]], na.rm = TRUE) == no.var)
    ##         complete.index = i
    ## }
    ## if (is.null(complete.index))
    ##     stop("It is expected that at least one study has complete data!")

    ## if ( sum(!miss.index[[1]], na.rm = TRUE) != no.var )
    ##     stop("There should be no missing data in the first group.")

    for (i in 1:no.groups) {
        no.var.i <- sum(!miss.index[[i]], na.rm = TRUE)
        miss.index.i <- miss.index[[i]]
        Cov.i <- Cov[[i]][!miss.index.i, !miss.index.i]
        ## dimnames(Cov.i) <- list(var.names[!miss.index.i], var.names[!miss.index.i])

        # Prepare matrices for calculations
        if (cor.analysis) {
            if (is.null(model.name)) model.name <- "TSSEM1 Correlation"
            SD <- Diag(paste(sqrt(Diag(sv)), "*sd", i, "_", 1:no.var, sep=""))
            # Fixed a bug when SD is a scalar
            SD <- SD[!miss.index.i, , drop=FALSE]
            SD <- as.mxMatrix(SD)
        } else {
            if (is.null(model.name)) model.name <- "TSSEM1 Covariance"
            SD <- Diag(rep(1, no.var))
            SD <- SD[!miss.index.i, , drop=FALSE]
            SD <- as.mxMatrix(SD)
        }
        # Expected covariance matrix
        expC <- mxAlgebra(SD %&% S, name="expC", dimnames=list(var.names[!miss.index.i],
                          var.names[!miss.index.i]))

        fitFunction <- mxFitFunctionML()

        ## Fixed a bug when Cov[[i]][, , ] is a scalar
        g.model <- paste("g", i, " <- mxModel(\"g", i, "\", S, SD, expC, mxData(observed=Cov[[",i,"]][!miss.index[[",i,"]],!miss.index[[",i,"]], drop=FALSE], type=\"cov\", numObs=n[", i,
                "]), fitFunction, mxExpectationNormal(covariance=\"expC\", means=NA, dimnames=var.names[!miss.index[[", i, "]]]))", sep = "")
        eval(parse(text = g.model))
    }

    ## Replaced mxFitFunctionAlgebra() with mxFitFunctionMultigroup()  
    tssem1.model <- paste0("tssem1 <- mxModel(\"", model.name, "\", S, ",
                          paste0("g", 1:no.groups, collapse = ","),
                          ", mxFitFunctionMultigroup(c(", paste0("\"g", 1:no.groups, "\"", collapse=","), ")))")
    ## mgFitFn <- paste0("mxFitFunctionMultigroup(c(", paste0("\"g", 1:no.groups, "\"", collapse=","), ")")
      
    eval(parse(text = tssem1.model))

    ## Return mx model without running the analysis
    if (run==FALSE) return(tssem1)

    # try to run it with error message as output
    ## mx.fit <- mxRun(tssem1)
    mx.fit <- tryCatch(mxRun(tssem1, suppressWarnings = suppressWarnings, silent=silent, ...),
                       error = function(e) e)

    ## It is useful to return error for computer simulation.  
    if (inherits(mx.fit, "error")) {
        warning(print(mx.fit))
        out <- mx.fit
    } else {
        ## Calculate 2LL of the saturated and independence models and the DF of independence model
        baseMinus2LL <- tryCatch(.minus2LL(x=Cov, n=n), error = function(e) e)
        if (inherits(baseMinus2LL, "error"))
          warning("Could not calculate baseline likelihoods: ", conditionMessage(baseMinus2LL))

        out <- list(call = match.call(), cor.analysis=cor.analysis, data=Cov, n = n,
                    baseMinus2LL = baseMinus2LL, mx.model=tssem1, mx.fit = mx.fit,
                    original.names=original.names)
        class(out) <- "tssem1FEM"
    }
    return(out)
      
  }
}

tssem1REM <- function(Cov, n, cor.analysis=TRUE, RE.type=c("Diag", "Symm", "Zero", "User"),
                      RE.startvalues=0.1, RE.lbound = 1e-10, RE.constraints=NULL,
                      I2="I2q", acov=c("weighted", "individual", "unweighted"),
                      asyCovOld=FALSE, model.name=NULL, suppressWarnings=TRUE, silent=TRUE,
                      run=TRUE, ...) {
  .check.cov.names(Cov)
  ## It handles missing effect sizes rather than missing correlations. Thus, it is more flexible than tssem1FEM().
  ## Missing effect sizes are indicated in the observed data; sampling
  ## covariances follow the selected working-matrix assumption.

  acov <- match.arg(acov, c("weighted", "individual", "unweighted"))
    
  ## Throw an error when df and n are in different lengths.
  if (length(Cov) != length(n)) stop("Lengths of 'Cov' and 'n' are different.")
  Cov <- .align.study.matrices(Cov)
    
  ## A reported covariance cannot be standardized when either of its
  ## variances is missing. Legacy individual weights also cannot use it
  ## without inventing a variance, even in covariance analysis.
  check.reported.variance <- function(i) {
    x <- Cov[[i]]
    missing.variance <- which(is.na(diag(x)))
    if (!length(missing.variance)) return(invisible(NULL))
    affected <- vapply(missing.variance, function(j) {
      others <- setdiff(seq_len(nrow(x)), j)
      any(!is.na(x[j, others])) || any(!is.na(x[others, j]))
    }, logical(1))
    if (any(affected)) {
      j <- missing.variance[which(affected)[1L]]
      variable <- if (is.null(colnames(x))) as.character(j) else colnames(x)[j]
      stop("Study ", i, " reports a covariance involving variable '", variable,
           "' but its variance is missing. Supply the variance",
           if (!cor.analysis) " or choose an appropriate pooled working matrix" else " to calculate the correlation", ".", call.=FALSE)
    }
    invisible(NULL)
  }
  if (cor.analysis || (asyCovOld && acov == "individual"))
    for (i in seq_along(Cov)) check.reported.variance(i)

  ## Get the original variable names
  original.names <- colnames(Cov[[1]])

  ## Calculate the asymptotic sampling covariance matrix of the correlation matrix
  if (asyCovOld) {
      ## Preserve the historical placeholder for wholly missing variables
      ## with individual weights, but never replace a missing covariance
      ## between observed variables. For pooled weights, average the actual
      ## observed entries rather than including artificial zeros.
      if (acov == "individual") {
        my.complete <- lapply(seq_along(Cov), function(i) {
          x <- Cov[[i]]
          .check.asycovold.missing(x)
          if (cor.analysis) Diag(x)[is.na(Diag(x))] <- 1
          else Diag(x)[is.na(Diag(x))] <- mean(Diag(x), na.rm=TRUE)
          x[is.na(x)] <- 0
          x
        })
      } else my.complete <- Cov
      acovR <- asyCovOld(x=my.complete, n=n, cor.analysis=cor.analysis, dropNA=FALSE, as.matrix=TRUE, acov=acov)
  } else {
      ## Unknown sampling covariances are propagated by asyCov().
      acovR <- asyCov(x=Cov, n=n, cor.analysis=cor.analysis, as.matrix=TRUE, acov=acov)
  }
    
  ## Fixed a bug that Cov is covariance matrix while cor.analysis is TRUE
  ## When cor.analysis=TRUE, the old version just takes the lower triangle without converting covariance into correlation.
  if (cor.analysis) {
    ## Convert possible covariance matrices into correlation matrices
    ## When there are NA in diagonas, they become 1 after cov2cor()
    ## It is fine as the diagonals are not used in cor.analysis=TRUE
    ES <- list2matrix(x=suppressWarnings(lapply(Cov, cov2cor)), diag=FALSE)
  } else {
    ES <- list2matrix(x=Cov, diag=TRUE)
  }
  ## meta() removes effects whose sampling variances are missing. Diagnose
  ## that before the fit so a reported statistic is never silently dropped.
  no.es <- ncol(ES)
  index <- matrix(NA_integer_, no.es, no.es)
  index[lower.tri(index, diag=TRUE)] <- seq_len(no.es*(no.es+1L)/2L)
  sampling.variances <- acovR[, diag(index), drop=FALSE]
  missing.variance <- !is.na(ES) & !is.finite(sampling.variances)
  if (any(missing.variance)) {
    position <- which(missing.variance, arr.ind=TRUE)[1L, ]
    effect <- if (is.null(colnames(ES))) as.character(position[2L]) else colnames(ES)[position[2L]]
    stop("Study ", position[1L], " reports '", effect,
         "' but its sampling variance is unavailable. Supply the missing covariance information or choose an appropriate working matrix.", call.=FALSE)
  }

  if (is.null(model.name)) {
    if (cor.analysis) {
      model.name <- "TSSEM1 Correlation"
    } else {
      model.name <- "TSSEM1 Covariance"
    }
  }

  RE.type <- match.arg(RE.type, c("Diag", "Symm", "Zero", "User"))
  switch( RE.type,
         Symm = mx.fit <- meta(y=ES, v=acovR, model.name=model.name, I2=I2, RE.startvalues=RE.startvalues,
                               RE.lbound=RE.lbound, suppressWarnings=suppressWarnings, silent=silent, run=run, ...),
         Diag = mx.fit <- meta(y=ES, v=acovR, model.name=model.name, I2=I2,
                               RE.constraints=Diag(paste0(RE.startvalues, "*Tau2_", 1:no.es, "_", 1:no.es)),
                               RE.lbound=RE.lbound, suppressWarnings=suppressWarnings, silent=silent, run=run, ...),
         Zero = mx.fit <- meta(y=ES, v=acovR, model.name=model.name, I2=I2, RE.constraints=matrix(0, ncol=no.es, nrow=no.es),
                               suppressWarnings=suppressWarnings, silent=silent, run=run, ...),
         User = mx.fit <- meta(y=ES, v=acovR, model.name=model.name, I2=I2, RE.constraints=RE.constraints,
                               suppressWarnings=suppressWarnings, silent=silent, run=run, ...) )

  ## Return mx model without running the analysis
  if (run==FALSE) return(mx.fit)

  ## if (RE.diag.only==TRUE) {
  ##   ## No covariance between random effects
  ##   mx.fit <- meta(y=ES, v=acovR, model.name=model.name, I2=I2,
  ##                    RE.constraints=diag(x=paste(RE.startvalues, "*Tau2_", 1:no.es, "_", 1:no.es, sep=""),
  ##                                        nrow=no.es, ncol=no.es), RE.lbound=RE.lbound)
  ## } else {
  ##   mx.fit <- meta(y=ES, v=acovR, model.name=model.name, I2=I2, RE.startvalues=RE.startvalues, RE.lbound=RE.lbound)
  ## }

  out <- list(total.n=sum(n), cor.analysis=cor.analysis, RE.type=RE.type, no.es=no.es, original.names=original.names)
  out <- c(out, mx.fit)
  class(out) <- c("tssem1REM", "meta")
  return(out)
}



#' First Stage of the Two-Stage Structural Equation Modeling (TSSEM)
#' 
#' It conducts the first stage analysis of TSSEM by pooling
#' correlation/covariance matrices. \code{tssem1FEM()} and \code{tssem1REM()}
#' use fixed- and random-effects models, respectively. \code{tssem1()} is a
#' wrapper of these functions.
#' The fixed-effects summary reports RMSEA using total sample size N as the
#' denominator; see \code{\link[metaSEM]{summary}} for the formula.
#' Variable names and data column names must not contain periods. Rename them consistently, for example \code{x.1} to \code{x_1}, and check that the new names are unique. Study, group, and cluster values may contain periods.
#' 
#' 
#' @aliases tssem1 tssem1FEM tssem1REM
#' @usage
#' tssem1(Cov, n, method = c("REM", "FEM"), cor.analysis = TRUE,
#'     cluster = NULL, RE.type = c("Diag", "Symm", "Zero",
#'         "User"), RE.startvalues = 0.1, RE.lbound = 1e-10,
#'     RE.constraints = NULL, I2 = "I2q", acov = c("weighted",
#'         "individual", "unweighted"), asyCovOld = FALSE,
#'     model.name = NULL, suppressWarnings = TRUE, silent = TRUE,
#'     run = TRUE, ...)
#' tssem1FEM(Cov, n, cor.analysis = TRUE, model.name = NULL,
#'     cluster = NULL, suppressWarnings = TRUE, silent = TRUE,
#'     run = TRUE, ...)
#' tssem1REM(Cov, n, cor.analysis = TRUE, RE.type = c("Diag",
#'     "Symm", "Zero", "User"), RE.startvalues = 0.1,
#'     RE.lbound = 1e-10, RE.constraints = NULL, I2 = "I2q",
#'     acov = c("weighted", "individual", "unweighted"),
#'     asyCovOld = FALSE, model.name = NULL, suppressWarnings = TRUE,
#'     silent = TRUE, run = TRUE, ...)
#' @param Cov A list of correlation/covariance matrices. For both TSSEM methods,
#' named matrices must all have unique row and column names for the
#' same variables; each study is aligned to the first study's variable order
#' before pooling and calculating sampling covariances. If all matrices are
#' unnamed, their positions are used. Fixed-effects TSSEM requires complete
#' correlations among the variables present in each study; random-effects
#' TSSEM can handle partially missing correlations. It rejects a reported
#' statistic whose sampling variance is unavailable rather than silently
#' removing that statistic. Supply the missing information or choose an
#' appropriate pooled working matrix. For correlation analysis, reported
#' covariances require both corresponding variances so they can be standardized.
#' Fixed-effects covariance analysis retains studies reporting only a variance.
#' Fixed-effects correlation analysis rejects studies with no observed correlations;
#' covariance analysis rejects studies with no observed variances.
#' @param n A vector of sample sizes
#' @param method Either \code{"REM"} (default if missing) or \code{"FEM"}.  If
#' it is \code{"REM"}, a random-effects meta-analysis will be applied. If it is \code{"FEM"},
#' a fixed-effects meta-analysis will be applied.
#' @param cor.analysis Logical. The output is either a pooled correlation or a
#' covariance matrix.
#' @param cluster A character vector in \code{tssem3L1} and \code{tssemRobust1}
#' or a vector of characters or numbers indicating the clusters in
#' \code{tssem1}. Analyses will be conducted for each cluster. It will be
#' ignored when \code{method="REM"}.
#' @param RE.type Either \code{"Diag"}, \code{"Symm"}, \code{"Zero"} or
#' \code{"User"}. If it is \code{"Diag"} (default if missing), a diagonal
#' matrix is used for the random effects meaning that the random effects are
#' independent. If it is \code{"Symm"}, a symmetric matrix is used for the
#' random effects on the covariances among the correlation (or covariance)
#' vectors. If it is \code{"Zero"}, there is no random effects which is similar
#' to the conventional Generalized Least Squares (GLS) approach to
#' fixed-effects analysis. If it is \code{"User"}, the user has to specify the variance
#' component via the \code{RE.constraints} argument. This argument will be
#' ignored when \code{method="FEM"}.
#' @param RE.startvalues Starting values on the diagonals of the variance
#' component of the random effects. It will be ignored when
#' \code{method="FEM"}.
#' @param RE.lbound Lower bounds on the diagonals of the variance component of
#' the random effects. It will be ignored when \code{method="FEM"}.
#' @param RE.constraints A \eqn{p*}{p*} x \eqn{p*}{p*} matrix specifying the
#' variance components of the random effects, where \eqn{p*}{p*} is the number
#' of effect sizes. If the input is not a matrix, it is converted into a matrix
#' by \code{as.matrix()}. The default is that all covariance/variance
#' components are free. The format of this matrix follows
#' \code{\link[metaSEM]{as.mxMatrix}}. Elements of the variance components can
#' be constrained equally by using the same labels. If a zero matrix is
#' specified, it becomes a fixed-effects meta-analysis.
#' @param I2 Possible options are \code{"I2q"}, \code{"I2hm"} and
#' \code{"I2am"}. They represent the \code{I2} calculated by using a typical
#' within-study sampling variance from the Q statistic, the harmonic mean and
#' the arithmetic mean of the within-study sampling variances (Xiong, Miller, &
#' Morris, 2010). More than one options are possible. If
#' \code{intervals.type="LB"}, 95\% confidence intervals on the heterogeneity
#' indices will be constructed.
#' @param acov If it is \code{individual}, the sampling variance-covariance
#' matrices are calculated based on individual correlation/covariance matrix.
#' If it is either \code{unweighted} or \code{weighted} (the default), the
#' average correlation/covariance matrix is calculated based on the unweighted
#' or weighted mean with the sample sizes. The average correlation/covariance
#' matrix is used to calculate the sampling variance-covariance matrices. This
#' argument is ignored with the \code{method="FEM"} argument.
#' @param asyCovOld Whether to use the legacy Hessian-based method. It requires
#' complete covariances among retained variables in its working matrix.
#' \code{asyCov()} is preferred. See \code{\link[metaSEM]{asyCov}}.
#' @param model.name A string for the model name in
#' \code{\link[OpenMx]{mxModel}}.
#' @param suppressWarnings Logical. If \code{TRUE}, warnings are suppressed. It
#' is passed to \code{\link[OpenMx]{mxRun}}.
#' @param silent Logical. An argument to be passed to
#' \code{\link[OpenMx]{mxRun}}
#' @param run Logical. If \code{FALSE}, only return the mx model without
#' running the analysis.
#' @param \dots Further arguments to be passed to \code{\link[OpenMx]{mxRun}}
#' @return Either an object of class \code{tssem1FEM} for fixed-effects TSSEM,
#' an object of class \code{tssem1FEM.cluster} for fixed-effects TSSEM with
#' \code{cluster} argument, or an object of class \code{tssem1REM} for
#' random-effects TSSEM.
#' @author Mike W.-L. Cheung <mikewlcheung@@nus.edu.sg>
#' @seealso \code{\link[metaSEM]{wls}}, \code{\link[metaSEM]{Cheung09}},
#' \code{\link[metaSEM]{Becker92}}, \code{\link[metaSEM]{Digman97}},
#' \code{\link[metaSEM]{issp89}}, \code{\link[metaSEM]{issp05}}
#' @references Cheung, M. W.-L. (2014). Fixed- and random-effects meta-analytic
#' structural equation modeling: Examples and analyses in R. \emph{Behavior
#' Research Methods}, \bold{46}, 29-40.
#' 
#' Cheung, M. W.-L. (2013). Multivariate meta-analysis as structural equation
#' models. \emph{Structural Equation Modeling}, \bold{20}, 429-454.
#' 
#' Cheung, M. W.-L., & Chan, W. (2005). Meta-analytic structural equation
#' modeling: A two-stage approach. \emph{Psychological Methods}, \bold{10},
#' 40-64.
#' 
#' Cheung, M. W.-L., & Chan, W. (2009). A two-stage approach to synthesizing
#' covariance matrices in meta-analytic structural equation modeling.
#' \emph{Structural Equation Modeling}, \bold{16}, 28-53.
#' @keywords tssem
tssem1 <- function(Cov, n, method=c("REM", "FEM"), cor.analysis=TRUE, cluster=NULL,
                   RE.type=c("Diag", "Symm", "Zero", "User"), RE.startvalues=0.1, RE.lbound=1e-10,
                   RE.constraints=NULL, I2="I2q", acov=c("weighted", "individual", "unweighted"),
                   asyCovOld=FALSE, model.name=NULL, suppressWarnings=TRUE, silent=TRUE, run=TRUE, ...) {
  method <- match.arg(method)
  switch(method,
    FEM = out <- tssem1FEM(Cov=Cov, n=n, cor.analysis=cor.analysis, model.name=model.name,
                          cluster=cluster, suppressWarnings=suppressWarnings, silent=silent, run=run, ...),
    REM = out <- tssem1REM(Cov=Cov, n=n, cor.analysis=cor.analysis, RE.type=RE.type,
                          RE.startvalues=RE.startvalues, RE.lbound=RE.lbound, RE.constraints=RE.constraints,
                          I2=I2, acov=acov, asyCovOld=asyCovOld, model.name=model.name,
                          suppressWarnings=suppressWarnings, silent=silent, run=run, ...) )
  out
}

## Known bug: wls() will fall into loop when the Amatrix is zero


#' Conduct a Correlation/Covariance Structure Analysis with WLS
#' 
#' It fits a correlation or covariance structure with weighted least squares
#' (WLS) estimation method where the inverse of the asymptotic covariance
#' matrix is used as the weight matrix. \code{tssem2} conducts the second stage
#' analysis of the two-stage structural equation modeling (TSSEM).
#' \code{tssem2} is a wrapper of \code{wls}.
#' WLS summaries use the supplied sample size \code{n} as the RMSEA denominator;
#' see \code{\link[metaSEM]{summary}} for the formula.
#' Variable names in the matrices, RAM model, and \code{subset.variables},
#' and ordinary parameter labels, must not contain periods. Rename them
#' consistently, e.g., \code{x.1} to \code{x_1}, and check for duplicate names.
#' 
#' 
#' @aliases wls tssem2
#' @param tssem1.obj An object of either class \code{tssem1FEM}, class
#' \code{tssem1FEM.cluster} or class \code{tssem1REM} returned from
#' \code{tssem1()}
#' @param Cov A \eqn{p}{p} x \eqn{p}{p} sample correlation/covariance matrix
#' where \eqn{p}{p} is the number of variables.
#' @param aCov A \eqn{p*}{p*} x \eqn{p*}{p*} asymptotic sampling covariance
#' matrix of either \code{\link[OpenMx]{vechs}} \code{(Cov)} or
#' \code{\link[OpenMx]{vech}} \code{(Cov)} where \eqn{p* = p(p-1)/2 }{p* =
#' p(p-1)/2} for correlation matrix and \eqn{p* = p(p+1)/2 }{p* = p(p+1)/2} for
#' covariance matrix. When both dimensions have recognizable, unique labels,
#' they are aligned to Cov before subsetting; reversed pair names are accepted
#' when they uniquely identify a pair. Partially matching labels are
#' rejected; wholly different labels produce a warning and use position.
#' Unnamed matrices use position.
#' @param n Sample size.
#' @param RAM A RAM object including a list of matrices of the model returned
#' from \code{\link[metaSEM]{lavaan2RAM}}. When the observed variable names
#' in RAM and Cov match, RAM is reordered to match Cov. If both have names
#' that do not match, positional matching is retained with a warning.
#' Unnamed inputs are matched by position. The number of observed variables
#' must match the matrix dimension. Separately supplied named Fmatrix rows are also
#' aligned to Cov; Amatrix and Smatrix retain their node order. Named node dimensions of the separately supplied matrices must agree in order.
#' @param Amatrix If \code{RAM} is not specified, an \code{Amatrix} is
#' required. An asymmetric matrix in the RAM specification with
#' \code{\link[OpenMx]{MxMatrix-class}}. If it is \code{NULL}, a matrix of zero
#' will be created. If it is a matrix, it will be converted into
#' \code{\link[OpenMx]{MxMatrix-class}} by the \code{as.mxMatrix} function.
#' @param Smatrix If \code{RAM} is not specified, an \code{Smatrix} is
#' required. A symmetric matrix in the RAM specification with
#' \code{\link[OpenMx]{MxMatrix-class}}. If it is a matrix, it will be
#' converted into \code{\link[OpenMx]{MxMatrix-class}} by the
#' \code{as.mxMatrix} function.
#' @param Fmatrix A filter matrix in the RAM specification with
#' \code{\link[OpenMx]{MxMatrix-class}}. If it is \code{NULL} (the default), an
#' identity matrix with the same dimensions of \code{Cov} will be created. If
#' it is a matrix, it will be converted into
#' \code{\link[OpenMx]{MxMatrix-class}} by the \code{as.mxMatrix} function. It
#' is not required when there is no latent variable.
#' @param diag.constraints Logical. This argument is ignored when
#' \code{cor.analysis=FALSE}. If \code{diag.constraints=TRUE}, the diagonals of
#' the model implied matrix would be constrained at 1 by nonlinear constraints.
#' The drawback is that standard error will not be generated. Parametric
#' bootstrap is used to estimate the standard error by drawing samples from
#' \eqn{\mathcal{N}(vech(Cov), asyCov)}{N(vech(Cov), asyCov)} for covariance
#' analysis and \eqn{\mathcal{N}(vechs(Cov), asyCov)}{N(vechs(Cov), asyCov)}
#' for correlation analysis while asyCov is treated as fixed. This process is
#' computationally intensive. A better approach is to request likelihood-based
#' confidence intervals (CIs) by specifying \code{intervals.type="LB"}.  If
#' \code{diag.constraints=FALSE} and \code{cor.analysis=TRUE}, the diagonals
#' are automatically constrained as ones by treating the error variances as
#' computed values rather than as parameters. Since the error variances are not
#' parameters, they are not reported. Fixed dependent residual variances are
#' ignored with a warning in this implicit method. In the explicit-constraint
#' method, fixed dependent residuals do not receive a unit-variance constraint;
#' a warning asks the user to verify the model-implied variance.
#' @param cor.analysis Logical. Analysis of correlation or covariance
#' structure. If \code{cor.analysis=TRUE}, \code{\link[OpenMx]{vechs}} is used
#' to vectorize \code{S}; otherwise, \code{\link[OpenMx]{vech}} is used to
#' vectorize \code{S}.
#' @param intervals.type Either \code{z} (default if missing) or \code{LB}. If
#' it is \code{z}, it calculates the 95\% Wald CIs based on the z statistic. If
#' it is \code{LB}, it calculates the 95\% likelihood-based CIs on the
#' parameter estimates. Please note that the z values and their associated p
#' values are based on the z statistic. They are not related to the
#' likelihood-based CIs.
#' @param mx.algebras A list of \code{\link[OpenMx]{mxMatrix}} or
#' \code{\link[OpenMx]{mxAlgebra}} objects on the \code{Amatrix},
#' \code{Smatrix}, and \code{Fmatrx}. It can be used to define new functions of
#' parameters and their LBCIs. For example, if the regression coefficients to
#' calculate an indirect effect are stored in A[1,2] and A[1,3], we may define
#' \code{list(ind=mxAlgebra(Amatrix[1,2]*Amatrix[1,3], name="ind"))} See the
#' examples in \code{\link[metaSEM]{Becker92}} and
#' \code{\link[metaSEM]{Hunter83}}. It should be noted that Fmatrix, Amatrix,
#' Smatrix, Iden (a \eqn{p}{p} x \eqn{p}{p} identity matrix), sampleS (sample
#' correlation or covariance matrix), impliedS1, impliedS (model implied
#' correlation or covariance matrix), vecS, invAcov, obj, One, select and
#' constraint and Ematrix (computed error variances when
#' \code{diag.constraints=FALSE}) have been defined internally. You should not
#' create new matrices using these names.
#' @param mxModel.Args A list of arguments passed to
#' \code{\link[OpenMx]{mxModel}}. These include, for example, additional
#' \code{\link[OpenMx]{mxMatrix}} and \code{\link[OpenMx]{mxConstraint}}.
#' @param model.name A string for the model name in
#' \code{\link[OpenMx]{mxModel}}. If it is missing, the default is "TSSEM2 (or
#' WLS) Analysis of Correlation Structure" for \code{cor.analysis=TRUE} and
#' "TSSEM2 (or WLS) Analysis of Covariance Structure" for
#' \code{cor.analysis=FALSE}.
#' @param subset.variables An optional character vector of variable names to
#' select variables in the analysis. For example, there are 10 variables in
#' \code{Cov}, say, x1 to x10. We may use \code{c("x1", "x2", "x3")} to select
#' three variables in the analysis. The order supplied here is used for both
#' the selected covariance matrix and its asymptotic covariance matrix.
#' @param suppressWarnings Logical. If \code{TRUE}, warnings are suppressed.
#' The argument to be passed to \code{\link[OpenMx]{mxRun}}.
#' @param silent Logical. An argument to be passed to
#' \code{\link[OpenMx]{mxRun}}
#' @param run Logical. If \code{FALSE}, only return the mx model without
#' running the analysis.
#' @param \dots Further arguments to be passed to \code{\link[OpenMx]{mxRun}}.
#' @return An object of class \code{wls} with a list of \item{call}{The matched
#' call} \item{Cov}{Input data of either a covariance or correlation matrix}
#' \item{asyCov}{The asymptotic covariance matrix of the input data}
#' \item{noObservedStat}{Number of observed statistics} \item{n}{Sample size}
#' \item{cor.analysis}{logical} \item{noConstraints}{Number of constraints
#' imposed on S} \item{indepModelChisq}{Chi-square statistic of the independent
#' model returned by \code{.indepwlsChisq} } \item{indepModelDf}{Degrees of
#' freedom of the independent model returned by \code{.indepwlsChisq}}
#' \item{mx.fit}{A fitted object returned from \code{\link[OpenMx]{mxRun}}}
#' @note If the input is a list of \code{tssem1.obj}, it returns a list of
#' results for each cluster.
#' @author Mike W.-L. Cheung <mikewlcheung@@nus.edu.sg>
#' @seealso \code{\link[metaSEM]{tssem1}}, \code{\link[metaSEM]{Becker92}},
#' \code{\link[metaSEM]{Digman97}}, \code{\link[metaSEM]{Hunter83}},
#' \code{\link[metaSEM]{issp89}}, \code{\link[metaSEM]{issp05}}
#' @references Bentler, P.M., & Savalei, V. (2010). Analysis of correlation
#' structures: current status and open problems. In Kolenikov, S., Thombs, L.,
#' & Steinley, D. (Eds.). \emph{Recent Methodological Developments in Social
#' Science Statistics} (pp. 1-36). Hoboken, NJ: Wiley.
#' 
#' Cheung, M. W.-L. (2010). Fixed-effects meta-analyses as multiple-group
#' structural equation models. \emph{Structural Equation Modeling}, \bold{17},
#' 481-509.
#' 
#' Cheung, M. W.-L. (2014). Fixed- and random-effects meta-analytic structural
#' equation modeling: Examples and analyses in R. \emph{Behavior Research
#' Methods}, \bold{46}, 29-40.
#' 
#' Cheung, M. W.-L., & Chan, W. (2005). Meta-analytic structural equation
#' modeling: A two-stage approach. \emph{Psychological Methods}, \bold{10},
#' 40-64.
#' 
#' Cheung, M. W.-L., & Chan, W. (2009). A two-stage approach to synthesizing
#' covariance matrices in meta-analytic structural equation modeling.
#' \emph{Structural Equation Modeling}, \bold{16}, 28-53.
#' 
#' Joreskog, K. G., Sorbom, D., Du Toit, S., & Du Toit, M. (1999). \emph{LISREL
#' 8: New Statistical Features.} Chicago: Scientific Software International.
#' 
#' McArdle, J. J., & MacDonald, R. P. (1984). Some algebraic properties of the
#' Reticular Action Model for moment structures. \emph{British Journal of
#' Mathematical and Statistical Psychology}, \bold{37}, 234-251.
#' @keywords tssem
#' @examples
#' 
#' \donttest{
#' #### Analysis of correlation structure
#' R1.labels <- c("a1", "a2", "a3", "a4")
#' 
#' R1 <- matrix(c(1.00, 0.22, 0.24, 0.18,
#'                0.22, 1.00, 0.30, 0.22,
#'                0.24, 0.30, 1.00, 0.24,
#'                0.18, 0.22, 0.24, 1.00), ncol=4, nrow=4,
#'                dimnames=list(R1.labels, R1.labels))
#' n <- 1000
#' acovR1 <- asyCov(R1, n)
#' 
#' #### One-factor CFA model using lavaan specification
#' model1 <- "f =~ a1 + a2 + a3 + a4"
#' 
#' RAM1 <- lavaan2RAM(model1, obs.variables=R1.labels)
#' 
#' wls.fit1a <- wls(Cov=R1, aCov=acovR1, n=n, RAM=RAM1,
#'                  cor.analysis=TRUE, intervals="LB")
#' summary(wls.fit1a)
#' 
#' ## One-factor CFA model using RAM specification
#' (A1 <- cbind(matrix(0, nrow=5, ncol=4),
#'              matrix(c("0.2*a1","0.2*a2","0.2*a3","0.2*a4",0),
#'              ncol=1)))
#' 
#' (S1 <- Diag(c("0.2*e1","0.2*e2","0.2*e3","0.2*e4",1)))
#' 
#' ## The first 4 variables are observed while the last one is latent.
#' (F1 <- create.Fmatrix(c(1,1,1,1,0), name="F1"))
#' 
#' wls.fit1b <- wls(Cov=R1, aCov=acovR1, n=n, Fmatrix=F1, Smatrix=S1, Amatrix=A1,
#'                  cor.analysis=TRUE, intervals="LB")
#' summary(wls.fit1b)
#' 
#' ## Select 3 variables to analyze
#' model2 <- "f =~ a1 + a2 + a3"
#' 
#' RAM2 <- lavaan2RAM(model2, obs.variables=R1.labels[-4])
#' 
#' wls.fit1c <- wls(Cov=R1, aCov=acovR1, n=n, RAM=RAM2,
#'                  cor.analysis=TRUE, subset.variables=c("a1", "a2", "a3"))
#' summary(wls.fit1c)
#' 
#' #### Multiple regression analysis using lavaan specification
#' R2.labels <- c("y", "x1", "x2")
#' 
#' R2 <- matrix(c(1.00, 0.22, 0.24, 
#'                0.22, 1.00, 0.30, 
#'                0.24, 0.30, 1.00), ncol=3, nrow=3,
#'                dimnames=list(R2.labels, R2.labels))
#' acovR2 <- asyCov(R2, n)
#' 
#' model3 <- "y ~ x1 + x2
#'            ## Variances of x1 and x2 are 1
#'            x1 ~~ 1*x1
#'            x2 ~~ 1*x2
#'            ## x1 and x2 are correlated
#'            x1 ~~ x2"
#' 
#' RAM3 <- lavaan2RAM(model3, obs.variables=R2.labels)
#' 
#' wls.fit2a <- wls(Cov=R2, aCov=acovR2, n=n, RAM=RAM3,
#'                  cor.analysis=TRUE, intervals="z")
#' summary(wls.fit2a)
#' 
#' 
#' #### Multiple regression analysis using RAM specification
#' 
#' ## A2: Regression coefficents
#' #    y x1 x2
#' # y  F T  T 
#' # x1 F F  F 
#' # x2 F F  F 
#' (A2 <- mxMatrix("Full", ncol=3, nrow=3, byrow=TRUE,
#'                free=c(FALSE, rep(TRUE, 2), rep(FALSE, 6)), name="A2"))
#' 
#' ## S2: Covariance matrix of free parameters
#' #    y x1 x2
#' # y  T F  F 
#' # x1 F F  F 
#' # x2 F T  F
#' (S2 <- mxMatrix("Symm", ncol=3, nrow=3, values=c(0.2,0,0,1,0.2,1),
#'                 labels=c("Var_y", NA, NA, NA, "Cov_x1_x2", NA),
#'                 free=c(TRUE,FALSE,FALSE,FALSE,TRUE,FALSE), name="S2"))
#' 
#' ## F may be ignored as there is no latent variable.
#' wls.fit2b <- wls(Cov=R2, aCov=acovR2, n=n, Amatrix=A2, Smatrix=S2,
#'                  cor.analysis=TRUE, intervals="LB")
#' summary(wls.fit2b)
#' 
#' 
#' #### Analysis of covariance structure using lavaan specification
#' R3.labels=c("a1", "a2", "a3", "a4")
#' 
#' R3 <- matrix(c(1.50, 0.22, 0.24, 0.18,
#'                0.22, 1.60, 0.30, 0.22,
#'                0.24, 0.30, 1.80, 0.24,
#'                0.18, 0.22, 0.24, 1.30), ncol=4, nrow=4,
#'                dimnames=list(R3.labels, R3.labels))
#' n <- 1000
#' acovS3 <- asyCov(R3, n, cor.analysis=FALSE)
#' 
#' model3 <- "f =~ a1 + a2 + a3 + a4"
#' 
#' RAM3 <- lavaan2RAM(model3, obs.variables=R3.labels)
#' 
#' wls.fit3a <- wls(Cov=R3, aCov=acovS3, n=n, RAM=RAM3,
#'                  cor.analysis=FALSE)
#' summary(wls.fit3a)
#' 
#' #### Analysis of covariance structure using RAM specification
#' (A3 <- cbind(matrix(0, nrow=5, ncol=4),
#'              matrix(c("0.2*a1","0.2*a2","0.2*a3","0.2*a4",0),ncol=1)))
#' 
#' (S3 <- Diag(c("0.2*e1","0.2*e2","0.2*e3","0.2*e4",1)))
#' 
#' F3 <- c(TRUE,TRUE,TRUE,TRUE,FALSE)
#' (F3 <- create.Fmatrix(F3, name="F3", as.mxMatrix=FALSE))
#' 
#' wls.fit3b <- wls(Cov=R3, aCov=acovS3, n=n, Amatrix=A3, Smatrix=S3,
#'                 Fmatrix=F3, cor.analysis=FALSE)
#' summary(wls.fit3b)
#' }
#' 
.align.wls.acov <- function(Cov, aCov, cor.analysis) {
  vars <- rownames(Cov)
  rows <- rownames(aCov); cols <- colnames(aCov)
  if (is.null(vars) || (is.null(rows) && is.null(cols))) return(aCov)
  if (is.null(rows) || is.null(cols) || anyDuplicated(rows) || anyDuplicated(cols))
    stop("Named 'aCov' must have unique row and column names on both axes.", call.=FALSE)
  expected <- .genCorNames(vars, cor.analysis=cor.analysis)$ylabels
  if (setequal(rows, expected) && setequal(cols, expected))
    return(aCov[expected, expected, drop=FALSE])
  pairs <- which(lower.tri(Cov, diag=!cor.analysis), arr.ind=TRUE)
  reversed <- paste0(vars[pairs[,2L]], "_", vars[pairs[,1L]])
  aliases <- split(rep(seq_along(expected), 2L), c(expected, reversed))
  aliases <- lapply(aliases, unique)
  index <- function(labels) {
    hits <- lapply(labels, function(label) aliases[[label]])
    if (any(lengths(hits) > 1L))
      stop("Ambiguous 'aCov' pair labels; rename the variables or use the exact generated labels.", call.=FALSE)
    vapply(hits, function(z) if (length(z)) z else NA_integer_, integer(1))
  }
  ri <- index(rows); ci <- index(cols)
  if (!anyNA(ri) && !anyNA(ci) && !anyDuplicated(ri) && !anyDuplicated(ci) &&
      setequal(ri, seq_along(expected)) && setequal(ci, seq_along(expected))) {
    out <- aCov[match(seq_along(expected), ri), match(seq_along(expected), ci), drop=FALSE]
    dimnames(out) <- list(expected, expected)
    return(out)
  }
  if (any(!is.na(ri)) || any(!is.na(ci)))
    stop("The names of 'aCov' partially match the elements of Cov; check their order and spelling.", call.=FALSE)
  warning("The names of 'aCov' do not identify the elements of Cov; matching by position.", call.=FALSE)
  aCov
}

.align.wls.filter <- function(Fmatrix, Cov) {
  vals <- Fmatrix$values
  if (nrow(vals) != nrow(Cov))
    stop("Fmatrix has ", nrow(vals), " observed variables, but Cov has ", nrow(Cov), ".", call.=FALSE)
  obs <- rownames(vals); vars <- rownames(Cov)
  if (is.null(obs) || is.null(vars)) return(Fmatrix)
  if (anyDuplicated(obs) || anyDuplicated(vars))
    stop("Observed variable names in Fmatrix and Cov must be unique.", call.=FALSE)
  if (setequal(obs, vars)) return(Fmatrix[match(vars, obs), , drop=FALSE])
  warning("Observed variable names in Fmatrix and Cov do not match; matching by position. Check the variable order and possible typos; estimates may be affected.", call.=FALSE)
  Fmatrix
}

wls <- function(Cov, aCov, n, RAM=NULL, Amatrix=NULL, Smatrix=NULL, Fmatrix=NULL, 
                diag.constraints=FALSE, cor.analysis=TRUE, intervals.type=c("z", "LB"), 
                mx.algebras=NULL, mxModel.Args=NULL, subset.variables=NULL,
                model.name=NULL, suppressWarnings=TRUE, 
                silent=TRUE, run=TRUE, ...) {

    .check.cov.names(Cov)
    .check.ram.names(RAM)
    for (mat in list(Amatrix, Smatrix, Fmatrix)) .check.model.matrix(mat)
    .check.no.period(subset.variables, "subset.variables")
    if (inherits(RAM, c("RAM_multigroup", "RAM_twolevel", "RAM_multigroup_twolevel")))
        stop("wls() supports single-group, single-level RAM models only.", call.=FALSE)
    aCov <- .align.wls.acov(Cov, aCov, cor.analysis)

    ## Filter out variables not used in the analysis
    if (!is.null(subset.variables)) {
        obslabels <- rownames(Cov)
        index  <- !(subset.variables %in% obslabels)
        if (any(index)) {
            stop(paste0(paste0(subset.variables[index], collapse = ", "), " are not in the \"Cov\".\n"))
        }
        if (anyDuplicated(subset.variables))
            stop("'subset.variables' must not contain duplicates.")
        p.full <- length(obslabels)
        pair.index <- matrix(NA_integer_, p.full, p.full)
        lower <- lower.tri(pair.index, diag=!cor.analysis)
        pair.index[lower] <- seq_len(sum(lower))
        pair.index[upper.tri(pair.index)] <- t(pair.index)[upper.tri(pair.index)]
        selected <- match(subset.variables, obslabels)
        pair.index <- pair.index[selected, selected, drop=FALSE]
        subset.acov <- if (cor.analysis) vechs(pair.index) else vech(pair.index)

        ## Filter the variables
        Cov <- Cov[subset.variables, subset.variables, drop=FALSE]
        aCov <- aCov[subset.acov, subset.acov, drop=FALSE]
    }
    
    if (cor.analysis && nrow(Cov) < 2L)
        stop("Correlation WLS requires at least two observed variables.", call.=FALSE)
    ## Read RAM first. If it is not specified, read individual matrices
    if (!is.null(RAM)) {
        if (nrow(RAM$F) != nrow(Cov))
            stop("RAM has ", nrow(RAM$F), " observed variables, but Cov has ",
                 nrow(Cov), ". Check 'subset.variables' and the RAM.", call.=FALSE)
        obs <- rownames(RAM$F)
        data.names <- rownames(Cov)
        if (!is.null(obs) && !is.null(data.names)) {
            if (length(obs) == length(data.names) && !anyDuplicated(obs) &&
                !anyDuplicated(data.names) && setequal(obs, data.names)) {
                RAM$F <- RAM$F[data.names, , drop=FALSE]
            } else {
                warning("Observed variable names in RAM and Cov do not match; ",
                        "matching by position. Check the variable order and possible typos; ",
                        "estimates may be affected.", call.=FALSE)
            }
        }
        Amatrix <- as.mxMatrix(RAM$A, name="Amatrix")
        Smatrix <- as.mxMatrix(RAM$S, name="Smatrix")
        Fmatrix <- as.mxMatrix(RAM$F, name="Fmatrix")
        ## Bounds from inequalities in the lavaan syntax (see lavaan2RAM())
        Amatrix <- .addbound(Amatrix, attr(RAM, "lbound"), attr(RAM, "ubound"))
        Smatrix <- .addbound(Smatrix, attr(RAM, "lbound"), attr(RAM, "ubound"))
    } else {
        if (is.null(Smatrix)) {
            stop("\"Smatrix\" matrix is not specified.\n")
        } else if (is.matrix(Smatrix)) {
            Smatrix <- as.mxMatrix(Smatrix, name="Smatrix")
        } else {
            ## Change the name of the input mxMatrix
            Smatrix@name <- "Smatrix"
        }
        
        ## No. of observed and latent variables
        p <- nrow(Smatrix@values)  

        if (is.null(Amatrix)) {
            ## If Amatrix is not specified, use a zero matrix.
            Amatrix <- as.mxMatrix(matrix(0, nrow=p, ncol=p), name="Amatrix")
        } else if (is.matrix(Amatrix)) {
            Amatrix <- as.mxMatrix(Amatrix, name="Amatrix")
        } else {
            ## Change the name of the input mxMatrix
            Amatrix@name <- "Amatrix"
        }

        if (is.null(Fmatrix)) {
            ## If Fmatrix is not specified, use an identity matrix.
            f <- Diag(rep(p,1))
            if (!is.null(rownames(Smatrix$values)))
              dimnames(f) <- list(rownames(Smatrix$values), rownames(Smatrix$values))
            Fmatrix <- as.mxMatrix(f, name="Fmatrix")
        } else if (is.matrix(Fmatrix)) {
            Fmatrix <- as.mxMatrix(Fmatrix, name="Fmatrix")
        } else {
            ## Change the name of the input mxMatrix
            Fmatrix@name <- "Fmatrix"
        }    
        Fmatrix <- .align.wls.filter(Fmatrix, Cov)
        if (!identical(dim(Amatrix$values), c(p,p)) ||
            !identical(dim(Smatrix$values), c(p,p)) || ncol(Fmatrix$values) != p)
            stop("Amatrix and Smatrix must be square with matching dimensions, and Fmatrix must have the same number of columns.", call.=FALSE)
        node.names <- c(dimnames(Amatrix$values), dimnames(Smatrix$values),
                        list(colnames(Fmatrix$values)))
        node.names <- Filter(Negate(is.null), node.names)
        if (length(node.names) > 1L &&
            any(!vapply(node.names[-1L], identical, logical(1), node.names[[1L]])))
            stop("Named Amatrix, Smatrix and Fmatrix node dimensions must have the same names in the same order.", call.=FALSE)
    }      
    
  ## CheckRAM
  checkRAM(Amatrix=Amatrix, Smatrix=Smatrix, cor.analysis=cor.analysis)

  ## No. of observed and latent variables
  p <- nrow(Smatrix@values)      
  ## A pxp identity matrix
  Id <- as.mxMatrix(Diag(rep(p, 1)), name="Id")

  ## No. of observed variables
  no.var <- ncol(Cov)
  if (is.pd(Cov)) {
    sampleS <- as.mxMatrix(Cov, name="sampleS")
  } else {
    stop("\"Cov\" is not positive definite.\n")
  }

  intervals.type <- match.arg(intervals.type)
  # Default is z
  switch(intervals.type,
         z = intervals <- FALSE,
         LB = intervals <- TRUE)

  # Inverse of asymptotic covariance matrix
  if (is.pd(aCov)) {
    invaCov <- tryCatch(chol2inv(chol(aCov)), error = function(e) e)
    ## It appears that solve() does not fail
    if (inherits(invaCov, "error")) {
      cat("Error in inverting \"aCov\":\n")
      stop(print(invaCov))
    }
    invAcov <- as.mxMatrix(invaCov, name="invAcov")
  } else {
    stop("\"aCov\" is not positive definite.\n")
  }

  if (cor.analysis) {
    if (is.null(model.name)) model.name <- "WLS Correlation"
    ps <- no.var * (no.var - 1)/2
  } else {
    if (is.null(model.name)) model.name <- "WLS Covariance"
    ps <- no.var * (no.var + 1)/2
  }
  
  if (ncol(aCov) != ps)
    stop("No. of dimension of \"Cov\" does not match the multiplier of the dimension of \"aCov\"\n")
  
  ## Assuming no constraint
  Constraints <- 0
  
  if (cor.analysis) {
    
    ## Count no. of dependent variables including both observed and latent variables
    ## Since it is correlation structure, Smatrix@values=1 and Smatrix@free=FALSE on the diagonals.
    Constraints <- Diag(Smatrix@free)
    ## Use nonlinear constraints to impose diagonals as 1
    if (diag.constraints & (sum(Constraints)>0)) {
      dv <- rowSums(Amatrix$free | (!is.na(Amatrix$values) & Amatrix$values != 0)) > 0
      if (any(dv & !Constraints))
        warning("wls() does not impose an explicit unit-variance constraint for dependent variables with fixed residual variances; verify their model-implied variances.", call.=FALSE)
      
      One <- mxMatrix("Full", values=1, ncol=1, nrow=sum(Constraints), free=FALSE, name="One")
      select <- create.Fmatrix(Constraints, name="select")
      constraint <- mxConstraint( select%*%diag2vec(solve(Id-Amatrix)%&%Smatrix)==One, 
                                  name="constraint" )
      impliedS <- mxAlgebra( (Fmatrix%*%solve(Id-Amatrix))%&%Smatrix, name="impliedS" )
      
      vecS <- mxAlgebra(vechs(sampleS - impliedS), name="vecS")
      obj <- mxAlgebra( t(vecS) %&% invAcov, name = "obj" )
      objective <- mxFitFunctionAlgebra(algebra="obj")
      
      mx.model <- mxModel(model=model.name, Fmatrix, Amatrix, Smatrix, Id, impliedS,
                          vecS, invAcov, obj, objective, sampleS, One, select, 
                          constraint, mxCI(c("Amatrix", "Smatrix")))
    } else {
    ## Consider error variances as functions of parameters  
      ## check types of variables
      ## dv: variables pointed by some variables
      dv <- rowSums(Amatrix$free | (!is.na(Amatrix$values) & Amatrix$values != 0)) > 0
      if (any(dv & !diag(Smatrix$free)))
        warning("For correlation analysis without explicit diagonal constraints, wls() computes dependent-variable residual variances; their fixed values in Smatrix are ignored.", call.=FALSE)
#       ## iv: variables pointed towards other variables
#       iv <- apply(Amatrix$free, 2, any)
#       ## med: mediators
#       med <- iv & dv
      
      ## S1: Smatrix without error variances on the dependent variables
      ## Fix the diagonal elements associated with dv to 0
      S1 <- Smatrix
      S1$name <- "S1"
      diag(S1$labels)[dv] <- NA
      diag(S1$values)[dv] <- 0
      diag(S1$free)[dv] <- FALSE

      ## Use it rather than Smatrix in mxCI()
      S1_labels <- S1$labels
      S1_labels[!S1$free] <- NA
      diag(S1_labels) <- NA
      S1_labels <- c(na.omit(unique(c(S1_labels))))

      ## Levels of dependent variables in an acyclic path model.
      path.levels <- .pathLevels(Amatrix)
      Level <- c(path.levels$IV, path.levels$DV)

      ## no error variance involved for ALL variables
      impliedS1 <- mxAlgebra( solve(Id-Amatrix)%&%S1, name="impliedS1")
      
      ## setup for error variances for mediators and dvs
      ## Excluded level1 as they are ivs (started with i=2)
      levels <- if (length(Level) > 1L) seq.int(2L, length(Level)) else integer(0)
      extra <- list()
      for (i in levels) {
        ## filter the diagonals of mediators
        extra[[length(extra)+1L]] <- as.mxMatrix(diag(Level[[i]]), name=paste0("sel", i))
        ## extract the error variances of mediators based on the previous model implied covariance matrix (i-1)
        extra[[length(extra)+1L]] <- mxAlgebraFromString(paste0("vec2diag(diag2vec(Id-impliedS", i-1,
                                                     "))*sel", i), name=paste0("E", i))
        ## Implied covariance matrix with estimated error variances on mediators for (i)
        extra[[length(extra)+1L]] <- mxAlgebraFromString(paste0("solve(Id-Amatrix)%&%(S1+",
                                                     paste0("E", seq.int(2L, i), collapse="+"), ")"),
                                              name=paste0("impliedS", i))
      }

      ## Final Smatrix including all error variances
      ## Smatrix=S1+E2+E3...
      Smatrix <- mxAlgebraFromString(paste0("S1", if (length(levels)) paste0("+E", levels, collapse="")),
                                     name="Smatrix")
      
      impliedS <- mxAlgebra((Fmatrix%*%solve(Id-Amatrix))%&%Smatrix, name="impliedS")
      
      vecS <- mxAlgebra(vechs(sampleS - impliedS), name="vecS")
      obj <- mxAlgebra( t(vecS) %&% invAcov, name = "obj" )
      objective <- mxFitFunctionAlgebra(algebra="obj")
      
      mx.model <- mxModel(model=model.name, Fmatrix, Amatrix, Smatrix, Id, impliedS1, 
                          impliedS, vecS, invAcov, obj, objective, sampleS, 
                          S1, mxCI(c("Amatrix", S1_labels)))
      
      ## Add the matrices into mx.model
      if (length(extra)) mx.model <- do.call(mxModel, c(list(mx.model), extra))
    }  ## if (diag.constraints & (sum(Constraints)>0))
  } else {
    ## analysis of covariance rather than correlation matrix
    impliedS <- mxAlgebra( (Fmatrix%*%solve(Id-Amatrix))%&%Smatrix, name="impliedS" )
    vecS <- mxAlgebra(vech(sampleS - impliedS), name="vecS")
    
    obj <- mxAlgebra( t(vecS) %&% invAcov, name = "obj" )
    objective <- mxFitFunctionAlgebra(algebra="obj")
    
    mx.model <- mxModel(model=model.name, Fmatrix, Amatrix, Smatrix, Id, impliedS,
                        vecS, invAcov, obj, objective, sampleS, mxCI(c("Amatrix", "Smatrix")))  
  }

  ## Add additiona mxalgebras from RAM
  ## Initialize as NULL  
  algebra.names <- NULL  
  if (!is.null(RAM$mxalgebras)) {
    for (i in seq_along(RAM$mxalgebras)) {
      mx.model <- mxModel(mx.model, RAM$mxalgebras[[i]])
    }
    ## check if they are mxalgebra, not mxconstraint
    algebra.names <- names(RAM$mxalgebras)
    isalgebra <- !vapply(RAM$mxalgebras, inherits, logical(1),
                         what="MxConstraint")
    if (any(isalgebra)) {
        ## Remove names for mxconstraints
        algebra.names <- algebra.names[isalgebra]
        mx.model <- mxModel(mx.model, mxCI(algebra.names))
    }
  }  
    
  ## Add additional mxAlgebras
  if (!is.null(mx.algebras)) {
    for (i in seq_along(mx.algebras)) {
      mx.model <- mxModel(mx.model, mx.algebras[[i]])
    }
    mx.model <- mxModel(mx.model, mxCI(names(mx.algebras)))
  }
    
  ## Add additional arguments to mxModel
  if (!is.null(mxModel.Args)) {
      for (i in seq_along(mxModel.Args)) {
          mx.model <- mxModel(mx.model, mxModel.Args[[i]])
      }
  }
    
  ## Return mx model without running the analysis
  mx.model <- .tighten.feasibility(mx.model)
  if (run==FALSE) return(mx.model)

  mx.fit <- tryCatch( mxRun(mx.model, intervals=intervals, suppressWarnings=suppressWarnings, silent=silent, ...), 
                      error = function(e) e)
  mx.fit <- .check.constraints(mx.fit, intervals=intervals)

  # try to run it with error message as output
  if (inherits(mx.fit, "error")) {
      cat("Error in running the mxModel:\n")
      warning(print(mx.fit))
      out <- mx.fit
  } else {
      out <- list(call=match.call(), Cov=Cov, aCov=aCov, noObservedStat=ps, n=n, cor.analysis=cor.analysis, 
                  diag.constraints=diag.constraints, Constraints=Constraints,
                  indepModelChisq=.indepwlsChisq(S=Cov, aCov=aCov, cor.analysis=cor.analysis),
                  indepModelDf=no.var*(no.var-1)/2, mx.model=mx.model, mx.fit=mx.fit,
                  mx.algebras=c(names(mx.algebras), algebra.names), 
                  intervals.type=intervals.type)
      class(out) <- 'wls'
  }
  out
}


#' @rdname wls
tssem2 <- function(tssem1.obj, RAM=NULL, Amatrix=NULL, Smatrix=NULL, Fmatrix=NULL, diag.constraints=FALSE,
                   intervals.type = c("z", "LB"), mx.algebras=NULL, mxModel.Args=NULL, subset.variables=NULL,
                   model.name=NULL, suppressWarnings=TRUE, silent=TRUE, run=TRUE, ...) {
  .check.ram.names(RAM)
  for (mat in list(Amatrix, Smatrix, Fmatrix)) .check.model.matrix(mat)
  .check.no.period(subset.variables, "subset.variables")
  if (!inherits(tssem1.obj, c("tssem1FEM.cluster", "tssem1FEM", "tssem1REM")))
      stop("\"tssem1.obj\" must be of neither class \"tssem1FEM.cluster\", class \"tssem1FEM\" or \"tssem1REM\".")
  .check.no.period(tssem1.obj$original.names, "Observed variable names")

  type <- if (inherits(tssem1.obj, "tssem1FEM.cluster")) "tssem1FEM.cluster"
          else if (inherits(tssem1.obj, "tssem1FEM")) "tssem1FEM" else "tssem1REM"
  switch(type,
         tssem1FEM.cluster = { out <- lapply(tssem1.obj, tssem2, RAM=RAM, Amatrix=Amatrix, Smatrix=Smatrix, Fmatrix=Fmatrix,
                                             diag.constraints=diag.constraints, intervals.type=intervals.type,
                                             mx.algebras=mx.algebras, mxModel.Args=mxModel.Args,
                                             subset.variables=subset.variables,
                                             model.name=model.name, suppressWarnings=suppressWarnings, silent=silent,
                                             run=run, ...)
                              class(out) <- "wls.cluster" },
         tssem1FEM = { if (tssem1.obj$cor.analysis==TRUE) {
                        if (is.null(model.name)) model.name <- "TSSEM2 Correlation"
                      } else {
                        if (is.null(model.name)) model.name <- "TSSEM2 Covariance"
                      # to handle symbolic F(T) vs. logical FALSE(TRUE)
                      ## cor.analysis <- as.logical(as.character(cor.analysis))
                      }
                      ## Use the original varible names for the observed covariance matrix
                      pooledS <- coef.tssem1FEM(tssem1.obj)                      
                      ## dimnames(pooledS) <- list(tssem1.obj$original.names, tssem1.obj$original.names)
                      out <- wls(Cov=coef.tssem1FEM(tssem1.obj), aCov=vcov.tssem1FEM(tssem1.obj),
                                 n=sum(tssem1.obj$n), RAM=RAM, Amatrix=Amatrix, Smatrix=Smatrix, Fmatrix=Fmatrix,
                                 diag.constraints=diag.constraints, cor.analysis=tssem1.obj$cor.analysis,
                                 intervals.type=intervals.type, mx.algebras=mx.algebras, mxModel.Args=mxModel.Args,
                                 subset.variables=subset.variables,
                                 model.name=model.name, suppressWarnings=suppressWarnings,
                                 silent=silent, run=run, ...) },
         tssem1REM = { cor.analysis <- tssem1.obj$cor.analysis
                      ## Extract the pooled correlation matrix
                      pooledS <- vec2symMat( coef(tssem1.obj, select="fixed"), diag=!cor.analysis)
                      dimnames(pooledS) <- list(tssem1.obj$original.names, tssem1.obj$original.names) 
                      ## Extract the asymptotic covariance matrix of the pooled correlations                      
                      aCov <- vcov(tssem1.obj, select="fixed")
                      aCov.names <- .genCorNames(x=tssem1.obj$original.names, cor.analysis=cor.analysis)
                      dimnames(aCov) <- list(aCov.names$ylabels, aCov.names$ylabels)
      
                      if (cor.analysis==TRUE) {
                        if (is.null(model.name)) model.name <- "TSSEM2 Correlation"
                      } else {
                        if (is.null(model.name)) model.name <- "TSSEM2 Covariance"
                      }
                      ## Use the original varible names for the observed covariance matrix
                      dimnames(pooledS) <- list(tssem1.obj$original.names, tssem1.obj$original.names)
                      out <- wls(Cov=pooledS, aCov=aCov, n=tssem1.obj$total.n, RAM=RAM,
                                 Amatrix=Amatrix, Smatrix=Smatrix, Fmatrix=Fmatrix, diag.constraints=diag.constraints,
                                 cor.analysis=cor.analysis, intervals.type=intervals.type, mx.algebras=mx.algebras,
                                 subset.variables=subset.variables,
                                 mxModel.Args=mxModel.Args, model.name=model.name, suppressWarnings = suppressWarnings,
                                 silent=silent, run=run, ...) })
  out
}




#' Estimate the heterogeneity (SD) of the parameter estimates of the TSSEM
#' object
#' 
#' It estimates the heterogeneity of the parameter estimates of the TSSEM
#' objects using either the bootstrap or the delta methods.
#' 
#' The bootstrap method is based on the discussion in Cheung (2018) and Yu et
#' al. (2016). The delta method is an alternative method to obtain the
#' heterogeneity.
#' 
#' @param tssem1.obj An object of class \code{tssem1REM} returned from
#' \code{tssem1()}
#' @param tssem2.obj An object of class \code{wls} returned from
#' \code{tssem2()} or \code{wls()}
#' @param method If it is \code{bootstrap}, random correlation matrices are
#' sampled from the \code{tssem1.obj} by the parametric bootstrap. If it is
#' \code{delta}, the delta method is used to estimate the heterogeneity of the
#' parameter estimates.
#' @param interval The desired interval, e.g., .8 or .95.
#' @param Rep The number of parametric bootstrap. It is ignored when the method
#' is \code{delta}.
#' @param output Either a \code{data.frame} or \code{matrices} of the output.
#' @param nonPD.pop If it is \code{replace}, generated non-positive definite
#' matrices are replaced by generated new ones which are positive definite. If
#' it is \code{nearPD}, they are replaced by nearly positive definite matrices
#' by calling \code{Matrix::nearPD()}. If it is \code{accept}, they are
#' accepted.
#' @return Either a \code{data.frame} or \code{matrices} of the output.
#' @author Mike W.-L. Cheung <mikewlcheung@@nus.edu.sg>
#' @seealso \code{\link[metaSEM]{bootuniR1}}, \code{\link[metaSEM]{bootuniR2}},
#' \code{\link[metaSEM]{Nohe15}}
#' @references Cheung, M. W.-L. (2018). Issues in solving the problem of effect
#' size heterogeneity in meta-analytic structural equation modeling: A
#' commentary and simulation study on Yu, Downes, Carter, and O'Boyle (2016).
#' \emph{Journal of Applied Psychology}, \bold{103}, 787-803.
#' 
#' Yu, J. (Joya), Downes, P. E., Carter, K. M., & O'Boyle, E. H. (2016). The
#' problem of effect size heterogeneity in meta-analytic structural equation
#' modeling.  \emph{Journal of Applied Psychology}, \emph{101}, 1457-1473.
#' @keywords tssem
tssemParaVar <- function(tssem1.obj, tssem2.obj, method=c("bootstrap", "delta"),
                         interval=0.8, Rep=50, output=c("data.frame", "matrices"),
                         nonPD.pop=c("replace", "nearPD", "accept")) {

    if (interval <=0 | interval >=1) stop("'interval' must be within 0 and 1.\n")
    
    ## Means of stage 1
    Means <- mxEvalByName("Inter", tssem1.obj$mx.fit)
    ## Variance componet of the correlation coefficients
    V <- mxEvalByName("Tau", tssem1.obj$mx.fit)

    mx.model <- tssem2.obj$mx.fit
    ## Maximize the speed
    mx.model <- mxOption(mx.model, "Calculate Hessian", "No")
    mx.model <- mxOption(mx.model, "Standard Errors", "No")
  
    method <- match.arg(method)
    output <- match.arg(output)

    ## delta method
    if (method=="delta") {

        if (!requireNamespace("numDeriv", quietly = TRUE))
            stop("\"numDeriv\" package is required for this function.")

        ## Gradiant function
        ## x: Correlation coefficients
        fun1 <- function(x) {
            sampleS <- as.mxMatrix(vec2symMat(x, diag=FALSE), name="sampleS")
            model <- mxModel(mx.model, sampleS=sampleS)
            fit <- mxRun(model, silent=TRUE)
            coef(fit)
        }
        
        ## Jacobian matrix
        grad <- numDeriv::jacobian(fun1, x=Means)
        Tau2 <- grad %*% V %*% t(grad)
    } else {
        ## bootstrap method
        boot.cor <- rCorPop(Sigma=vec2symMat(Means, diag=FALSE),
                            V=V, k=Rep, nonPD.pop=nonPD.pop)

        boot.coef <- t(sapply(boot.cor, function(x) {
                               sampleS <- as.mxMatrix(x, name="sampleS")
                               model <- mxModel(mx.model, sampleS=sampleS)
                               fit <- mxRun(model, silent=TRUE)
                               coef(fit)
        }))
        Tau2 <- cov(boot.coef, use="complete.obs") 
    }

    ## Parameters for checking
    para <- coef(mxRun(mx.model, silent=TRUE))
    if (is.null(dimnames(Tau2))) {
        dimnames(Tau2) <- list(names(para), names(para))
    }
    SD <- sqrt(diag(Tau2))

    if (output=="data.frame") {
        z <- qnorm((1-interval)/2, lower.tail=FALSE)
        out <- data.frame(Parameter=para, SD=SD, lbound=para-z*SD, ubound=para+z*SD)
        lbound <- paste0(interval*100, "% lbound")
        ubound <- paste0(interval*100, "% ubound")
        colnames(out) <- c("Parameter", "SD", "lbound", "ubound")
    } else {
        out <- list(para=para, SD=SD, Tau2=Tau2)
    }
    out
}



## deltaCV <- function(tssem1.obj, tssem2.obj) {
    
##     if (!requireNamespace("numDeriv", quietly = TRUE)) 
##         stop("\"numDeriv\" package is required for this function.")

##     ## Means
##     Means <- mxEval(Inter, tssem1.obj$mx.fit)
##     ## Variance componet of the correlation coefficients
##     V <- mxEval(Tau, tssem1.obj$mx.fit)

##     mx.model <- tssem2.obj$mx.fit
##     ## Maximize the speed
##     mx.model <- mxOption(mx.model, "Calculate Hessian", "No")
##     mx.model <- mxOption(mx.model, "Standard Errors", "No")
    
##     ## Gradiant function
##     ## x: Correlation coefficients
##     fun <- function(x) {
##         sampleS <- as.mxMatrix(vec2symMat(x, diag=FALSE), name="sampleS")
##         model <- mxModel(mx.model, sampleS=sampleS)
##         fit <- mxRun(model, silent=TRUE)
##         coef(fit)
##     }

##     grad <- numDeriv::jacobian(fun, x=Means)
##     Tau2 <- grad %*% V %*% t(grad)

##     para <- coef(mxRun(mx.model, silent=TRUE))
##     dimnames(Tau2) <- list(names(para), names(para))
    
##     SD <- sqrt(diag(Tau2))
    
##     list(para=para, SD=SD, Tau2=Tau2)
## }



## delta2 <- function(tssem1.obj, Amatrix = NULL, Smatrix = NULL, Fmatrix = NULL, 
##                    diag.constraints = FALSE) {
    
##     if (!requireNamespace("numDeriv", quietly = TRUE)) 
##         stop("\"numDeriv\" package is required for this function.")

##     ## Means
##     Means <- mxEval(Inter, tssem1.obj$mx.fit)
##     ## Variance componet of the correlation coefficients
##     V <- mxEval(Tau, tssem1.obj$mx.fit)

##     ## Setup the model without running it
##     mx.model <- tssem2(tssem1.obj=tssem1.obj, Amatrix=Amatrix, Smatrix=Smatrix,
##                        Fmatrix=Fmatrix, diag.constraints=diag.constraints,
##                        run=FALSE)

##     ## Maximize the speed
##     mx.model <- mxOption(mx.model, "Calculate Hessian", "No")
##     mx.model <- mxOption(mx.model, "Standard Errors"  , "No")
    
##     ## Gradiant function
##     ## x: Correlation coefficients
##     fun <- function(x) {
##         sampleS <- as.mxMatrix(vec2symMat(x, diag=FALSE), name="sampleS")
##         model <- mxModel(mx.model, sampleS=sampleS)
##         fit <- mxRun(model, silent=TRUE)
##         coef(fit)
##     }

##     grad <- numDeriv::jacobian(fun, x=Means)
##     Tau2 <- grad %*% V %*% t(grad)

##     para <- coef(mxRun(mx.model, silent=TRUE))
##     dimnames(Tau2) <- list(names(para), names(para))

##     list(para=para, Tau2=Tau2)
## }

Try the metaSEM package in your browser

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

metaSEM documentation built on Nov. 16, 2026, 5:07 p.m.