Adding kendallTau() method for Kendall tau-b rank correlation with tie handling

Author: roberto-butti

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 1.5.2 - WIP
+- Adding `kendallTau()` method for Kendall tau-b rank correlation with tie handling
+- Adding `kendall` method support to `correlation()`
+
 ## 1.5.1 - 2026-05-12
 - Adding `rank()` method for assigning 1-based ranks to data points, with support for `average`, `min`, `max`, `dense`, and `ordinal` tie strategies
 - Adding `percentileRank()` method for calculating the percentile position of a value, with `weak`, `strict`, `mean`, and `rank` variants

README.md

@@ -97,7 +97,8 @@ The various mathematical statistics are listed below:
 | `iqrOutliers()` | outlier detection based on IQR method (box plot whiskers), robust for skewed data |
 | `geometricMean()` | geometric mean |
 | `harmonicMean()` | harmonic mean |
-| `correlation()` | Pearson’s or Spearman’s rank correlation coefficient for two inputs |
+| `correlation()` | Pearson’s, Spearman’s rank, or Kendall tau correlation coefficient for two inputs |
+| `kendallTau()` | Kendall tau-b rank correlation coefficient for ordinal association with tie handling |
 | `covariance()` | the sample covariance of two inputs |
 | `linearRegression()` | return the slope and intercept of simple linear regression parameters estimated using ordinary least squares (supports `proportional: true` for regression through the origin) |
 | `logarithmicRegression()` | logarithmic regression — fits `y = a × ln(x) + b`, ideal for diminishing returns patterns (e.g., athletic improvement, learning curves) |
