RMlocdepGamma: Partial Gamma Local Dependence Analysis

In easyRasch2: Psychometric Analysis with Rasch Measurement Theory

Partial Gamma Local Dependence Analysis

Description

Computes partial gamma coefficients for Local Dependence (LD) assessment using iarm::partgam_LD(). Each pair of items is tested for residual association, controlling for the rest score (total score minus one of the items in the pair).

Usage

RMlocdepGamma(
  data,
  cutoff = NULL,
  p_value = NULL,
  correction = c("fwer", "fdr_bh", "fdr_by", "none"),
  alpha = 0.05,
  output = "kable",
  n_pairs = NULL
)

Arguments

data	A data.frame or matrix of item responses. Items must be scored starting at 0 (non-negative integers). Missing values (NA) are allowed, but at least one complete case must exist.
cutoff	Optional. Default NULL (no cutoff applied). Can be: The return value of RMlocdepGammaCutoff (a list with ⁠$pair_cutoffs⁠): the data.frame is extracted automatically and simulation metadata is included in the kable caption. The ⁠$pair_cutoffs⁠ data.frame from RMlocdepGammaCutoff directly: must have columns Item1, Item2, gamma_low, gamma_high. When provided, adds columns Gamma_low, Gamma_high, and Flagged (logical; TRUE when the observed partial gamma falls outside the credible range) to the result.
p_value	Logical or NULL. When TRUE, adds one-sided bootstrap p-values for excess positive local dependence (p_gamma, padj_gamma), matching the p_value semantics of RMlocdepQ3, and flagged reflects padj_gamma < alpha (positive deviations only) instead of the credible range. One test per item pair: the p-value is computed on gamma_pair, the larger of the two conditioning directions, and repeated in the direction-2 table for the same pair. The asymptotic adjusted p-value and star columns from iarm::partgam_LD() are dropped in this mode, and the simulated gamma_low / gamma_high band is kept as the effect-size reference. NULL, the default, means TRUE when cutoff is the full RMlocdepGammaCutoff object (it carries the simulated distributions in ⁠$results⁠) and FALSE otherwise, so calling with no cutoff keeps the asymptotic table unchanged. Pass FALSE for the pre-1.2.0 behaviour. The interval makes a poor decision rule, since its width sets a family-wise error rate of 1 - width^m over all m pairs at once (Johansson, 2026).
correction	Character. Multiplicity correction for the bootstrap p-values, applied over the family of all item pairs (before any n_pairs display filter): "fwer" (default; Westfall-Young studentised-max step-down), "fdr_bh", "fdr_by", or "none". Ignored when p_value = FALSE.
alpha	Numeric in (0, 1). Significance level used to flag pairs on the corrected p-value. Default 0.05. Ignored when p_value = FALSE.
output	Character string controlling the return value. Either "kable" (default) for a formatted knitr::kable() table, or "dataframe" for the underlying data.frame.
n_pairs	Optional positive integer. When supplied, only the n_pairs item pairs with the largest absolute partial-gamma values (i.e., strongest residual dependence in either direction) are retained per rest-score direction, sorted by ⁠|gamma|⁠ descending. When NULL (default), all pairs are returned in iarm's native ordering. Values larger than the total number of pairs are silently capped at that total.

Details

Partial gamma (Christensen, Kreiner & Mesbah, 2013) measures the residual association between pairs of items after controlling for the rest score (total score minus one item). Because it matters which item is subtracted, calculations are done for each pair in both directions, yielding two data.frames.

Values near 0 indicate no local dependence. Large positive values suggest positive LD (items share variance beyond the latent trait), while large negative values suggest negative LD.

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

