% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/api-tables.R
\name{plot_residual_pca}
\alias{plot_residual_pca}
\title{Visualize residual PCA results}
\usage{
plot_residual_pca(
  x,
  mode = c("overall", "facet"),
  facet = NULL,
  plot_type = c("scree", "parallel_scree", "parallel_excess", "loadings"),
  component = 1L,
  top_n = 20L,
  preset = c("standard", "publication", "compact", "monochrome"),
  draw = TRUE
)
}
\arguments{
\item{x}{Output from \code{\link[=analyze_residual_pca]{analyze_residual_pca()}}, \code{\link[=diagnose_mfrm]{diagnose_mfrm()}}, or \code{\link[=fit_mfrm]{fit_mfrm()}}.}

\item{mode}{\code{"overall"} or \code{"facet"}.}

\item{facet}{Facet name for \code{mode = "facet"}.}

\item{plot_type}{\code{"scree"}, \code{"parallel_scree"},
\code{"parallel_excess"}, or \code{"loadings"}.}

\item{component}{Component index for loadings plot.}

\item{top_n}{Maximum number of variables shown in loadings plot.}

\item{preset}{Visual preset (\code{"standard"}, \code{"publication"}, \code{"compact"}, or \code{"monochrome"}).}

\item{draw}{If \code{TRUE}, draws the plot using base graphics.}
}
\value{
A named list of plotting data (class \code{mfrm_plot_data}) with:
\itemize{
\item \code{plot}: \code{"scree"}, \code{"parallel_scree"}, \code{"parallel_excess"}, or
\code{"loadings"}
\item \code{mode}: \code{"overall"} or \code{"facet"}
\item \code{facet}: facet name (or \code{NULL})
\item \code{title}: plot title text
\item \code{data}: underlying table used for plotting
}
}
\description{
Visualize residual PCA results
}
\details{
\code{x} can be either:
\itemize{
\item output of \code{\link[=analyze_residual_pca]{analyze_residual_pca()}}, or
\item a diagnostics object from \code{\link[=diagnose_mfrm]{diagnose_mfrm()}} (PCA is computed internally), or
\item a fitted object from \code{\link[=fit_mfrm]{fit_mfrm()}} (diagnostics and PCA are computed internally).
}

Plot types:
\itemize{
\item \code{"scree"}: component vs eigenvalue line plot
\item \code{"parallel_scree"}: observed eigenvalues with residual-permutation
parallel-analysis mean and upper cutoff
\item \code{"parallel_excess"}: observed eigenvalue minus the parallel-analysis
cutoff by component
\item \code{"loadings"}: horizontal bar chart of top absolute loadings
}

For \code{mode = "facet"} and \code{facet = NULL}, the first available facet is used.
}
\section{Interpreting output}{

\itemize{
\item \code{plot_type = "scree"}: look for dominant early components relative
to later components and the unit-eigenvalue reference line. Treat
this as exploratory residual-structure screening, not a standalone
unidimensionality test or a DIMTEST/UNIDIM substitute.
\item \code{plot_type = "parallel_scree"} or \code{"parallel_excess"}: use only after
running \code{\link[=analyze_residual_pca]{analyze_residual_pca()}} with \code{parallel = TRUE}. Components
above the residual-permutation cutoff are candidates for follow-up,
not proof of multidimensionality.
\item \code{plot_type = "loadings"}: identifies variables/elements driving each
component; inspect both sign and absolute magnitude.
}

Facet mode (\code{mode = "facet"}) helps localize residual structure to a
specific facet after global PCA review.
}

\section{Typical workflow}{

\enumerate{
\item Run \code{\link[=diagnose_mfrm]{diagnose_mfrm()}} with \code{residual_pca = "overall"} or \code{"both"}.
\item Build PCA object via \code{\link[=analyze_residual_pca]{analyze_residual_pca()}} (or pass diagnostics directly).
\item Use scree plot first, then loadings plot for targeted interpretation.
}
}

\examples{
toy_full <- load_mfrmr_data("example_core")
toy_people <- unique(toy_full$Person)[1:24]
toy <- toy_full[match(toy_full$Person, toy_people, nomatch = 0L) > 0L, , drop = FALSE]
fit <- suppressWarnings(
  fit_mfrm(toy, "Person", c("Rater", "Criterion"), "Score", method = "JML", maxit = 30)
)
diag <- diagnose_mfrm(fit, residual_pca = "overall")
pca <- analyze_residual_pca(diag, mode = "overall")
plt <- plot_residual_pca(pca, mode = "overall", plot_type = "scree", draw = FALSE)
head(plt$data)
\donttest{
pca_pa <- analyze_residual_pca(diag, mode = "overall", parallel = TRUE, parallel_reps = 10)
pa <- plot_residual_pca(pca_pa, mode = "overall", plot_type = "parallel_scree", draw = FALSE)
head(pa$data)
}
plt_load <- plot_residual_pca(
  pca, mode = "overall", plot_type = "loadings", component = 1, draw = FALSE
)
head(plt_load$data)
if (interactive()) {
  plot_residual_pca(pca, mode = "overall", plot_type = "scree", preset = "publication")
}
}
\seealso{
\code{\link[=analyze_residual_pca]{analyze_residual_pca()}}, \code{\link[=diagnose_mfrm]{diagnose_mfrm()}}
}
