11# ' Principal Component Analysis (PCA) and Factor Analysis (FA)
22# '
3- # ' The functions `principal_components()` and `factor_analysis()` can
4- # ' be used to perform a principal component analysis (PCA) or a factor analysis
5- # ' (FA). They return the loadings as a data frame, and various methods and
6- # ' functions are available to access / display other information (see the
7- # ' Details section).
3+ # ' The functions `principal_components()` and `factor_analysis()` can be used to
4+ # ' perform a principal component analysis (PCA) or a factor analysis (FA). They
5+ # ' return the loadings as a data frame, and various methods and functions are
6+ # ' available to access / display other information (see the 'Details' section).
87# '
9- # ' @param x A data frame or a statistical model.
8+ # ' @param x A data frame or a statistical model. For `closest_component()`, the
9+ # ' output of the `principal_components()` function.
1010# ' @param n Number of components to extract. If `n="all"`, then `n` is set as
1111# ' the number of variables minus 1 (`ncol(x)-1`). If `n="auto"` (default) or
1212# ' `n=NULL`, the number of components is selected through [`n_factors()`]
1919# ' @param rotation If not `"none"`, the PCA / FA will be computed using the
2020# ' **psych** package. Possible options include `"varimax"`, `"quartimax"`,
2121# ' `"promax"`, `"oblimin"`, `"simplimax"`, or `"cluster"` (and more). See
22- # ' [`psych::fa()`] for details.
22+ # ' [`psych::fa()`] for details. The default is `"none"` for PCA, and
23+ # ' `"oblimin"` for FA.
24+ # ' @param factor_method The factoring method to be used. Passed to the `fm`
25+ # ' argument in `psych::fa()`. Defaults to `"minres"` (minimum residual). Other
26+ # ' options include `"uls"`, `"ols"`, `"wls"`, `"gls"`, `"ml"`, `"minchi"`,
27+ # ' `"minrank"`, `"old.min"`, and `"alpha"`. See `?psych::fa` for details.
2328# ' @param sparse Whether to compute sparse PCA (SPCA, using [`sparsepca::spca()`]).
2429# ' SPCA attempts to find sparse loadings (with few nonzero values), which improves
2530# ' interpretability and avoids overfitting. Can be `TRUE` or `"robust"` (see
2631# ' [`sparsepca::robspca()`]).
2732# ' @param sort Sort the loadings.
33+ # ' @param n_obs An integer or a matrix.
34+ # ' - **Integer:** Number of observations in the original data set if `x` is a
35+ # ' correlation matrix. Required to compute correct fit indices.
36+ # ' - **Matrix:** A matrix where each cell `[i, j]` specifies the number of
37+ # ' pairwise complete observations used to compute the correlation between
38+ # ' variable `i` and variable `j` in the input `x`. It is crucial when `x` is
39+ # ' a correlation matrix (rather than raw data), especially if that matrix
40+ # ' was derived from a dataset containing missing values using pairwise
41+ # ' deletion. Providing a matrix allows `psych::fa()` to accurately calculate
42+ # ' statistical measures, such as chi-square fit statistics, by accounting
43+ # ' for the varying sample sizes that contribute to each individual
44+ # ' correlation coefficient.
2845# ' @param threshold A value between 0 and 1 indicates which (absolute) values
2946# ' from the loadings should be removed. An integer higher than 1 indicates the
3047# ' n strongest loadings to retain. Can also be `"max"`, in which case it will
4663# ' with missing values from the original data, hence the number of rows of
4764# ' predicted data and original data is equal.
4865# ' @param ... Arguments passed to or from other methods.
49- # ' @param pca_results The output of the `principal_components()` function.
5066# ' @param digits Argument for `print()`, indicates the number of digits
5167# ' (rounding) to be used.
5268# ' @param labels Argument for `print()`, character vector of same length as
8399# ' values, so it matches the original data frame.
84100# '
85101# ' - `performance::item_omega()` is a convenient wrapper around `psych::omega()`,
86- # ' which provides some additioal methods to work seamleassly within the
102+ # ' which provides some additional methods to work seamlessly within the
87103# ' *easystats* framework.
88104# '
89105# ' - [`performance::check_normality()`] checks residuals from objects returned
134150# '
135151# ' ## Computing Item Scores
136152# ' Use [`get_scores()`] to compute scores for the "subscales" represented by the
137- # ' extracted principal components. `get_scores()` takes the results from
138- # ' `principal_components()` and extracts the variables for each component found
139- # ' by the PCA. Then, for each of these "subscales", raw means are calculated
140- # ' (which equals adding up the single items and dividing by the number of items).
141- # ' This results in a sum score for each component from the PCA, which is on the
142- # ' same scale as the original, single items that were used to compute the PCA.
143- # ' One can also use `predict()` to back-predict scores for each component,
144- # ' to which one can provide `newdata` or a vector of `names` for the components.
153+ # ' extracted principal components or factors. `get_scores()` takes the results
154+ # ' from `principal_components()` or `factor_analysis()` and extracts the
155+ # ' variables for each component found by the PCA. Then, for each of these
156+ # ' "subscales", raw means are calculated (which equals adding up the single
157+ # ' items and dividing by the number of items). This results in a sum score for
158+ # ' each component from the PCA, which is on the same scale as the original,
159+ # ' single items that were used to compute the PCA. One can also use `predict()`
160+ # ' to back-predict scores for each component, to which one can provide `newdata`
161+ # ' or a vector of `names` for the components.
145162# '
146163# ' ## Explained Variance and Eingenvalues
147164# ' Use `summary()` to get the Eigenvalues and the explained variance for each
213230# '
214231# ' # Factor Analysis (FA) ------------------------
215232# '
216- # ' factor_analysis(mtcars[, 1:7], n = "all", threshold = 0.2)
217- # ' factor_analysis(mtcars[, 1:7], n = 2, rotation = "oblimin", threshold = "max", sort = TRUE)
218- # ' factor_analysis(mtcars[, 1:7], n = 2, threshold = 2, sort = TRUE)
233+ # ' factor_analysis(mtcars[, 1:7], n = "all", threshold = 0.2, rotation = "Promax" )
234+ # ' factor_analysis(mtcars[, 1:7], n = 2, threshold = "max", sort = TRUE)
235+ # ' factor_analysis(mtcars[, 1:7], n = 2, rotation = "none", threshold = 2, sort = TRUE)
219236# '
220237# ' efa <- factor_analysis(mtcars[, 1:5], n = 2)
221238# ' summary(efa)
@@ -234,9 +251,9 @@ principal_components <- function(x, ...) {
234251
235252# ' @rdname principal_components
236253# ' @export
237- rotated_data <- function (pca_results , verbose = TRUE ) {
238- original_data <- attributes(pca_results )$ dataset
239- rotated_matrix <- insight :: get_predicted(attributes(pca_results )$ model )
254+ rotated_data <- function (x , verbose = TRUE ) {
255+ original_data <- attributes(x )$ dataset
256+ rotated_matrix <- insight :: get_predicted(attributes(x )$ model )
240257 out <- NULL
241258
242259 if (is.null(original_data ) || is.null(rotated_matrix )) {
@@ -246,7 +263,7 @@ rotated_data <- function(pca_results, verbose = TRUE) {
246263 return (NULL )
247264 }
248265
249- compl_cases <- attributes(pca_results )$ complete_cases
266+ compl_cases <- attributes(x )$ complete_cases
250267 if (is.null(compl_cases ) && nrow(original_data ) != nrow(rotated_matrix )) {
251268 if (verbose ) {
252269 insight :: format_warning(" Could not retrieve information about missing data."
0 commit comments