Disparity

where $\operatorname{AvgSpread}(\mathbf{x}, \mathbf{y}) = (n \cdot \operatorname{Spread}(\mathbf{x}) + m \cdot \operatorname{Spread}(\mathbf{y})) / (n + m)$ is the weighted average of dispersions (pooled scale).

Robust effect size (shift normalized by pooled spread).

Input

• $\mathbf{x} = (x_1, x_2, \ldots, x_n)$ — first sample of measurements, requires sparity(x)
• $\mathbf{y} = (y_1, y_2, \ldots, y_m)$ — second sample of measurements, requires sparity(y)

Output

• Value — $\operatorname{Shift}(\mathbf{x}, \mathbf{y}) / \operatorname{AvgSpread}(\mathbf{x}, \mathbf{y})$
• Unit — spread units

Notes

• Robust alternative to — Cohen’s d (Cohen 1988; uses robust shift and spread instead of mean difference and pooled standard deviation)

Properties

• Location invariance $\operatorname{Disparity}(\mathbf{x} + k, \mathbf{y} + k) = \operatorname{Disparity}(\mathbf{x}, \mathbf{y})$
• Scale invariance $\operatorname{Disparity}(k \cdot \mathbf{x}, k \cdot \mathbf{y}) = \operatorname{sign}(k) \cdot \operatorname{Disparity}(\mathbf{x}, \mathbf{y})$
• Antisymmetry $\operatorname{Disparity}(\mathbf{x}, \mathbf{y}) = -\operatorname{Disparity}(\mathbf{y}, \mathbf{x})$

Example

• Disparity(x, y) = 0.4 where Shift = 2, AvgSpread = 5
• Disparity(x + c, y + c) = Disparity(x, y) Disparity(kx, ky) = Disparity(x, y)

$\operatorname{Disparity}$ expresses a difference between groups in a way that does not depend on the original measurement units. A disparity of 0.5 means the groups differ by half a spread unit; 1.0 means one full spread unit. Being dimensionless allows comparison of effect sizes across different studies, metrics, or measurement scales. What counts as a “large” or “small” disparity depends entirely on the domain and what matters practically in a given application. Do not rely on universal thresholds; interpret the number in context.

Algorithm

The $\operatorname{Disparity}$ estimator is a composition of Shift and Spread:

where $\operatorname{AvgSpread}(\mathbf{x}, \mathbf{y}) = (n \cdot \operatorname{Spread}(\mathbf{x}) + m \cdot \operatorname{Spread}(\mathbf{y})) / (n + m)$ is the pooled scale.

The algorithm proceeds as follows:

• Compute Spread for each sample — Delegate to the Spread algorithm for $\mathbf{x}$ and $\mathbf{y}$ independently.

• Compute AvgSpread — Form the weighted average $\operatorname{AvgSpread} = (n \cdot \operatorname{Spread}(\mathbf{x}) + m \cdot \operatorname{Spread}(\mathbf{y})) / (n + m)$.

• Domain check — Verify that $\operatorname{AvgSpread} > 0$. If the pooled spread is zero, the division is undefined.

• Compute Shift — Delegate to the Shift algorithm for the pair $(\mathbf{x}, \mathbf{y})$.

• Divide — Return $\operatorname{Shift}(\mathbf{x}, \mathbf{y}) / \operatorname{AvgSpread}(\mathbf{x}, \mathbf{y})$.

using Pragmastat.Algorithms;
using Pragmastat.Exceptions;
using Pragmastat.Internal;
using Pragmastat.Metrology;

namespace Pragmastat.Estimators;

public class DisparityEstimator : ITwoSampleEstimator
{
  public static readonly DisparityEstimator Instance = new();

  /// <summary>
  /// Raw native-array entry point. Returns a unitless disparity estimate.
  /// </summary>
  /// <param name="x">First sample values.</param>
  /// <param name="y">Second sample values.</param>
  /// <param name="assumeSorted">
  /// When true, both <paramref name="x"/> and <paramref name="y"/> are assumed already sorted
  /// ascending and the internal sort is skipped. This changes the computation path; passing true
  /// on unsorted input is undefined behavior and yields a wrong result. The caller is responsible.
  /// </param>
  public double Estimate(double[] x, double[] y, bool assumeSorted = false) => EstimateRaw(x, y, assumeSorted);

  public Measurement Estimate(Sample x, Sample y)
  {
    Assertion.NonWeighted("x", x);
    Assertion.NonWeighted("y", y);
    Assertion.CompatibleUnits(x, y);
    (x, y) = Assertion.ConvertToFiner(x, y);
    return EstimateRaw(x.SortedValues, y.SortedValues, assumeSorted: true).WithUnit(MeasurementUnit.Disparity);
  }

  /// <summary>
  /// Single shared implementation. Both the raw and Sample entry points call this.
  /// </summary>
  internal static double EstimateRaw(IReadOnlyList<double> x, IReadOnlyList<double> y, bool assumeSorted)
  {
    Assertion.Validity(x, Subject.X);
    Assertion.Validity(y, Subject.Y);

    int n = x.Count;
    int m = y.Count;

    var spreadX = SpreadImpl.Estimate(x, assumeSorted: assumeSorted);
    if (spreadX <= 0)
      throw AssumptionException.Sparity(Subject.X);
    var spreadY = SpreadImpl.Estimate(y, assumeSorted: assumeSorted);
    if (spreadY <= 0)
      throw AssumptionException.Sparity(Subject.Y);

    var shiftVal = ShiftImpl.Estimate(x, y, [0.5], assumeSorted)[0];
    var avgSpreadVal = (n * spreadX + m * spreadY) / (n + m);

    return shiftVal / avgSpreadVal;
  }
}

