plot_residual_pca: Visualize residual PCA results

In mfrmr: Estimation and Diagnostics for Many-Facet Measurement Models

Visualize residual PCA results

Description

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.

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.

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

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

1. Run diagnose_mfrm() with residual_pca = "overall" or "both".

2. Build PCA object via analyze_residual_pca() (or pass diagnostics directly).

3. Use scree plot first, then loadings plot for targeted interpretation.

See Also

analyze_residual_pca(), diagnose_mfrm()

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)
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")
}

mfrmr documentation built on March 31, 2026, 1:06 a.m.