Package 'exactGMH'

Exact/permutation Mantel test for a single item

Description

Computes the Mantel (1963) / Mantel-Haenszel DIF statistic for a single dichotomous or polytomous item, with statistical significance obtained via permutation of group membership within score-matched strata. Following Hemerik and Goeman (2018), the observed statistic is included among the reference draws (the "+1" correction), which guarantees the resulting p-value is exact at the nominal level rather than merely an asymptotic approximation, even for a finite number of permutations.

Usage

exact_mantel_dif(item_score, group, total_score, n_perm = 5000, seed = 123)

Arguments

item_score	Numeric vector of item scores: 0/1 for dichotomous items, or 0..C-1 for polytomous items (e.g., a 5-point rubric coded 0-4).
group	Vector of group membership (exactly 2 levels, e.g., "Reference" / "Focal").
total_score	Numeric vector used as the matching/stratification variable, typically the total test score computed after removing the item under study.
n_perm	Integer; number of permutations (default 5000). Larger values give a more precise p-value at the cost of computation time.
seed	Integer; random seed for reproducibility (default 123).

Value

A one-row data frame with columns:

item_type

"Dichotomous" or "Polytomous" (auto-detected).

z_statistic

Standardized Mantel statistic.

effect_size

Delta-MH (dichotomous) or standardized difference (polytomous).

effect_label

Label describing the effect size column.

chi_asymp

Asymptotic chi-square statistic (for comparison).

p_asymptotic

p-value from the conventional asymptotic chi-square approximation.

p_exact_perm

Exact permutation-based p-value (recommended).

classification

ETS-style DIF classification: "A (negligible)", "B (moderate)", or "C (large)".

n_permutations

Number of permutations used.

References

Mantel, N. (1963). Chi-square tests with one degree of freedom: Extensions of the Mantel-Haenszel procedure. Journal of the American Statistical Association, 58(303), 690-700. doi:10.1080/01621459.1963.10500879

Hemerik, J., & Goeman, J. (2018). Exact testing with random permutations. TEST, 27(4), 811-825. doi:10.1007/s11749-017-0571-1

Examples

set.seed(1)
n <- 60
group <- rep(c("Reference", "Focal"), each = n / 2)
item <- rbinom(n, 1, 0.5)
total <- rowSums(replicate(5, rbinom(n, 1, 0.5)))
exact_mantel_dif(item, group, total, n_perm = 500)

---

Screen all items in a test for Differential Item Functioning

Description

Runs the exact/permutation Mantel test (see exact_mantel_dif) on every column of a response matrix. Dichotomous (0/1) and polytomous (0..C-1) items may be freely mixed within the same matrix; item type is auto-detected per column.

Usage

run_dif_screening(
  response_matrix,
  group,
  n_perm = 5000,
  seed = 123,
  p_adjust_method = "none"
)

Arguments

response_matrix	A numeric matrix or data frame of item responses: rows are examinees, columns are items.
group	Vector of group membership (2 levels), of the same length as nrow(response_matrix).
n_perm	Integer; number of permutations per item (default 5000).
seed	Integer; base random seed (default 123). Each item uses seed + column_index internally for reproducible but non-identical permutation draws across items.
p_adjust_method	Character; multiple-testing correction method passed to p.adjust (e.g., "BH" for Benjamini-Hochberg, "bonferroni"). Default "none" returns unadjusted per-item p-values.

Value

A data frame with one row per item; see exact_mantel_dif for column descriptions. An additional item column identifies each item (from colnames(response_matrix) if available), and, when p_adjust_method != "none", a p_exact_adjusted column is added and used to update the classification column.

Examples

set.seed(42)
n <- 80
group <- rep(c("Reference", "Focal"), each = n / 2)
# 3 dichotomous items, 2 polytomous items (0-3)
resp <- data.frame(
  Item1 = rbinom(n, 1, 0.5),
  Item2 = rbinom(n, 1, 0.5),
  Item3 = rbinom(n, 1, 0.5),
  Item4 = sample(0:3, n, replace = TRUE),
  Item5 = sample(0:3, n, replace = TRUE)
)
run_dif_screening(resp, group, n_perm = 500, p_adjust_method = "BH")

---