Skip to contents

Plot Distribution of Simulated Partial Gamma LD Values

Source: R/ld_partgam.R
RMlocdepGammaPlot.Rd

Visualises the distribution of simulation-based partial gamma LD values from RMlocdepGammaCutoff, optionally overlaying observed partial gamma values computed from real data via partgam_LD.

Usage

RMlocdepGammaPlot(simfit, data, items = NULL, n_pairs = NULL)

Arguments

simfit

The return value of RMlocdepGammaCutoff (a list with components results, pair_cutoffs, actual_iterations, sample_n, and item_names).

data

Optional. A data.frame or matrix of item responses for computing and overlaying observed partial gamma values. Items must be scored starting at 0 (non-negative integers). When provided, the plot includes orange diamond markers for the observed partial gamma alongside the simulated distribution, plus segment summaries from the cutoff intervals.

items

Optional character vector of item names to include in the plot. Only item pairs where both items are in this vector will be shown. When NULL (default), all item pairs are plotted.

n_pairs

Optional positive integer. When supplied, only the n_pairs item pairs with the largest absolute partial gamma values are plotted, sorted by |gamma| descending. When data is supplied, the ranking uses the observed partial gammas (the diamonds you actually want to interpret); otherwise it falls back to the per-pair median of the simulated distributions. Applied after the items filter when both are supplied. Values larger than the number of available pairs are silently capped.

Value

A ggplot object.

Details

Uses ggdist::stat_dotsinterval() (when data is not supplied) or ggdist::stat_dots() (when data is supplied) with point_interval = "median_hdci" and .width = c(0.66, 0.95, 0.99).

The plot shows one row per item pair (labelled as "Item1 - Item2"). Only direction 1 (rest score = total - Item2) is plotted, matching the convention used in the simulation.

When data is not supplied, the function plots the simulated partial gamma distributions as dot-interval plots using ggdist::stat_dotsinterval() with median and Highest Density Continuous Interval (HDCI) summaries.

When data is supplied, the function:

  1. Computes observed partial gamma values via iarm::partgam_LD().

  2. Overlays observed gamma values as orange diamond markers on the simulated distributions.

  3. Shows per-pair cutoff intervals (from simfit$pair_cutoffs) as black line segments, with thicker segments for the 66\ black dots for the median.

The ggplot2, ggdist, and optionally iarm packages must be installed (they are in Suggests, not Imports).

See also

RMlocdepGammaCutoff, RMlocdepGamma

Examples

# \donttest{
set.seed(42)
sim_data <- as.data.frame(
  matrix(sample(0:1, 200 * 10, replace = TRUE), nrow = 200, ncol = 10)
)
colnames(sim_data) <- paste0("Item", 1:10)

# Run simulation
cutoff_res <- RMlocdepGammaCutoff(sim_data, iterations = 100, parallel = FALSE,
                           seed = 42)

# Simulated distribution only
RMlocdepGammaPlot(cutoff_res)


# With observed partial gamma overlaid
RMlocdepGammaPlot(cutoff_res, data = sim_data)


# Plot only a subset of items
RMlocdepGammaPlot(cutoff_res, data = sim_data,
           items = c("Item1", "Item2", "Item3"))

# }