Tests

The $\operatorname{Disparity}$ test suite contains 30 test cases (16 original + 12 unsorted + 2 error). Since $\operatorname{Disparity}$ combines $\operatorname{Shift}$ and $\operatorname{AvgSpread}$, unsorted tests verify both components handle sorting correctly.

Demo examples ($n = m = 5$) — from manual introduction, validating properties:

• demo-1: $\mathbf{x} = (0, 3, 6, 9, 12)$, $\mathbf{y} = (0, 2, 4, 6, 8)$, expected output: $0.4$ (base case: $2/5$)
• demo-2: $\mathbf{x} = (5, 8, 11, 14, 17)$, $\mathbf{y} = (5, 7, 9, 11, 13)$ (= demo-1 + 5), expected output: $0.4$ (location invariance)
• demo-3: $\mathbf{x} = (0, 6, 12, 18, 24)$, $\mathbf{y} = (0, 4, 8, 12, 16)$ (= 2 × demo-1), expected output: $0.4$ (scale invariance)
• demo-4: $\mathbf{x} = (0, 2, 4, 6, 8)$, $\mathbf{y} = (0, 3, 6, 9, 12)$ (= reversed demo-1), expected output: $-0.4$ (anti-symmetry)

Natural sequences ($[n, m] in {2, 3} \times {2, 3}$) — 4 combinations:

• natural-2-2, natural-2-3, natural-3-2, natural-3-3
• Minimum size $n, m \geq 2$ required for meaningful dispersion calculations

Negative values ($[n, m] = [2, 2]$) — end-to-end validation with negative values:

• negative-2-2: $\mathbf{x} = (-2, -1)$, $\mathbf{y} = (-2, -1)$, expected output: $0$

Uniform distribution ($[n, m] in {5, 100} \times {5, 100}$) — 4 combinations with $\underline{\operatorname{Uniform}}(0, 1)$:

• uniform-5-5, uniform-5-100, uniform-100-5, uniform-100-100
• Random generation: $\mathbf{x}$ uses seed 0, $\mathbf{y}$ uses seed 1

The smaller test set for $\operatorname{Disparity}$ reflects implementation confidence. Since $\operatorname{Disparity}$ combines $\operatorname{Shift}$ and $\operatorname{AvgSpread}$, correct implementation of those components ensures $\operatorname{Disparity}$ correctness. The test cases validate the division operation and confirm scale-free properties.

Composite estimator stress tests — edge cases for effect size calculation:

• composite-small-avgspread: $\mathbf{x} = (10.001, 10.002, 10.003)$, $\mathbf{y} = (10.004, 10.005, 10.006)$ (tiny spread, large shift)
• composite-large-avgspread: $\mathbf{x} = (1, 100, 200)$, $\mathbf{y} = (50, 150, 250)$ (large spread, small shift)
• composite-extreme-disparity: $\mathbf{x} = (1, 1.001)$, $\mathbf{y} = (100, 100.001)$ (extreme ratio, tests precision)

Unsorted tests — verify both Shift and AvgSpread handle sorting (12 tests):

• unsorted-x-natural-{n}-{m} for $(n,m) in {(3,3), (4,4)}$: X unsorted (reversed), Y sorted (2 tests)
• unsorted-y-natural-{n}-{m} for $(n,m) in {(3,3), (4,4)}$: X sorted, Y unsorted (reversed) (2 tests)
• unsorted-both-natural-{n}-{m} for $(n,m) in {(3,3), (4,4)}$: both unsorted (reversed) (2 tests)
• unsorted-demo-unsorted-x: $\mathbf{x} = (12, 0, 6, 3, 9)$, $\mathbf{y} = (0, 2, 4, 6, 8)$ (demo-1 with X unsorted)
• unsorted-demo-unsorted-y: $\mathbf{x} = (0, 3, 6, 9, 12)$, $\mathbf{y} = (8, 0, 4, 2, 6)$ (demo-1 with Y unsorted)
• unsorted-demo-both-unsorted: $\mathbf{x} = (9, 0, 12, 3, 6)$, $\mathbf{y} = (6, 0, 8, 2, 4)$ (demo-1 both unsorted)
• unsorted-location-invariance-unsorted: $\mathbf{x} = (17, 5, 11, 8, 14)$, $\mathbf{y} = (13, 5, 9, 7, 11)$ (demo-2 unsorted)
• unsorted-scale-invariance-unsorted: $\mathbf{x} = (24, 0, 12, 6, 18)$, $\mathbf{y} = (16, 0, 8, 4, 12)$ (demo-3 unsorted)
• unsorted-anti-symmetry-unsorted: $\mathbf{x} = (8, 0, 4, 2, 6)$, $\mathbf{y} = (12, 0, 6, 3, 9)$ (demo-4 reversed and unsorted)

As a composite estimator, $\operatorname{Disparity}$ tests both the numerator ($\operatorname{Shift}$) and denominator ($\operatorname{AvgSpread}$). Unsorted variants verify end-to-end correctness including invariance properties.

Error cases — input validation (2 tests):

• error-empty-x: $\mathbf{x} = ()$, $\mathbf{y} = (1, 2, 3, 4, 5)$ — empty X array violates validity
• error-empty-y: $\mathbf{x} = (1, 2, 3, 4, 5)$, $\mathbf{y} = ()$ — empty Y array violates validity

References