Adding rSquared() method for R² (coefficient of determination)

Author: roberto-butti

CHANGELOG.md

@@ -1,5 +1,8 @@
 # Changelog
 
+## 1.3.1 - WIP
+- Adding `rSquared()` method for R² (coefficient of determination) — proportion of variance explained by linear regression
+
 ## 1.3.0 - 2026-02-22
 - Adding `StreamingStat` class (experimental) for streaming/online computation of mean, variance, stdev, skewness, kurtosis, sum, min, and max with O(1) memory
 - Adding `percentile()` method for computing the value at any percentile (0–100) with linear interpolation
@@ -12,6 +15,7 @@
 - Adding `zscores()` method for computing z-scores of each value in a dataset
 - Adding `outliers()` method for z-score based outlier detection with configurable threshold
 - Adding `iqrOutliers()` method for IQR-based outlier detection (box plot whiskers), robust for skewed data
+- Adding `rSquared()` method for R² (coefficient of determination) — proportion of variance explained by linear regression
 
 ## 1.2.5 - 2026-02-22
 - Adding `kurtosis()` method for excess kurtosis

README.md

@@ -98,6 +98,7 @@ The various mathematical statistics are listed below:
 | `correlation()` | Pearson’s or Spearman’s rank correlation coefficient for two inputs |
 | `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) |
+| `rSquared()` | coefficient of determination (R²) — proportion of variance explained by linear regression |
 | `kde()` | kernel density estimation — returns a closure that estimates the probability density (or CDF) at any point |
 | `kdeRandom()` | random sampling from a kernel density estimate — returns a closure that generates random floats from the KDE distribution |
 

TODO.md

@@ -8,7 +8,6 @@
 
 - Kendall tau correlation - another rank-based correlation
 - Multiple/polynomial regression
-- R-squared (coefficient of determination)
 
 ### Hypothesis Testing
 

src/Stat.php

@@ -1680,4 +1680,58 @@ public static function linearRegression(
 
         return [$slope, $intercept];
     }
+
+    /**
+     * Calculate the coefficient of determination (R²).
+     *
+     * R² measures the proportion of variance in y explained by the
+     * linear regression on x. Returns a value between 0 and 1.
+     *
+     * @param  array<int|float>  $x
+     * @param  array<int|float>  $y
+     * @throws InvalidDataInputException
+     */
+    public static function rSquared(array $x, array $y, bool $proportional = false, ?int $round = null): float
+    {
+        $countX = count($x);
+        $countY = count($y);
+
+        if ($countX !== $countY) {
+            throw new InvalidDataInputException(
+                "R-squared requires x and y arrays of the same length.",
+            );
+        }
+
+        if ($countX < 2) {
+            throw new InvalidDataInputException(
+                "R-squared requires at least 2 data points.",
+            );
+        }
+
+        [$slope, $intercept] = self::linearRegression($x, $y, $proportional);
+        $meanY = self::mean($y);
+
+        $ssRes = 0.0;
+        $ssTot = 0.0;
+
+        foreach ($y as $key => $yi) {
+            $predicted = $slope * $x[$key] + $intercept;
+            $ssRes += ($yi - $predicted) ** 2;
+            $ssTot += ($yi - $meanY) ** 2;
+        }
+
+        if ($ssTot == 0) {
+            throw new InvalidDataInputException(
+                "R-squared is undefined when y values are constant (zero variance).",
+            );
+        }
+
+        $rSquared = 1 - $ssRes / $ssTot;
+
+        if ($round !== null) {
+            return round($rSquared, $round);
+        }
+
+        return $rSquared;
+    }
 }

tests/StatTest.php

@@ -732,6 +732,59 @@ public function test_proportional_linear_regression_with_all_zeros_x(): void
         Stat::linearRegression([0, 0, 0, 0, 0], [1, 2, 3, 4, 5], proportional: true);
     }
 
+    public function test_r_squared_perfect_fit(): void
+    {
+        $r2 = Stat::rSquared([1, 2, 3, 4, 5], [2, 4, 6, 8, 10]);
+        $this->assertEqualsWithDelta(1.0, $r2, 1e-10);
+    }
+
+    public function test_r_squared_real_data(): void
+    {
+        $r2 = Stat::rSquared(
+            [1971, 1975, 1979, 1982, 1983],
+            [1, 2, 3, 4, 5],
+        );
+        $this->assertEqualsWithDelta(0.961, round($r2, 4), 1e-4);
+    }
+
+    public function test_r_squared_with_rounding(): void
+    {
+        $r2 = Stat::rSquared(
+            [1971, 1975, 1979, 1982, 1983],
+            [1, 2, 3, 4, 5],
+            round: 2,
+        );
+        $this->assertSame(0.96, $r2);
+    }
+
+    public function test_r_squared_proportional(): void
+    {
+        $r2 = Stat::rSquared(
+            [1, 2, 3, 4, 5],
+            [2, 4, 6, 8, 10],
+            proportional: true,
+        );
+        $this->assertEqualsWithDelta(1.0, $r2, 1e-10);
+    }
+
+    public function test_r_squared_with_different_lengths(): void
+    {
+        $this->expectException(InvalidDataInputException::class);
+        Stat::rSquared([1, 2, 3], [1, 2]);
+    }
+
+    public function test_r_squared_with_single_element(): void
+    {
+        $this->expectException(InvalidDataInputException::class);
+        Stat::rSquared([1], [2]);
+    }
+
+    public function test_r_squared_with_constant_y(): void
+    {
+        $this->expectException(InvalidDataInputException::class);
+        Stat::rSquared([1, 2, 3, 4, 5], [3, 3, 3, 3, 3]);
+    }
+
     public function test_kde_normal(): void
     {
         $data = [-2.1, -1.3, -0.4, 1.9, 5.1, 6.2];