% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/efa_bartlett.R
\name{efa_bartlett}
\alias{efa_bartlett}
\title{Bartlett's test of sphericity}
\source{
Bartlett, M. S. (1951). The effect of standardization on a Chi-square
approximation in factor analysis. Biometrika, 38, 337-344.
}
\usage{
efa_bartlett(
  x,
  N = NA,
  use = c("pairwise.complete.obs", "all.obs", "complete.obs", "everything",
    "na.or.complete"),
  cor_method = c("pearson", "spearman", "kendall", "poly", "tetra")
)
}
\arguments{
\item{x}{data.frame or matrix. Dataframe or matrix of raw data or matrix with
correlations.}

\item{N}{numeric. The number of observations. Needs only be specified if a
correlation matrix is used.}

\item{use}{character. The missing-data policy for raw data. Passed to
\code{\link[stats:cor]{stats::cor()}} for \code{"pearson"}, \code{"spearman"}, and \code{"kendall"}; for \code{"poly"} /
\code{"tetra"} the same policies are applied to the raw data before the polychoric
estimation, where \code{"all.obs"} and \code{"everything"} abort on a missing value instead
of returning \code{NA} correlations. Default is "pairwise.complete.obs".}

\item{cor_method}{character. Correlation computed from raw data: \code{"pearson"},
\code{"spearman"}, or \code{"kendall"} (passed to \code{\link[stats:cor]{stats::cor()}}), or \code{"poly"} /
\code{"tetra"} for polychoric / tetrachoric correlations of ordinal / binary data
(a two-step estimator).
Default is "pearson".}
}
\value{
A list containing
\item{chisq}{The chi square statistic, or \code{NA}, with a warning, if \code{N} is too
small for the Bartlett correction (i.e. \eqn{N - 1 - (2p + 5)/6 \le 0}).}
\item{p_value}{The p value of the chi square statistic, or \code{NA} when \code{chisq}
is \code{NA}.}
\item{df}{The degrees of freedom for the chi square statistic.}
\item{settings}{A list of the settings used.}
}
\description{
This function tests whether a correlation matrix is significantly different
from an identity matrix (Bartlett, 1951). If the Bartlett's test is not
significant, the correlation matrix is not suitable for factor analysis
because the variables show too little covariance.
}
\details{
Bartlett (1951) proposed this statistic to determine a correlation
matrix' suitability for factor analysis. The statistic is approximately
chi square distributed with \eqn{df = \frac{p(p - 1)}{2}} and is given by

\deqn{chi^2 = -log(det(R)) (N - 1 - (2 * p + 5)/6)}

where \eqn{det(R)} is the determinant of the correlation matrix, \eqn{N} is
the sample size, and \eqn{p} is the number of variables.

This test requires multivariate normality. If this condition is not met,
the Kaiser-Meyer-Olkin criterion (\code{\link[=efa_kmo]{efa_kmo()}})
can still be used.

This function was heavily influenced by the \code{\link[psych:cortest.bartlett]{psych::cortest.bartlett()}} function from the psych package.

The \code{efa_bartlett} function can also be called together with the
(\code{\link[=efa_kmo]{efa_kmo()}}) function and with factor retention criteria
in the \code{\link[=efa_retain]{efa_retain()}} function.
}
\examples{
efa_bartlett(test_models$baseline$cormat, N = 500)

}
\seealso{
\code{\link[=efa_kmo]{efa_kmo()}} for another measure to determine
suitability for factor analysis.

\code{\link[=efa_retain]{efa_retain()}} as a wrapper function for this function,
\code{\link[=efa_kmo]{efa_kmo()}} and several factor retention criteria.

Other factor analysis suitability:
\code{\link[=efa_kmo]{efa_kmo()}},
\code{\link[=efa_screen]{efa_screen()}},
\code{\link[=print.efa_screen]{print.efa_screen()}}
}
\concept{factor analysis suitability}