@@ -609,10 +610,12 @@ $covariance = Stat::covariance(
 // -7.5
 ```
 
-#### Stat::correlation ( array $x , array $y, string $method = ‘linear’ )
+#### Stat::correlation ( array $x , array $y, string $method = 'linear' )
 Return the Pearson’s correlation coefficient for two inputs. Pearson’s correlation coefficient r takes values between -1 and +1. It measures the strength and direction of the linear relationship, where +1 means very strong, positive linear relationship, -1 very strong, negative linear relationship, and 0 no linear relationship.
 
-Use `$method = ‘ranked’` for Spearman’s rank correlation, which measures monotonic relationships (not just linear). Spearman’s correlation is computed by applying Pearson’s formula to the ranks of the data.
+Use `$method = 'ranked'` for Spearman’s rank correlation, which measures monotonic relationships (not just linear). Spearman’s correlation is computed by applying Pearson’s formula to the ranks of the data.
+
+Use `$method = 'kendall'` for Kendall tau-b correlation, which measures ordinal association by comparing concordant and discordant pairs. Kendall tau-b is often useful for ordinal data, small samples, and datasets with ties.
 
 ```php
 $correlation = Stat::correlation(
@@ -635,11 +638,33 @@ Spearman’s rank correlation (non-linear but monotonic relationship):
 $correlation = Stat::correlation(
     [1, 2, 3, 4, 5],
     [1, 4, 9, 16, 25],
-    ‘ranked’
+    'ranked'
 );
 // 1.0
 ```
 
+Kendall tau-b rank correlation with ties:
+```php
+$correlation = Stat::correlation(
+    [12, 2, 1, 12, 2],
+    [1, 4, 7, 1, 0],
+    'kendall'
+);
+// -0.47140452079103173
+```
+
+#### Stat::kendallTau ( array $x , array $y, ?int $round = null )
+Return Kendall's tau-b rank correlation coefficient for two inputs.
+
+```php
+$correlation = Stat::kendallTau(
+    [12, 2, 1, 12, 2],
+    [1, 4, 7, 1, 0],
+    4
+);
+// -0.4714
+```
+
 #### Stat::linearRegression ( array $x , array $y , bool $proportional = false )
 Return the slope and intercept of simple linear regression  parameters estimated using ordinary least squares.
 Simple linear regression describes the relationship between an independent variable *$x* and a dependent variable *$y* in terms of a linear function.

TODO.md

@@ -9,10 +9,9 @@
 
 ### Priority 2: Correlation
 
-- `kendallTau()` - Kendall tau rank correlation.
-  - Useful for ordinal data and small samples.
-  - Complements the existing Pearson and Spearman support in `correlation()`.
-- Consider extending `correlation()` with a Kendall method option.
+- DONE: `kendallTau()` - Kendall tau-b rank correlation.
+  - Useful for ordinal data, small samples, and datasets with ties.
+- DONE: Extend `correlation()` with a Kendall method option.
 
 ### Priority 3: Hypothesis Testing
 

examples/article-boston-marathon-analysis.php

@@ -199,11 +199,13 @@
 
 $pearson = Stat::correlation($ages, $finishTimes);
 $spearman = Stat::correlation($ages, $finishTimes, 'ranked');
+$kendall = Stat::correlation($ages, $finishTimes, 'kendall');
 $regression = Stat::linearRegression($ages, $finishTimes);
 $r2 = Stat::rSquared($ages, $finishTimes, false, 4);
 
 echo "Pearson correlation:  " . round($pearson, 4) . PHP_EOL;
 echo "Spearman correlation: " . round($spearman, 4) . PHP_EOL;
+echo "Kendall tau:          " . round($kendall, 4) . PHP_EOL;
 echo PHP_EOL;
 echo "Linear regression:    finish = " . round($regression[0], 1) . " × age + " . round($regression[1]) . PHP_EOL;
 echo "R-squared:            " . $r2 . PHP_EOL;
@@ -212,6 +214,7 @@
 echo "How to interpret:" . PHP_EOL;
 echo "- Pearson and Spearman close to +1 = strong positive relationship (older = slower)." . PHP_EOL;
 echo "- If both correlations are similar, the relationship is linear, not just monotonic." . PHP_EOL;
+echo "- Kendall tau is stricter and useful for rank agreement, especially with ties." . PHP_EOL;
 echo "- The slope tells you seconds added per year of age. Divide by 60 for minutes." . PHP_EOL;
 echo "- R-squared tells you what fraction of variation age explains (0 = none, 1 = all)." . PHP_EOL;
 
@@ -458,6 +461,7 @@
     ['Stat::tTestPaired()', '3'],
     ['Stat::correlation() — Pearson', '4'],
     ['Stat::correlation() — Spearman', '4'],
+    ['Stat::correlation() — Kendall', '4'],
     ['Stat::linearRegression()', '4'],
     ['Stat::rSquared()', '4'],
     ['Stat::coefficientOfVariation()', '5'],

examples/stat_methods.php

@@ -34,6 +34,10 @@
 // 60.0
 $percentileRank = Stat::percentileRank([10, 20, 20, 30, 40], 20, Stat::PERCENTILE_RANK_STRICT);
 // 20.0
+$correlation = Stat::kendallTau([12, 2, 1, 12, 2], [1, 4, 7, 1, 0], 4);
+// -0.4714
+$correlation = Stat::correlation([12, 2, 1, 12, 2], [1, 4, 7, 1, 0], 'kendall');
+// -0.47140452079103173
 $quantiles = Stat::quantiles([98, 90, 70, 18, 92, 92, 55, 83, 45, 95, 88]);
 // [ 55.0, 88.0, 92.0 ]
 $quantiles = Stat::quantiles([105, 129, 87, 86, 111, 111, 89, 81, 108, 92, 110, 100, 75, 105, 103, 109, 76, 119, 99, 91, 103, 129, 106, 101, 84, 111, 74, 87, 86, 103, 103, 106, 86, 111, 75, 87, 102, 121, 111, 88, 89, 101, 106, 95, 103, 107, 101, 81, 109, 104], 10);

src/Stat.php

@@ -1257,8 +1257,8 @@ public static function harmonicMean(
      * Return the sample covariance of two inputs *$x* and *$y*.
      * Covariance is a measure of the joint variability of two inputs.
      *
-     * @param  array<int|float>  $x
-     * @param  array<int|float>  $y
+     * @param  array<mixed>  $x
+     * @param  array<mixed>  $y
      *
      * @throws InvalidDataInputException if 2 arrays have different size,
      * or if the length of arrays are < 2, or if the 2 input arrays has not numeric elements
@@ -1311,8 +1311,8 @@ public static function covariance(array $x, array $y): false|float
      * -1 very strong, negative linear relationship,
      * and 0 no linear relationship.
      *
-     * @param  array<int|float>  $x
-     * @param  array<int|float>  $y
+     * @param  array<mixed>  $x
+     * @param  array<mixed>  $y
      *
      * @throws InvalidDataInputException if 2 arrays have different size,
      * or if the length of arrays are < 2, or if the 2 input arrays has not numeric elements,
@@ -1323,9 +1323,9 @@ public static function correlation(
         array $y,
         string $method = "linear",
     ): false|float {
-        if ($method !== "linear" && $method !== "ranked") {
+        if (!in_array($method, ["linear", "ranked", "kendall"], true)) {
             throw new InvalidDataInputException(
-                "Correlation method must be 'linear' or 'ranked'.",
+                "Correlation method must be 'linear', 'ranked', or 'kendall'.",
             );
         }
 
@@ -1346,6 +1346,9 @@ public static function correlation(
             $x = self::ranks($x);
             $y = self::ranks($y);
         }
+        if ($method === "kendall") {
+            return self::kendallTau($x, $y);
+        }
 
         $meanX = self::mean($x);
         $meanY = self::mean($y);
@@ -1370,6 +1373,87 @@ public static function correlation(
         return $a / $b;
     }
 
+    /**
+     * Return Kendall's tau-b rank correlation coefficient for two inputs.
+     *
+     * Kendall's tau measures ordinal association by comparing concordant and
+     * discordant pairs. The tau-b variant adjusts for ties in either input.
+     *
+     * @param  array<mixed>  $x
+     * @param  array<mixed>  $y
+     * @param  int|null  $round whether to round the result
+     *
+     * @throws InvalidDataInputException if inputs have different sizes, fewer than 2 data points,
+     * or non-numeric/constant data
+     */
+    public static function kendallTau(array $x, array $y, ?int $round = null): float
+    {
+        $countX = count($x);
+        $countY = count($y);
+        if ($countX !== $countY) {
+            throw new InvalidDataInputException(
+                "Kendall tau requires that both inputs have same number of data points.",
+            );
+        }
+        if ($countX < 2) {
+            throw new InvalidDataInputException(
+                "Kendall tau requires at least two data points.",
+            );
+        }
+
+        $concordant = 0;
+        $discordant = 0;
+        $tiesX = 0;
+        $tiesY = 0;
+
+        for ($i = 0; $i < $countX - 1; $i++) {
+            if (!is_numeric($x[$i]) || !is_numeric($y[$i])) {
+                throw new InvalidDataInputException(
+                    "Kendall tau requires numeric data points.",
+                );
+            }
+            for ($j = $i + 1; $j < $countX; $j++) {
+                if (!is_numeric($x[$j]) || !is_numeric($y[$j])) {
+                    throw new InvalidDataInputException(
+                        "Kendall tau requires numeric data points.",
+                    );
+                }
+
+                $xComparison = $x[$i] <=> $x[$j];
+                $yComparison = $y[$i] <=> $y[$j];
+
+                if ($xComparison === 0 && $yComparison === 0) {
+                    continue;
+                }
+                if ($xComparison === 0) {
+                    $tiesX++;
+                    continue;
+                }
+                if ($yComparison === 0) {
+                    $tiesY++;
+                    continue;
+                }
+                if ($xComparison === $yComparison) {
+                    $concordant++;
+                    continue;
+                }
+                $discordant++;
+            }
+        }
+
+        $denominator = sqrt(
+            ($concordant + $discordant + $tiesX)
+            * ($concordant + $discordant + $tiesY),
+        );
+        if ($denominator == 0) {
+            throw new InvalidDataInputException(
+                "Kendall tau, at least one of the inputs is constant.",
+            );
+        }
+
+        return Math::round(($concordant - $discordant) / $denominator, $round);
+    }
+
     /**
      * Assign average ranks to data values (handles ties by averaging).
      *

tests/StatTest.php

@@ -522,14 +522,14 @@ public function test_calculates_covariance_with_non_numeric_first(): void
     {
         $this->expectException(InvalidDataInputException::class);
         // Intentionally passing non-numeric values to test exception handling
-        Stat::covariance(['a', 1], ['b', 2]); // @phpstan-ignore argument.type, argument.type
+        Stat::covariance(['a', 1], ['b', 2]);
     }
 
     public function test_calculates_covariance_with_non_numeric_second(): void
     {
         $this->expectException(InvalidDataInputException::class);
         // Intentionally passing non-numeric values to test exception handling
-        Stat::covariance([3, 1], ['b', 2]); // @phpstan-ignore argument.type
+        Stat::covariance([3, 1], ['b', 2]);
     }
 
     public function test_calculates_correlation(): void
@@ -629,6 +629,87 @@ public function test_calculates_spearman_correlation_with_ties(): void
         $this->assertEqualsWithDelta(1.0, $correlation, 1e-9);
     }
 
+    public function test_calculates_kendall_tau(): void
+    {
+        $this->assertEqualsWithDelta(
+            1.0,
+            Stat::kendallTau([1, 2, 3, 4], [10, 20, 30, 40]),
+            1e-9,
+        );
+        $this->assertEqualsWithDelta(
+            -1.0,
+            Stat::kendallTau([1, 2, 3, 4], [40, 30, 20, 10]),
+            1e-9,
+        );
+    }
+
+    public function test_calculates_kendall_tau_with_ties(): void
+    {
+        $tau = Stat::kendallTau([12, 2, 1, 12, 2], [1, 4, 7, 1, 0]);
+
+        $this->assertEqualsWithDelta(-0.47140452079103173, $tau, 1e-12);
+    }
+
+    public function test_calculates_kendall_tau_with_ties_in_y_only(): void
+    {
+        $tau = Stat::kendallTau([1, 2, 3], [1, 1, 2]);
+
+        $this->assertEqualsWithDelta(0.8164965809277261, $tau, 1e-12);
+    }
+
+    public function test_calculates_kendall_tau_with_rounding(): void
+    {
+        $tau = Stat::kendallTau([12, 2, 1, 12, 2], [1, 4, 7, 1, 0], 4);
+
+        $this->assertSame(-0.4714, $tau);
+    }
+
+    public function test_calculates_correlation_with_kendall_method(): void
+    {
+        $correlation = Stat::correlation(
+            [12, 2, 1, 12, 2],
+            [1, 4, 7, 1, 0],
+            'kendall',
+        );
+
+        $this->assertEqualsWithDelta(-0.47140452079103173, $correlation, 1e-12);
+    }
+
+    public function test_calculates_kendall_tau_wrong_usage_different_lengths(): void
+    {
+        $this->expectException(InvalidDataInputException::class);
+
+        Stat::kendallTau([1, 2], [1, 2, 3]);
+    }
+
+    public function test_calculates_kendall_tau_wrong_usage_empty(): void
+    {
+        $this->expectException(InvalidDataInputException::class);
+
+        Stat::kendallTau([], []);
+    }
+
+    public function test_calculates_kendall_tau_wrong_usage_constant(): void
+    {
+        $this->expectException(InvalidDataInputException::class);
+
+        Stat::kendallTau([1, 1, 1], [1, 2, 3]);
+    }
+
+    public function test_calculates_kendall_tau_with_non_numeric_data(): void
+    {
+        $this->expectException(InvalidDataInputException::class);
+
+        Stat::kendallTau([1, 'a', 3], [1, 2, 3]);
+    }
+
+    public function test_calculates_kendall_tau_with_non_numeric_first_pair(): void
+    {
+        $this->expectException(InvalidDataInputException::class);
+
+        Stat::kendallTau(['a', 1, 3], [1, 2, 3]);
+    }
+
     public function test_calculates_correlation_invalid_method(): void
     {
         $this->expectException(InvalidDataInputException::class);
@@ -1493,13 +1574,13 @@ public function test_covariance_non_numeric_x_throws(): void
         $this->expectException(InvalidDataInputException::class);
         // true passes mean()'s string filter and array_sum without warnings,
         // but is_numeric(true) returns false, triggering the loop guard
-        Stat::covariance([true, 1, 2], [3, 4, 5]); // @phpstan-ignore argument.type
+        Stat::covariance([true, 1, 2], [3, 4, 5]);
     }
 
     public function test_covariance_non_numeric_y_throws(): void
     {
         $this->expectException(InvalidDataInputException::class);
-        Stat::covariance([1, 2, 3], [true, 4, 5]); // @phpstan-ignore argument.type
+        Stat::covariance([1, 2, 3], [true, 4, 5]);
     }
 
     public function test_kde_cumulative_bounded_kernels(): void