liu_agresti_ccor: Liu-Agresti Common Cumulative Odds Ratio

In difR: Collection of Methods to Detect Dichotomous, Polytomous, and Continuous Differential Item Functioning (DIF)

Liu–Agresti Common Cumulative Odds Ratio

Description

Computes the Liu–Agresti estimate of the common cumulative odds ratio (\Psi) and its log (\alpha = \log \Psi) for ordinal data from two independent groups. This statistic quantifies the direction and strength of ordinal association between groups. The implementation follows Section 2 of Liu & Agresti (1996), treating the first level of group as the reference.

Usage

liu_agresti_ccor(responses, group, strata = NULL,
                 se = c("liu_agresti","bootstrap","naive"),
                 B = 1000, seed = NULL, eps = 1e-12)

Arguments

responses	A numeric vector (typically coded as consecutive integers, e.g., 1 to 5 for a Likert-type scale) or an ordered factor of ordinal item responses. Numeric inputs are internally converted to an ordered factor via sort(unique(responses)).
group	A grouping vector indicating the group to which each observation belongs. It must contain exactly two unique values (e.g., "ref" and "foc"). The first level is the reference (compared to the second).
strata	Optional factor/character of length n giving strata (matching blocks). If NULL, a single stratum is used.
se	Standard-error method: "liu_agresti" (delta with multinomial variance; recommended), "bootstrap" (percentile CI on \log \Psi), or "naive" (simple large-sample SE on \log \Psi).
B	Number of bootstrap replicates when se = "bootstrap".
seed	Optional RNG seed for bootstrap reproducibility.
eps	Small numerical constant for stability (avoids zero divisions).

Details

This function creates a contingency table of dimension 2 \times C, where C denotes the number of distinct ordinal response categories. It computes cumulative marginal frequencies and estimates the odds ratio using Liu and Agresti's formulation (1996). The variance of the log-transformed estimate is computed according to their Eq.~3.

Formally, letting cumulation be over Y \le j, and with N_k = n_{1k} + n_{2k} for stratum k, the estimator is

\widehat{\Psi}=\frac{\sum_k \sum_{j=1}^{C-1} (a_{jk} d_{jk})/N_k}{\sum_k \sum_{j=1}^{C-1} (b_{jk} c_{jk})/N_k},

with the first level of group as the reference and the second as the focal. The estimator reduces to the standard Mantel–Haenszel odds ratio when C = 2.

The estimate \widehat{\Psi} is based on cumulative frequencies and is designed for ordinal response categories. It quantifies the association between group membership and the likelihood of higher category responses.

Strata in which at least one of the two groups is completely absent are skipped in the computation of the estimator.

The function is not designed to handle missing values; observations with NA should be removed prior to use.

If one of the response categories is completely absent from one group, then the cumulative margins used in the computation may contain zero values. In such cases, either the numerator or the denominator of the Liu–Agresti formula will be zero, making the estimate numerically unstable. When this occurs, the estimate may be 0, Inf, or NaN, and users should carefully inspect the output and, if necessary, collapse sparse categories or strata.

When strata are very small or categories are extremely sparse, consider se = "bootstrap" for more robust interval estimation.

Value

A named vector (class "liu_agresti_ccor") returning the following elements (the first three mirror the original concise summary, additional fields follow for inference):

Psi_hat	The Liu–Agresti estimate of the common cumulative odds ratio (\widehat{\Psi}).
Alpha_hat	\log(\widehat{\Psi}).
SE_log_Psi	The standard error of \log(\widehat{\Psi}), which can be used to construct confidence intervals or conduct hypothesis testing.
z	Wald statistic based on \log(\widehat{\Psi}).
p_two_sided	Two-sided p-value associated with the Wald statistic.
CI_log_lower	Lower bound of the 95% confidence interval for \log(\Psi).
CI_log_upper	Upper bound of the 95% confidence interval for \log(\Psi).

Author(s)

Sebastien Beland
Faculte des sciences de l'education
Universite de Montreal (Canada)
[e-mail]

References

Liu, I., & Agresti, A. (1996). Mantel–Haenszel-Type Inference for Cumulative Odds Ratios with a Stratified Ordinal Response. Biometrics, 52(4), 1223–1234.

See Also

mantelhaen.test (binary case), clm, vglm for parametric cumulative logit models.

Examples

# Simulated balanced example
set.seed(123)

group <- rep(c("ref", "foc"), each = 100)
stopifnot(length(group) == 200)

responses <- sample(1:4, size = length(group), replace = TRUE)
stopifnot(length(responses) == length(group))

liu_agresti_ccor(as.integer(responses), factor(group))

difR documentation built on Nov. 29, 2025, 9:06 a.m.