add matrix method

Author: strengejacke

NEWS.md

@@ -16,6 +16,10 @@
 
 ## Changes
 
+* `factor_analysis()` gets a `.matrix` method, including arguments `n_obs` and
+  `n_matrix`, to compute factor analysis for a correlation matrix or covariance
+  matrix.
+
 * New function `factor_scores()` to extract factor scores from EFA (`psych::fa()`
   or `factor_analysis()`).
 

R/factor_analysis.R

@@ -42,8 +42,43 @@ factor_analysis.data.frame <- function(x,
 }
 
 
+#' @rdname principal_components
 #' @export
-factor_analysis.matrix <- factor_analysis.data.frame
+factor_analysis.matrix <- function(x,
+                                   n = "auto",
+                                   rotation = "oblimin",
+                                   n_obs = NULL,
+                                   n_matrix = NULL,
+                                   sort = FALSE,
+                                   threshold = NULL,
+                                   standardize = FALSE,
+                                   ...) {
+  # check if we have a square matrix. in this case, we assume that
+  # the user wants to do a factor analysis on the correlation matrix
+  if ((dim(x)[1] == dim(x)[2]) && is.null(n_obs)) {
+    insight::format_error(
+      "You provided a square matrix, which is assumed to be a correlation matrix. Please specify the number of observations with `n_obs`. If your matrix is not a correlation matrix, please provide a data frame instead."
+    )
+  }
+
+  # the default n.obs argument in `psych::fa()` is `NA`, so we change
+  # our default `NULL` to `NA` to avoid errors
+  if (is.null(n_obs)) {
+    n_obs <- NA
+  }
+
+  factor_analysis.data.frame(
+    as.data.frame(x),
+    n = n,
+    rotation = rotation,
+    sort = sort,
+    threshold = threshold,
+    standardize = standardize,
+    n.obs = n_obs,
+    np.obs = n_matrix,
+    ...
+  )
+}
 
 
 .is_oblique_rotation <- function(rotation) {

R/principal_components.R

@@ -1,10 +1,9 @@
 #' Principal Component Analysis (PCA) and Factor Analysis (FA)
 #'
-#' The functions `principal_components()` and `factor_analysis()` can
-#' be used to perform a principal component analysis (PCA) or a factor analysis
-#' (FA). They return the loadings as a data frame, and various methods and
-#' functions are available to access / display other information (see the
-#' Details section).
+#' The functions `principal_components()` and `factor_analysis()` can be used to
+#' perform a principal component analysis (PCA) or a factor analysis (FA). They
+#' return the loadings as a data frame, and various methods and functions are
+#' available to access / display other information (see the 'Details' section).
 #'
 #' @param x A data frame or a statistical model.
 #' @param n Number of components to extract. If `n="all"`, then `n` is set as
@@ -26,6 +25,19 @@
 #'   interpretability and avoids overfitting. Can be `TRUE` or `"robust"` (see
 #'   [`sparsepca::robspca()`]).
 #' @param sort Sort the loadings.
+#' @param n_obs Number of observations in the original data set if `x` is a
+#'   correlation matrix. Required to compute correct fit indices.
+#' @param n_matrix This argument expects a matrix where each cell `[i, j]`
+#'   specifies the number of pairwise complete observations used to compute the
+#'   correlation between variable `i` and variable `j` in the input `x`. It is
+#'   crucial when `x` is a correlation matrix (rather than raw data), especially
+#'   if that matrix was derived from a dataset containing missing values using
+#'   pairwise deletion. Providing `n_matrix` allows `psych::fa()` to accurately
+#'   calculate statistical measures, such as chi-square fit statistics, by
+#'   accounting for the varying sample sizes that contribute to each individual
+#'   correlation coefficient. This precision is vital for methods that rely on
+#'   these specific sample sizes for statistical inference, such as 'minimum
+#'   chi-square' (minchi) solutions.
 #' @param threshold A value between 0 and 1 indicates which (absolute) values
 #'   from the loadings should be removed. An integer higher than 1 indicates the
 #'   n strongest loadings to retain. Can also be `"max"`, in which case it will

man/principal_components.Rd

@@ -50,6 +50,36 @@ test_that("factor_analysis", {
   # check factor scores
   fc <- factor_scores(out)
   expect_identical(dim(fc), c(32L, 2L))
+
+  # works with correlation matrix
+  skip_if_not_installed("correlation")
+  skip_on_cran() # takes too long on CRAN
+
+  raq_poly <- correlation::correlation(raq_items, method = "polychoric")
+  raq_poly_mtx <- as.matrix(raq_poly) # store correlation matrix
+
+  # needs n_obs
+  expect_error(
+    factor_analysis(raq_poly_mtx, n = 4),
+    regex = "You provided a square matrix"
+  )
+
+  out1 <- factor_analysis(raq_poly_mtx, n = 4, n_obs = 2571)
+  expect_identical(dim(out1), c(23L, 7L))
+  expect_named(
+    out1,
+    c("Variable", "MR1", "MR2", "MR4", "MR3", "Complexity", "Uniqueness")
+  )
+
+  out2 <- factor_analysis(as.matrix(raq_items), n = 4)
+  expect_identical(dim(out2), c(23L, 7L))
+  expect_named(
+    out2,
+    c("Variable", "MR1", "MR2", "MR4", "MR3", "Complexity", "Uniqueness")
+  )
+
+  # roughly equal results
+  expect_equal(out1$MR1, out2$MR1, tolerance = 1e-1)
 })