Bootstrap p-values. When p_value = TRUE, each pair is tested once, on the larger of its two rest-score directions (the gamma_pair column), against its simulated null distribution (from cutoff$results, simulated under local independence and built from that same maximum). The per-pair statistic is the residual studentised by the bootstrap mean and SD; the marginal p-value is the one-sided Monte-Carlo p-value ⁠(1 + #\{t* >= t\}) / (B + 1)⁠ for excess positive LD (redundancy, the diagnostic target — matching RMlocdepQ3), so it can be no smaller than 1 / (B + 1). The band still shows both bounds for reference. correction = "fwer" uses the Westfall-Young studentised-max step-down over the family of all pairs, which exploits the bootstrap dependence among them (Ferreira, 2024); it is liberal when the simulation is small, so at least 1000 iterations in RMlocdepGammaCutoff() are recommended (a warning is issued below that). Unlike the asymptotic p-values from iarm::partgam_LD(), these are calibrated against the simulated Rasch null rather than the asymptotic SE; they are model-conditional and sample-size-sensitive, and are reported alongside the simulated effect-size band, not in place of it.

Value

• If output = "kable": an object of class "RMlocdepGamma". Internally a list with two knitr_kable elements, ⁠$direction1⁠ and ⁠$direction2⁠. In both, the rest score is the total score minus Item 2 (the second column); the two elements list each item pair in the two possible orders, so together they cover both rest-score directions for every pair. Each has columns "Item 1", "Item 2", "Partial gamma", "Adj. p-value (BH)", and "p-value sign." (a star-string indicator from iarm::partgam_LD()). When cutoff is provided, additional columns "Gamma low", "Gamma high", and "Flagged" are included.

  The object has custom print() and knitr::knit_print() methods: in the R console it prints the two tables stacked vertically; in a Quarto / R Markdown chunk it renders as two distinct pipe tables. Access the individual tables explicitly as result$direction1 and result$direction2 if needed.

• If output = "dataframe": a named list of two data.frames (⁠$direction1⁠, ⁠$direction2⁠) with columns Item1, Item2, gamma, se, lower, upper (95% Wald CI), padj_bh, Significance. When cutoff is provided, columns gamma_low, gamma_high, and flagged are also included. With p_value = TRUE, padj_bh and Significance are replaced by p_gamma and padj_gamma (identical for a pair in both directions).

Multiple comparisons

The marginal p-value controls the error rate of a single comparison: for one item (or item pair) decided on in advance it is the relevant value. But scanning all k comparisons and flagging whichever fall below alpha tests k hypotheses at once, so the chance of at least one false flag inflates to roughly 1 - (1 - \alpha)^k (e.g. about 34% for k = 8 at alpha = 0.05) – even when every marginal p-value is correctly calibrated. The corrected (adjusted) p-value controls this: correction = "fwer" bounds the probability of any false flag (strict, lower power), while "fdr_bh" / "fdr_by" bound the expected proportion of false flags among those raised (a more lenient middle ground). Rule of thumb: use the marginal p-value for a single pre-specified comparison, and a corrected p-value when screening the whole table – the usual workflow.

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

Ferreira, J. A. (2024). Methods of testing a 'small' or 'moderate' number of hypotheses simultaneously. Journal of Statistical Theory and Practice, 19(6). \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1007/s42519-024-00412-4")}

Westfall, P. H., & Young, S. S. (1993). Resampling-Based Multiple Testing. Wiley.

See Also

RMlocdepGammaCutoff, RMlocdepGammaPlot

Examples

if (requireNamespace("iarm", 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)

  # Default kable output
  RMlocdepGamma(sim_data)

  # Return as data.frame list
  RMlocdepGamma(sim_data, output = "dataframe")

  # Simulation-based cutoffs (slow): 100+ Monte-Carlo iterations
  if (requireNamespace("ggdist", quietly = TRUE)) {
    cutoff_res <- RMlocdepGammaCutoff(sim_data, iterations = 100,
                                      parallel = FALSE, seed = 42)
    RMlocdepGamma(sim_data, cutoff = cutoff_res)

    # Bootstrap p-values with family-wise (Westfall-Young) correction
    # (use iterations >= 1000 in real analyses for stable p-values)
    RMlocdepGamma(sim_data, cutoff = cutoff_res, p_value = TRUE,
                  output = "dataframe")
  }
}

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