Adding confidenceInterval() method for computing confidence intervals

Author: roberto-butti

CHANGELOG.md

@@ -1,6 +1,7 @@
 # Changelog
 
 ## 1.3.1 - WIP
+- Adding `confidenceInterval()` method for computing confidence intervals for the mean using the normal (z) distribution
 - Adding `rSquared()` method for R² (coefficient of determination) — proportion of variance explained by linear regression
 
 ## 1.3.0 - 2026-02-22

README.md

@@ -99,6 +99,7 @@ The various mathematical statistics are listed below:
 | `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 |
+| `confidenceInterval()` | confidence interval for the mean using the normal (z) distribution |
 | `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 |
 
@@ -624,6 +625,54 @@ list($slope, $intercept) = Stat::linearRegression(
 // $intercept = 0.0
 ```
 
+#### Stat::rSquared( array $x, array $y, bool $proportional = false, ?int $round = null )
+Return the coefficient of determination (R²) — the proportion of variance in the dependent variable explained by the linear regression model. Values range from 0 (no explanatory power) to 1 (perfect fit).
+
+Requires at least 2 data points and arrays of the same length.
+
+```php
+use HiFolks\Statistics\Stat;
+$r2 = Stat::rSquared([1, 2, 3, 4, 5], [2, 4, 6, 8, 10]);
+// 1.0 (perfect linear relationship)
+
+$r2 = Stat::rSquared(
+    [1971, 1975, 1979, 1982, 1983],
+    [1, 2, 3, 4, 5],
+    round: 2,
+);
+// 0.96
+```
+
+With proportional regression (through the origin):
+
+```php
+$r2 = Stat::rSquared(
+    [1, 2, 3, 4, 5],
+    [2, 4, 6, 8, 10],
+    proportional: true,
+);
+// 1.0
+```
+
+#### Stat::confidenceInterval( array $data, float $confidenceLevel = 0.95, ?int $round = null )
+Return the confidence interval for the mean using the normal (z) distribution.
+
+Computes: `mean ± z * (stdev / √n)`, where the z-critical value is derived from the inverse normal CDF.
+
+Requires at least 2 data points. The confidence level must be between 0 and 1 exclusive.
+
+```php
+use HiFolks\Statistics\Stat;
+[$lower, $upper] = Stat::confidenceInterval([2, 4, 4, 4, 5, 5, 7, 9]);
+// 95% CI: [3.52, 6.48] (approximately)
+
+[$lower, $upper] = Stat::confidenceInterval([2, 4, 4, 4, 5, 5, 7, 9], confidenceLevel: 0.99);
+// 99% CI: wider interval
+
+[$lower, $upper] = Stat::confidenceInterval([2, 4, 4, 4, 5, 5, 7, 9], round: 2);
+// [3.52, 6.48]
+```
+
 #### Stat::kde ( array $data , float $h , KdeKernel $kernel = KdeKernel::Normal , bool $cumulative = false )
 Create a continuous probability density function (or cumulative distribution function) from discrete sample data using Kernel Density Estimation.
 Returns a `Closure` that can be called with any point to estimate the density (or CDF value).

TODO.md

@@ -15,7 +15,6 @@
 - Chi-squared test
 - Z-test
 - P-value calculation
-- Confidence intervals
 
 ### Other Distributions (beyond Normal)
 

src/Stat.php

@@ -4,6 +4,7 @@
 
 use HiFolks\Statistics\Enums\KdeKernel;
 use HiFolks\Statistics\Exception\InvalidDataInputException;
+use HiFolks\Statistics\NormalDist;
 
 class Stat
 {
@@ -1734,4 +1735,49 @@ public static function rSquared(array $x, array $y, bool $proportional = false,
 
         return $rSquared;
     }
+
+    /**
+     * Return the confidence interval for the mean using the normal (z) distribution.
+     *
+     * Computes: mean ± z * (stdev / √n)
+     *
+     * @param  array<int|float>  $data
+     * @param  float  $confidenceLevel the confidence level (e.g. 0.95 for 95%)
+     * @param  int|null  $round whether to round the result
+     * @return array{0: float, 1: float} [lower bound, upper bound]
+     *
+     * @throws InvalidDataInputException if data has fewer than 2 elements or confidence level is not in (0, 1)
+     */
+    public static function confidenceInterval(
+        array $data,
+        float $confidenceLevel = 0.95,
+        ?int $round = null,
+    ): array {
+        if (self::count($data) < 2) {
+            throw new InvalidDataInputException(
+                "Confidence interval requires at least 2 data points.",
+            );
+        }
+
+        if ($confidenceLevel <= 0.0 || $confidenceLevel >= 1.0) {
+            throw new InvalidDataInputException(
+                "Confidence level must be between 0 and 1 exclusive.",
+            );
+        }
+
+        $mean = self::mean($data);
+        $standardError = self::sem($data);
+
+        $zCritical = (new NormalDist(0.0, 1.0))->invCdf((1 + $confidenceLevel) / 2);
+        $margin = $zCritical * $standardError;
+
+        $lower = $mean - $margin;
+        $upper = $mean + $margin;
+
+        if ($round !== null) {
+            return [Math::round($lower, $round), Math::round($upper, $round)];
+        }
+
+        return [$lower, $upper];
+    }
 }

src/Statistics.php

@@ -273,6 +273,20 @@ public function sem(?int $round = null): float
         return Stat::sem($this->numericalArray(), $round);
     }
 
+    /**
+     * Return the confidence interval for the mean using the normal (z) distribution.
+     *
+     * @param  float  $confidenceLevel the confidence level (e.g. 0.95 for 95%)
+     * @param  int|null  $round whether to round the result
+     * @return array{0: float, 1: float} [lower bound, upper bound]
+     *
+     * @see Stat::confidenceInterval()
+     */
+    public function confidenceInterval(float $confidenceLevel = 0.95, ?int $round = null): array
+    {
+        return Stat::confidenceInterval($this->numericalArray(), $confidenceLevel, $round);
+    }
+
     /**
      * Return the mean absolute deviation (MAD).
      *

tests/StatTest.php

@@ -785,6 +785,82 @@ public function test_r_squared_with_constant_y(): void
         Stat::rSquared([1, 2, 3, 4, 5], [3, 3, 3, 3, 3]);
     }
 
+    public function test_confidence_interval_95(): void
+    {
+        $data = [2, 4, 4, 4, 5, 5, 7, 9];
+        [$lower, $upper] = Stat::confidenceInterval($data);
+        // mean = 5.0, stdev ≈ 2.1381, sem ≈ 0.7559, z = 1.96
+        // margin ≈ 1.4815
+        $this->assertEqualsWithDelta(3.5185, $lower, 0.01);
+        $this->assertEqualsWithDelta(6.4815, $upper, 0.01);
+    }
+
+    public function test_confidence_interval_99(): void
+    {
+        $data = [2, 4, 4, 4, 5, 5, 7, 9];
+        [$lower, $upper] = Stat::confidenceInterval($data, confidenceLevel: 0.99);
+        // 99% CI is wider than 95% CI
+        $this->assertLessThan(3.5, $lower);
+        $this->assertGreaterThan(6.5, $upper);
+    }
+
+    public function test_confidence_interval_with_rounding(): void
+    {
+        $data = [2, 4, 4, 4, 5, 5, 7, 9];
+        [$lower, $upper] = Stat::confidenceInterval($data, round: 2);
+        $this->assertSame(3.52, $lower);
+        $this->assertSame(6.48, $upper);
+    }
+
+    public function test_confidence_interval_narrows_with_more_data(): void
+    {
+        $small = [2, 4, 4, 4, 5, 5, 7, 9];
+        $large = [2, 4, 4, 4, 5, 5, 7, 9, 3, 4, 5, 6, 4, 5, 6, 5];
+        [$sLower, $sUpper] = Stat::confidenceInterval($small);
+        [$lLower, $lUpper] = Stat::confidenceInterval($large);
+        $this->assertLessThan($sUpper - $sLower, $lUpper - $lLower);
+    }
+
+    public function test_confidence_interval_single_element_throws(): void
+    {
+        $this->expectException(InvalidDataInputException::class);
+        Stat::confidenceInterval([42]);
+    }
+
+    public function test_confidence_interval_empty_throws(): void
+    {
+        $this->expectException(InvalidDataInputException::class);
+        Stat::confidenceInterval([]);
+    }
+
+    public function test_confidence_interval_invalid_confidence_level_throws(): void
+    {
+        $data = [1, 2, 3, 4, 5];
+        $this->expectException(InvalidDataInputException::class);
+        Stat::confidenceInterval($data, confidenceLevel: 0.0);
+    }
+
+    public function test_confidence_interval_confidence_level_one_throws(): void
+    {
+        $data = [1, 2, 3, 4, 5];
+        $this->expectException(InvalidDataInputException::class);
+        Stat::confidenceInterval($data, confidenceLevel: 1.0);
+    }
+
+    public function test_confidence_interval_confidence_level_above_one_throws(): void
+    {
+        $data = [1, 2, 3, 4, 5];
+        $this->expectException(InvalidDataInputException::class);
+        Stat::confidenceInterval($data, confidenceLevel: 1.5);
+    }
+
+    public function test_confidence_interval_negative_confidence_level_throws(): void
+    {
+        $data = [1, 2, 3, 4, 5];
+        $this->expectException(InvalidDataInputException::class);
+        Stat::confidenceInterval($data, confidenceLevel: -0.1);
+    }
+
     public function test_kde_normal(): void
     {
         $data = [-2.1, -1.3, -0.4, 1.9, 5.1, 6.2];

tests/StatisticTest.php

@@ -305,6 +305,24 @@ public function test_sem(): void
         $this->assertEqualsWithDelta($expected, $s->sem(), 1e-10);
     }
 
+    public function test_confidence_interval(): void
+    {
+        $s = Statistics::make([2, 4, 4, 4, 5, 5, 7, 9]);
+        [$lower, $upper] = $s->confidenceInterval();
+        [$expectedLower, $expectedUpper] = Stat::confidenceInterval([2, 4, 4, 4, 5, 5, 7, 9]);
+        $this->assertEqualsWithDelta($expectedLower, $lower, 1e-10);
+        $this->assertEqualsWithDelta($expectedUpper, $upper, 1e-10);
+    }
+
+    public function test_confidence_interval_with_params(): void
+    {
+        $s = Statistics::make([2, 4, 4, 4, 5, 5, 7, 9]);
+        [$lower, $upper] = $s->confidenceInterval(confidenceLevel: 0.99, round: 2);
+        [$expectedLower, $expectedUpper] = Stat::confidenceInterval([2, 4, 4, 4, 5, 5, 7, 9], confidenceLevel: 0.99, round: 2);
+        $this->assertSame($expectedLower, $lower);
+        $this->assertSame($expectedUpper, $upper);
+    }
+
     public function test_mean_absolute_deviation(): void
     {
         $s = Statistics::make([1, 2, 3, 4, 5]);