plot_misfit: Plot person misfit in 2D/3D using stored thresholds

Description

plot_misfit() visualizes person-level misfit statistics stored in an epmfd_misfit object. It supports:

2D: scatter plots for all pairwise combinations of the selected statistics (or a single 2D plot if exactly two are given). Points are coloured by the joint exceedance logic (see any). Axis titles are the statistic names; the main title shows the cut-offs in parentheses, and dashed lines mark the cut-offs per axis.
3D: an interactive scatter using plotly if three statistics are supplied; optionally adds three semi-transparent planes at the x/y/z cut-offs when planes = TRUE.

Usage

plot_misfit(
  object,
  stats = NULL,
  threeD = FALSE,
  any = FALSE,
  planes = TRUE,
  label_ids = FALSE,
  ...
)

Value

A ggplot object (2D), a named list of ggplots (all 2D pairs), or a plotly object (3D), depending on stats and threeD.

Arguments

object

An epmfd_misfit or epmfd_clean object. If epmfd_clean is supplied, its $misfit component is used.

stats

Character vector of length 2 or 3 naming statistics found in object$scores (e.g., c("Gnp","U3p","lpz")). If NULL, the first up to three available statistics are used.

threeD

Logical. If TRUE and three statistics are available, a 3D plotly plot is drawn; otherwise the function falls back to 2D and emits a warning.

any

Logical. Colouring rule:

FALSE (default): only two classes - all cut-offs exceeded (red) vs none exceeded (blue).
TRUE: adds an intermediate class (orange) for partial exceedance (in 2D: exactly one; in 3D: one or two).

planes

Logical (3D only). If TRUE, draw three semi-transparent planes at the x, y, and z cut-off values; if FALSE, no planes are shown. Ignored for 2D plots.

label_ids

Logical. If TRUE, label points by id in 2D plots (uses ggrepel when available).

...

Additional aesthetics passed to ggplot2::geom_point() (2D) or plotly::add_markers() (3D), such as alpha, size, etc.

Details

Cut-off logic. For each selected statistic, a person is deemed to exceed if its score is greater than the cut-off for upper-tailed statistics or less than the cut-off for lower-tailed statistics. In 2D, dashed vertical and horizontal lines indicate the cut-offs; the plot title shows "Y (cutY) vs X (cutX)" with formatted values. In 3D, axis titles include the cut-off values in parentheses, and (optionally) three grey planes make the cut-offs explicit.

Returned value. With two statistics, a single ggplot is returned; with three statistics and threeD = FALSE, a named list of ggplots is returned for all 2D pairs. With threeD = TRUE and three statistics, a plotly object is returned.

Dependencies. This function uses ggplot2 for 2D plots and, for 3D, plotly (required only when threeD = TRUE). Optional labels in 2D use ggrepel when installed.

Examples

Run this code

if (FALSE) {
# \donttest{
# Suppose 'mf' is an epmfd_misfit with scores Gnp, U3p, lpz

# 2D: single plot
plot_misfit(mf, stats = c("Gnp","U3p"), any = TRUE)

# 2D: all pairwise plots
plot_misfit(mf, stats = c("Gnp","U3p","lpz"))

# 3D: with cut-off planes
plot_misfit(mf, stats = c("Gnp","U3p","lpz"), threeD = TRUE, planes = TRUE)

# 3D: points only (no planes)
plot_misfit(mf, stats = c("Gnp","U3p","lpz"), threeD = TRUE, planes = FALSE)
# }
}