Skip to contents

Computes descriptive Cliff's delta as the number of A-greater-than-B pairs minus A-less-than-B pairs, divided by all available cross-arm pairs. Ties contribute zero. No inferential p value or independence claim is supplied. Pair counts use sorted value frequencies without a cross-product matrix or value subtraction. Every registered group is retained, including empty arms.

Usage

ContrastGroupedRanks(
  data,
  registry,
  groups,
  id,
  arm,
  value,
  missing = c("propagate", "available")
)

Arguments

data

Data frame with group keys, observation IDs, arms and values.

registry

Data frame containing every allowed group key exactly once.

groups

Nonempty character vector naming distinct group columns.

id

Character name of the observation ID column; IDs are unique within each complete group key.

arm

Character name of the arm column, containing exactly "A" or "B".

value

Character name of a numeric column containing finite values or explicit NA. NaN and infinities are rejected. Convert nonfinite input values to NA only through an explicit upstream policy.

missing

"propagate" suppresses delta if any supplied value is NA; "available" explicitly uses available values independently in each arm.

Value

Data frame sorted by group keys, preserving original key values. Supplied, available and unavailable counts are returned for each arm, together with available cross-pair, greater, less and tied counts, delta, missingness policy and status. Empty available arms yield UNAVAILABLE; otherwise propagation with missing values yields MISSING_VALUES, followed by PARTIAL or COMPLETE. Pair counts always describe available values even when delta is suppressed. Counts exceeding exact binary64 integer capacity are rejected before multiplication. An empty registry returns typed output.

Details

Group keys and observation IDs must be dimensionless, nonmissing, nonblank character vectors. Factors and numeric IDs are not coerced. The reserved ASCII 28 separator (intToUtf8(28)) is rejected in keys. Column selections must be distinct, and group columns must not collide with output names. Registry keys must be unique. Every observation must belong to a registered group and have a unique ID within that complete group, including across arms. The same ID may occur in different groups. Arm values must be exactly "A" or "B"; no labels or population policy are inferred.

Delta is positive when A tends to exceed B and negative when B tends to exceed A. It equals the proportion of available cross-arm pairs with A greater than B minus the proportion with A less than B. Equal values, including signed zeros, are ties. Comparisons use represented numeric values without a tolerance. No value subtraction, cross-pair matrix, rank test or resampling is performed. Pair counts above 2^53 - 1 are rejected before multiplication rather than rounded. Sorting distinct values and counting frequencies avoids allocating a Cartesian product, but input and distinct values must still fit in memory.

Available-case analysis filters missing values separately within each arm; it is not paired-observation deletion. Propagation suppresses delta when either supplied arm contains missing values, while still reporting the available pair counts. If an available arm is empty, status is UNAVAILABLE under either policy. A declared group without observations is retained. Group membership and missingness policies do not establish independence or exchangeability. This function computes a descriptive effect only.

Examples

d <- data.frame(
  g = "one", id = letters[1:4],
  arm = c("A", "A", "B", "B"), value = c(2, 4, 1, 2)
)
ContrastGroupedRanks(d, data.frame(g = "one"), "g", "id", "arm", "value")
#>     g n_a_supplied n_b_supplied n_a_available n_b_available n_a_unavailable
#> 1 one            2            2             2             2               0
#>   n_b_unavailable n_pairs n_a_greater n_a_less n_tied delta_a_vs_b   status
#> 1               0       4           3        0      1         0.75 COMPLETE
#>   missing_policy
#> 1      propagate