R/MultiDimScaling.R

In sethmargolis/PairMeasInv: Applies The Pairwise Method of Examining Measurement Invariance

#' Perform non-metric multidimensional scaling on invariance matrices
#'
#' \code{MultiDimScaling} performs non-metric multidimensional scaling on each
#' invariance matrix in a list.
#' 
#' This function uses \code{\link[MASS]{isoMDS}} to perform Kruskal's non-metric 
#' multidimensional scaling with 2 dimensions on invariance matrices.
#'
#' @param matrix.list A list of invariance matrices from 
#' \code{\link{InvarianceMatrices}}
#' @param ... optional arguments that are passed to \code{\link[MASS]{isoMDS}}
#' @return This function returns a list of objects returned from 
#' \code{\link[MASS]{isoMDS}}. Importantly, these objects contain the 
#' coordinates of groups in 2-dimensional space. 
#'
#' @export
MultiDimScaling <- function(matrix.list, ...) {
  # creating list to fill in and output
  out.list <- list()
  # for each invariance matrix, rum multidimensional scaling
  for(matrix.number in 1:length(matrix.list)){
    # subset matrix.list to a matrix
    temp.matrix <- matrix.list[[matrix.number]]
    # create a distance matrix
    temp.distances <- stats::dist(temp.matrix)
    temp.distances[1:length(temp.distances)] <- 
      temp.matrix[lower.tri(temp.matrix)] - min(temp.matrix, na.rm = T) + .001
    # run multidimensional scaling
    capture.output(temp.mds <- MASS::isoMDS(temp.distances, k = 2, ...))
    # fill in output list
    out.list[[matrix.number]] <- temp.mds
    # create names for output list
    names(out.list)[matrix.number] <- names(matrix.list)[matrix.number]
  }
  return(out.list)
}