\encoding{UTF-8}
\name{simple_structure}
\alias{calc_AUC}
\alias{calc_FSI}
\alias{calc_simplicity}
\alias{calc_hyperplane}
\alias{calc_fitstats}
\alias{simple_structure}
\title{Simple Structure Quality Measures}
\description{
  Functions for assessing the quality of simple structure in a rotated
  factor solution. Four criterion-free measures are available:
  \describe{
    \item{\code{calc_AUC}}{Area Under the Curve measure of factor loading
      simplicity, computed per factor and overall (Liu et al., 2023).}
    \item{\code{calc_FSI}}{Factor Simplicity Index, computed per factor
      and overall (Lorenzo-Seva, 2003).}
    \item{\code{calc_simplicity}}{Three overall solution measures:
      Hoffman (1978), Gini (Kaiser, 1974), and Bentler (1977).}
    \item{\code{calc_hyperplane}}{Hyperplane count per factor and overall,
      measuring coordinate sparsity in the rotated solution.}
    \item{\code{calc_fitstats}}{Chi-square, SMRS, RMSEA with confidence interval,
      valid for MLE extracted loadings only.}
  }

  All measures are criterion-free --- they do not depend on how the
  rotation was obtained --- making them useful for comparing simple
  structure quality across different rotation methods applied to the
  same unrotated solution. The table below summarizes the measures,
  their scope, range, and interpretation:

  \tabular{lllll}{
    \strong{Measure} \tab \strong{Scope} \tab \strong{Range} \tab
      \strong{Good} \tab \strong{Poor} \cr
    AUC        \tab per factor         \tab [0.5, 1.0]    \tab near 1.0      \tab near 0.5 \cr
    FSI        \tab per factor         \tab [0.0, 1.0]    \tab near 1.0      \tab near 0.0 \cr
    Hoffman    \tab overall solution   \tab [0.0, 1.0]    \tab near 1.0      \tab near 0.0 \cr
    Gini       \tab overall solution   \tab [0.0, 1.0]    \tab near 1.0      \tab near 0.0 \cr
    Bentler    \tab overall solution   \tab [0.0, 1.0]    \tab near 1.0      \tab near 0.0 \cr
    Hyperplane \tab per factor; overall \tab [0, p(k-1)] \tab high count    \tab low count \cr
  }

  \strong{Note:} No universally accepted cutoffs exist for these measures.
  The ranges above are approximate guidelines based on empirical experience.
  Always interpret in conjunction with substantive theory and model fit
  indices such as RMSEA and SRMR.

  \strong{Note on Bentler:} the Bentler index tends to be low when
  factor intercorrelations are high, even when simple structure is
  otherwise clean. A low Bentler value should therefore be interpreted
  in conjunction with AUC, FSI, and hyperplane counts rather than in
  isolation. High AUC and hyperplane counts alongside a low Bentler
  value typically indicate correlated factors rather than poor simple
  structure.

  These functions are used internally by \code{\link{print.GPArotation}}
  and \code{\link{summary.GPArotation}} and are displayed automatically
  when printing or summarising a \code{GPArotation} object. They can also
  be called directly using the triple-colon operator, for example
  \code{GPArotation:::calc_AUC(x)}.
}
\usage{
## Not exported -- access via GPArotation:::calc_AUC(x) etc.
## calc_AUC(x, digits = 3L)
## calc_FSI(x, digits = 3L)
## calc_simplicity(x, digits = 3L)
## calc_hyperplane(x, cutoff = 0.1, digits = 3L)
## calc_fitstats(x)
}
\arguments{
  \item{x}{a \code{GPArotation} object, a \code{factanal} object, or a
    factor loading matrix. For oblique rotations all measures are computed
    from the pattern matrix, not the structure matrix.}
  \item{digits}{integer. Number of decimal places for rounding. Default 3.}
  \item{cutoff}{numeric. Half-width of the hyperplane band for
    \code{calc_hyperplane}. Loadings with absolute value below
    \code{cutoff} are counted as hyperplane loadings. Default 0.1.
    Common choices are 0.1 (strict) and 0.15 (lenient). Results should
    always be reported with the cutoff value used.}
}
\details{
  All four measures are criterion-free --- they do not depend on how the
  rotation was obtained --- making them useful for comparing simple
  structure quality across different rotation methods applied to the same
  unrotated solution.

  \subsection{AUC (Liu et al., 2023)}{
    For each factor \eqn{j} the squared loadings are sorted in descending
    order and their cumulative proportions of total factor variance are
    plotted against their rank. AUC is the area under this curve:
    \deqn{AUC_j = \frac{1}{p} \sum_{i=1}^{p}
          \frac{\sum_{r=1}^{i} l_{(r)j}^2}{\sum_{r=1}^{p} l_{(r)j}^2}}
    \eqn{AUC = 1} indicates perfect simple structure (one non-zero
    loading); \eqn{AUC = 0.5} indicates no simple structure (equal
    loadings). Adjusted AUC subtracts 0.5 so that 0 corresponds to
    no simple structure.
  }

  \subsection{FSI (Lorenzo-Seva, 2003)}{
    Based on the kurtosis of the squared loadings within each factor:
    \deqn{FSI_j = \frac{p \sum l_{ij}^4 - \left(\sum l_{ij}^2\right)^2}
                 {(p-1)\left(\sum l_{ij}^2\right)^2}}
    \eqn{FSI = 0} indicates no simple structure; \eqn{FSI = 1} indicates
    perfect simple structure. More sensitive to dominant loadings than AUC.
  }

  \subsection{Overall solution measures}{
    \strong{Hoffman (1978):}
    \deqn{H = 1 - \frac{\sum_j \sum_i l_{ij}^2 (1 - l_{ij}^2)}{p \cdot k \cdot 0.25}}
    Measures how far loadings are from 0.5. \eqn{H = 1} when all loadings
    are 0 or 1; \eqn{H = 0.25} when all loadings equal 0.5.

    \strong{Gini (Kaiser, 1974):}
    Based on the Gini coefficient of the absolute loadings within each
    factor, averaged across factors. Higher values indicate greater
    concentration of variance on fewer indicators per factor.

    \strong{Bentler (1977):}
    Ratio of between-factor to within-factor variance of squared loadings.
    Values near 1 indicate clean simple structure.
  }

  \subsection{Hyperplane count (Mair, 2018)}{
    For each factor \eqn{j}:
    \deqn{HP_j = \sum_{i=1}^{p} \mathbf{1}(|l_{ij}| < c)}
    where \eqn{c} is the hyperplane cutoff. The theoretical maximum is
    \eqn{p(k-1)}, achieved when each indicator loads on exactly one factor.
    The percentage of the theoretical maximum provides a scale-free summary
    of hyperplane density.
  }

  AUC and FSI are per-factor measures shown in \code{print.GPArotation}.
  All four measures plus their summaries are shown in
  \code{summary.GPArotation}.
}
\examples{
data("CCAI", package = "GPArotation")
fa.un <- factanal(factors = 3, covmat = CCAI_R, n.obs = 461,
                  rotation = "none")

res.tan <- tandemI(fa.un)
res.ob  <- oblimin(fa.un)

# Simple structure measures shown automatically in print
# Orthogonal: SS loadings, Proportion Var, Cumulative Var, AUC, FSI
print(res.tan)

# Oblique: SS loadings, AUC, FSI, Phi
print(res.ob)

# Summary adds overall measures: Hoffman, Gini, Bentler, hyperplane
summary(res.tan)
summary(res.ob)

# Direct access for custom analyses
GPArotation:::calc_AUC(res.ob)
GPArotation:::calc_FSI(res.ob)
GPArotation:::calc_simplicity(res.ob)
GPArotation:::calc_hyperplane(res.ob)

# Stricter hyperplane cutoff
GPArotation:::calc_hyperplane(res.ob, cutoff = 0.05)

# Compare simple structure across rotation methods
auc.tan <- GPArotation:::calc_AUC(res.tan)$AUC_mean
auc.ob  <- GPArotation:::calc_AUC(res.ob)$AUC_mean
fsi.tan <- GPArotation:::calc_FSI(res.tan)$FSI_mean
fsi.ob  <- GPArotation:::calc_FSI(res.ob)$FSI_mean

cat(paste0(formatC("Tandem I", width = 10, flag = "-"),
           "  AUC: ", round(auc.tan, 3),
           "  FSI: ", round(fsi.tan, 3), "\n"))
cat(paste0(formatC("Oblimin", width = 10, flag = "-"),
           "  AUC: ", round(auc.ob, 3),
           "  FSI: ", round(fsi.ob, 3), "\n"))           
}
\seealso{
  \code{\link{print.GPArotation}},
  \code{\link{summary.GPArotation}}
}
\references{
  Bentler, P.M. (1977) Factor simplicity index and transformations.
    \emph{Psychometrika}, \bold{42}(2), 277--295.
    \doi{10.1007/BF02294054}

  Hoffman, P.J. (1978) The paramorphic representation of clinical judgment.
    \emph{Psychological Bulletin}, \bold{55}(2), 116--131.
    \doi{10.1037/h0047807}

  Kaiser, H.F. (1974) An index of factorial simplicity.
    \emph{Psychometrika}, \bold{39}(1), 31--36.
    \doi{10.1007/BF02291575}

  Liu, X., Wallin, G., Chen, Y., and Moustaki, I. (2023). Rotation to
    sparse loadings using \eqn{L^p}{Lp} losses and related inference
    problems. \emph{Psychometrika}, \bold{88}(2), 527--553.
    \doi{10.1007/s11336-023-09911-y}

  Lorenzo-Seva, U. (2003) A factor simplicity index.
    \emph{Psychometrika}, \bold{68}(1), 49--60.
    \doi{10.1007/BF02296652}

  Mair, P. (2018). \emph{Modern Psychometrics with R}.
    Springer. \doi{10.1007/978-3-319-93177-7}
}
\author{Coen A. Bernaards.}
\keyword{internal}
\concept{rotation}
\keyword{multivariate}
