% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/special_effects.R
\name{special_effects}
\alias{special_effects}
\alias{print.special_effects}
\title{Special-effect summaries of a bifactor fit}
\usage{
special_effects(object, tau = 0.5)

\method{print}{special_effects}(x, digits = 3, ...)
}
\arguments{
\item{object}{A fitted \code{\link[=vbfa]{vbfa()}} object with a bifactor structure (see
Details).}

\item{tau}{Hard-selection threshold on the posterior inclusion
probability (default \code{0.5}), used both for group-membership inference
and for the Eq.-16 effect sizes.}

\item{x}{A \code{special_effects} object.}

\item{digits}{Number of decimals in the printed table.}

\item{...}{Unused.}
}
\value{
An object of class \code{special_effects}: a list with
\item{groups}{A data frame with one row per group factor: \code{n_items}
(assigned items), \code{mean_ratio}, \code{sd_ratio}, \code{cv}, \code{gamma}
(second-order loading), and \code{D} (Eq.-16 effect size).}
\item{mean_cv}{The item-weighted mean CV across group factors.}
\item{items}{A data frame with one row per item: assigned \code{group}
(\code{NA} if unassigned), \code{b_gen}, \code{b_grp}, \code{ratio}, and \code{lambda} (the
first-order loading implied by the higher-order parameterization).}
\item{gamma}{Named vector of second-order loadings (same as in
\code{groups}).}
\item{unassigned, crossloaded, no_general}{Integer vectors of item
indices flagged by the membership rules above.}
\item{tau, source, call}{Bookkeeping (\code{source} is \code{"bifactor"} for
native fits, \code{"legacy"} for hand-built ones).}
}
\description{
Post-processes an orthogonal bifactor \code{\link[=vbfa]{vbfa()}} fit into the three
summaries used throughout the \code{bifactor} vignette: (i) the
\strong{Schmid-Leiman (SL) proportionality check} -- the within-group
coefficient of variation (CV) of the group-to-general loading ratio, per
group factor and item-weighted overall; (ii) the \strong{(approximate)
higher-order parameterization} -- second-order loadings
\eqn{\hat\gamma_k = 1/\sqrt{1 + \bar r_k^2}} from each group's mean ratio
\eqn{\bar r_k}, and first-order loadings
\eqn{\hat\lambda_j = |b^{gen}_j| / \hat\gamma_{k(j)}}; and (iii)
\strong{testlet/special effect sizes} by Eq. 16 of Zhang and Chen (2024): the
average squared loading on each group factor, counting specified loadings
always and unspecified ones only when their posterior inclusion
probability exceeds \code{tau}.
}
\details{
All output is \strong{descriptive}. Near-zero CVs signal SL proportionality --
the fitted bifactor is then (approximately) a higher-order model, and by
the same token a testlet model, so the higher-order parameters are a
faithful re-expression. Values near \code{.1} are conventionally read as
approximately higher-order, but the cutoff is suggestive, not a test; the
higher-order parameters and effect sizes are reported regardless, and
with clearly non-constant ratios they are a deliberately lossy summary of
a genuinely richer bifactor. The ratio inherits the sampling softness of
the general/group split, so CVs are noisy below (roughly) a few thousand
observations -- see the \code{bifactor} vignette for demonstrations, caveats,
and the covariance geometry behind all three summaries.

\strong{Which fits are accepted.} A fit with \code{bifactor = TRUE} is used as-is
(general column first, group columns after). A legacy hand-built fit is
also accepted when it has \code{orthogonal = TRUE} and exactly one
all-specified column in \code{Q}, which is taken as the general factor. Group
membership of each item is the group column where it is anchored
(\code{Q == 1}) or, for unspecified rows, its single active group column
(inclusion probability above \code{tau}). Items with no active group loading
are excluded from the ratio summaries and reported; items active on
several group columns are assigned to the anchored one (else the largest
absolute loading) and reported. Ratios use absolute loadings; items whose
general loading is fixed at zero (bifactor-(S-1)-style designs) carry no
ratio and are reported.
}
\examples{
## higher-order data: the ratios are near-constant and gamma is recovered
sim <- sim_fa(N = 500, K = 3, ipf = 6, lam = .8, gamma = c(.8, .7, .6),
              rseed = 11)
Q <- matrix(-1L, 18, 3)
for (k in 1:3) { a <- which(rep(1:3, each = 6) == k)[1:2]
                 Q[a, ] <- 0L; Q[a, k] <- 1L }
fit <- vbfa(sim$dat, Q, bifactor = TRUE, v0 = .001)
special_effects(fit)

}
\references{
Schmid, J., & Leiman, J. M. (1957). The development of hierarchical
factor solutions. \emph{Psychometrika}, 22(1), 53-61.

Yung, Y.-F., Thissen, D., & McLeod, L. D. (1999). On the relationship
between the higher-order factor model and the hierarchical factor model.
\emph{Psychometrika}, 64(2), 113-128.

Zhang, Y., & Chen, J. (2024). Accommodating and extending various models
for special effects within the generalized partially confirmatory factor
analysis framework. \emph{Applied Psychological Measurement}, 48(4-5),
208-229. \doi{10.1177/01466216241261704}
}
\seealso{
\code{\link[=vbfa]{vbfa()}}, and the \code{bifactor} vignette for the full workflow.
}
