Visualize residual PCA results

Usage

plot_residual_pca(
  x,
  mode = c("overall", "facet"),
  facet = NULL,
  plot_type = c("scree", "loadings"),
  component = 1L,
  top_n = 20L,
  preset = c("standard", "publication", "compact"),
  draw = TRUE
)

Arguments

x: Output from analyze_residual_pca(), diagnose_mfrm(), or fit_mfrm().
mode: "overall" or "facet".
facet: Facet name for mode = "facet".
plot_type: "scree" or "loadings".
component: Component index for loadings plot.
top_n: Maximum number of variables shown in loadings plot.
preset: Visual preset ("standard", "publication", or "compact").
draw: If TRUE, draws the plot using base graphics.

Value

A named list of plotting data (class mfrm_plot_data) with:

plot: "scree" or "loadings"
mode: "overall" or "facet"
facet: facet name (or NULL)
title: plot title text
data: underlying table used for plotting

Details

x can be either:

output of analyze_residual_pca(), or
a diagnostics object from diagnose_mfrm() (PCA is computed internally), or
a fitted object from fit_mfrm() (diagnostics and PCA are computed internally).

Plot types:

"scree": component vs eigenvalue line plot
"loadings": horizontal bar chart of top absolute loadings

For mode = "facet" and facet = NULL, the first available facet is used.

Interpreting output

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.
plot_type = "loadings": identifies variables/elements driving each component; inspect both sign and absolute magnitude.

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

Typical workflow

Run diagnose_mfrm() with residual_pca = "overall" or "both".
Build PCA object via analyze_residual_pca() (or pass diagnostics directly).
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 = 15)
)
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)
#> $plot
#> [1] "scree"
#> 
#> $mode
#> [1] "overall"
#> 
#> $facet
#> NULL
#> 
#> $title
#> [1] "Overall Residual PCA (Scree)"
#> 
#> $subtitle
#> [1] "Variance explained by residual components"
#> 
#> $legend
#>                       label      role  aesthetic   value
#> 1      Residual eigenvalues component line-point #1f78b4
#> 2 Unit-eigenvalue reference reference       line #6b7280
#> 
plt_load <- plot_residual_pca(
  pca, mode = "overall", plot_type = "loadings", component = 1, draw = FALSE
)
head(plt_load$data)
#> $plot
#> [1] "loadings"
#> 
#> $mode
#> [1] "overall"
#> 
#> $facet
#> NULL
#> 
#> $title
#> [1] "Overall Residual PCA (Loadings: PC1)"
#> 
#> $subtitle
#> [1] "Top 16 absolute loadings"
#> 
#> $legend
#>               label    role aesthetic   value
#> 1 Positive loadings loading       bar #1b9e77
#> 2 Negative loadings loading       bar #d95f02
#> 
if (interactive()) {
  plot_residual_pca(pca, mode = "overall", plot_type = "scree", preset = "publication")
}