RMlocdepGammaCutoff: Simulation-Based Partial Gamma LD Cutoff Determination

In easyRasch2: Psychometric Analysis with Rasch Measurement Theory

Simulation-Based Partial Gamma LD Cutoff Determination

Description

Uses parametric bootstrap simulation to determine appropriate cutoff values for partial gamma Local Dependence analysis via partgam_LD. Under a correctly fitting Rasch model where items are locally independent, this function generates the expected distribution of partial gamma values per item pair, providing empirical critical values.

Usage

RMlocdepGammaCutoff(
  data,
  iterations = 400,
  parallel = TRUE,
  n_cores = NULL,
  verbose = FALSE,
  seed = NULL,
  cutoff_method = "hdci",
  hdci_width = 0.95
)

Arguments

data	A data.frame or matrix of item responses. Items must be scored starting at 0 (non-negative integers). Only complete cases (rows without any NA) are used.
iterations	Integer. Number of simulation iterations (default 400, was 250 before 1.2.0). 400 is the calibrated floor for the Westfall-Young correction (Johansson, 2026) and the count a 95\ converge. Use 1000 to 2000 for a final analysis.
parallel	Logical. Use parallel processing via mirai if available (default TRUE).
n_cores	Integer or NULL. Number of parallel workers. When NULL, getOption("mc.cores") is checked first. If neither is set and parallel = TRUE, a warning is issued and execution falls back to sequential (single core) processing.
verbose	Logical. Show a progress bar (default FALSE).
seed	Integer or NULL. Random seed for reproducibility. See easyRasch2-reproducibility for what this guarantees and how it interacts with parallel.
cutoff_method	Character string specifying how cutoff intervals are computed. Either "hdci" (default) for the Highest Density Interval via ggdist::hdci(), or "quantile" for the 2.5th/97.5th percentiles via stats::quantile().
hdci_width	Numeric. Width of the HDCI when cutoff_method = "hdci". Default is 0.95 (95\ describes where a fitting pair's coefficient is expected to fall and is no longer the default decision rule, so the width is chosen to converge at the default iteration count rather than to imply an error rate. Ignored when cutoff_method = "quantile".

Details

For each simulation iteration the function:

1. Resamples person parameters (thetas) with replacement from the WLE person locations.

2. Simulates item response data under a Rasch model (dichotomous via psychotools::rrm() or polytomous via an internal partial credit simulator).

3. Computes partial gamma for every item pair in both rest-score directions and keeps the larger. The coefficients are identical to those of iarm::partgam_LD(), but are computed by a vectorised internal, since iarm also derives the asymptotic standard error and confidence interval that a simulated null does not need and costs roughly two orders of magnitude more per iteration.

Because the data are simulated under the Rasch model, items are locally independent by construction. The distribution of partial gamma values across iterations provides empirical critical values per item pair. Values from real data that fall outside these bounds suggest local dependence that exceeds what would be expected by chance. Failed iterations (e.g., due to convergence issues or degenerate data) are silently discarded.

The generating model uses CML item thresholds via psychotools::pcmodel() (a dichotomous item is a 2-category PCM) and WLE person locations, consistent with the rest of the package; responses are simulated with psychotools::rrm() (dichotomous) or an internal partial credit score simulator (polytomous).

Parallel processing is provided by the mirai package (optional). Install it with install.packages("mirai") to enable parallelisation.

The iarm package must be installed (it is in Suggests, not Imports).

Value

A list with components:

results

data.frame with columns iteration, Item1, Item2, and gamma (one row per item pair per successful iteration). gamma is the larger of the pair's two rest-score directions, the statistic RMlocdepGamma() tests. Rows are keyed by the sorted pair order, with Item1 before Item2 in column order.

pair_cutoffs

data.frame with per-pair cutoff summaries: Item1, Item2, gamma_low, gamma_high. Bounds are computed using the method specified by cutoff_method.

actual_iterations

Number of successful iterations.

sample_n

Number of complete cases used.

sample_n_total

Number of respondents in the raw input data, before the complete-case filter.

sample_has_na

Logical. Whether the raw input data contained any missing values.

sample_summary

Summary statistics of estimated person parameters.

item_names

Character vector of item names from data.

cutoff_method

The method used to compute cutoffs ("hdci" or "quantile").

hdci_width

The HDCI width used (only meaningful when cutoff_method = "hdci").

References

Christensen, K. B., Kreiner, S. & Mesbah, M. (Eds.) (2013). Rasch Models in Health, pp. 133–135. ISTE & Wiley. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1002/9781118574454")}

See Also

partgam_LD, RMlocdepGamma, RMlocdepGammaPlot

Examples

if (requireNamespace("iarm", quietly = TRUE) &&
    requireNamespace("ggdist", quietly = TRUE)) {
  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 100 iterations sequentially for a quick demo
  cutoff_res <- RMlocdepGammaCutoff(sim_data, iterations = 100,
                                    parallel = FALSE, seed = 42)
  cutoff_res$pair_cutoffs
}

easyRasch2 documentation built on Sept. 13, 2026, 1:07 a.m.