Adding kurtosis() method for excess kurtosis

Author: roberto-butti

CHANGELOG.md

@@ -1,5 +1,8 @@
 # Changelog
 
+## 1.2.5 - WIP
+- Adding `kurtosis()` method for excess kurtosis
+- 
 ## 1.2.4 - 2026-02-21
 - Adding `skewness()` method for adjusted Fisher-Pearson sample skewness
 - Adding `pskewness()` method for population (biased) skewness

README.md

@@ -79,6 +79,7 @@ The various mathematical statistics are listed below:
 | `variance()` | variance for a sample (supports pre-computed mean via `xbar`) |
 | `skewness()` | adjusted Fisher-Pearson sample skewness |
 | `pskewness()` | population (biased) skewness |
+| `kurtosis()` | excess kurtosis (sample formula, 0 for normal distribution) |
 | `geometricMean()` | geometric mean |
 | `harmonicMean()` | harmonic mean |
 | `correlation()` | Pearson’s or Spearman’s rank correlation coefficient for two inputs |
@@ -342,6 +343,22 @@ use HiFolks\Statistics\Stat;
 $pskewness = Stat::pskewness([1, 1, 1, 1, 1, 10]);
 ```
 
+#### Stat::kurtosis ( array $data, ?int $round = null )
+Kurtosis measures the "tailedness" of a distribution — how much data lives in the extreme tails compared to a normal distribution. This method returns the **excess kurtosis** using the sample formula, which is the same as Excel's `KURT()` and Python's `scipy.stats.kurtosis(bias=False)`.
+
+A normal distribution has excess kurtosis of 0. Positive values (leptokurtic) indicate heavier tails and more outliers. Negative values (platykurtic) indicate lighter tails and fewer outliers.
+
+Requires at least 4 data points.
+
+```php
+use HiFolks\Statistics\Stat;
+$kurtosis = Stat::kurtosis([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
+// negative (platykurtic, lighter tails than normal)
+
+$kurtosis = Stat::kurtosis([1, 2, 2, 2, 2, 2, 2, 2, 2, 50]);
+// positive (leptokurtic, heavier tails due to outlier)
+```
+
 #### Stat::covariance ( array $x , array $y )
 Covariance, static method, returns the sample covariance of two inputs *$x* and *$y*.
 Covariance is a measure of the joint variability of two inputs.

TODO.md

@@ -4,8 +4,6 @@
 
 - Trimmed/Truncated mean - mean after removing outliers (top/bottom x%)
 - Weighted median - median with weights (like fmean supports weights, but median doesn't)
-- Skewness - measure of asymmetry of the distribution
-- Kurtosis - measure of "tailedness" of the distribution
 - Standard error of the mean (SEM)
 - Coefficient of variation (CV) - stdev / mean, useful for comparing variability across datasets
 - Mean absolute deviation (MAD)
@@ -49,4 +47,4 @@
 
 ### Notes
 
-The most impactful additions would likely be skewness, kurtosis, coefficient of variation, percentile, and Spearman correlation — these are commonly needed and align well with the package's existing scope (inspired by Python's statistics module).
+The most impactful additions would likely be (skewness DONE), (kurtosis DONE), coefficient of variation, percentile, and Spearman correlation — these are commonly needed and align well with the package's existing scope (inspired by Python's statistics module).

examples/norm_dist.php

@@ -84,6 +84,9 @@
 echo "Skewness: " . Stat::skewness($times, 4)
     . " (positive = right-skewed, a few slow finishers pull the tail right)"
     . PHP_EOL;
+echo "Kurtosis: " . Stat::kurtosis($times, 4)
+    . " (positive = leptokurtic, heavy tails with outliers)"
+    . PHP_EOL;
 
 // --- Normal Distribution Model ---
 echo PHP_EOL . "=== Normal Distribution Model ===" . PHP_EOL . PHP_EOL;
@@ -193,3 +196,9 @@
         . ")"
         . PHP_EOL;
 }
+
+// --- Distribution Shape ---
+echo PHP_EOL . "=== Distribution Shape ===" . PHP_EOL . PHP_EOL;
+
+echo "Skewness: " . Stat::skewness($times, 4) . PHP_EOL;
+echo "Kurtosis: " . Stat::kurtosis($times, 4) . PHP_EOL;

src/Stat.php

@@ -582,6 +582,49 @@ public static function pskewness(array $data, ?int $round = null): float
         return Math::round($pskewness, $round);
     }
 
+    /**
+     * Return the excess kurtosis of the data using the sample formula.
+     * This is the same formula used by Excel's KURT() and Python's
+     * scipy.stats.kurtosis(bias=False, fisher=True).
+     *
+     * Excess kurtosis measures the "tailedness" of a distribution relative
+     * to a normal distribution. A normal distribution has excess kurtosis 0.
+     * Positive values (leptokurtic) indicate heavier tails and more outliers;
+     * negative values (platykurtic) indicate lighter tails and fewer outliers.
+     *
+     * Formula: [n(n+1) / ((n-1)(n-2)(n-3))] * Σ((xi - x̄) / s)⁴ − [3(n-1)² / ((n-2)(n-3))]
+     *
+     * @param  array<int|float>  $data
+     * @param  int|null  $round whether to round the result
+     * @return float excess kurtosis
+     *
+     * @throws InvalidDataInputException if the data has fewer than 4 elements or all values are identical
+     */
+    public static function kurtosis(array $data, ?int $round = null): float
+    {
+        $n = self::count($data);
+        if ($n < 4) {
+            throw new InvalidDataInputException("Kurtosis requires at least 4 data points.");
+        }
+
+        $mean = self::mean($data);
+        $stdev = self::stdev($data);
+
+        if ($stdev == 0) {
+            throw new InvalidDataInputException("Kurtosis is undefined when all values are identical (standard deviation is zero).");
+        }
+
+        $sumFourth = 0.0;
+        foreach ($data as $xi) {
+            $sumFourth += (($xi - $mean) / $stdev) ** 4;
+        }
+
+        $kurtosis = ($n * ($n + 1)) / (($n - 1) * ($n - 2) * ($n - 3)) * $sumFourth
+            - (3 * ($n - 1) ** 2) / (($n - 2) * ($n - 3));
+
+        return Math::round($kurtosis, $round);
+    }
+
     /**
      * Return the geometric mean of the numeric data.
      * That is the number that can replace each of these numbers so that their product

src/Statistics.php

@@ -295,6 +295,18 @@ public function pskewness(?int $round = null): float
         return Stat::pskewness($this->numericalArray(), $round);
     }
 
+    /**
+     * Return the excess kurtosis (sample formula).
+     *
+     * @param  int|null  $round whether to round the result
+     *
+     * @see Stat::kurtosis()
+     */
+    public function kurtosis(?int $round = null): float
+    {
+        return Stat::kurtosis($this->numericalArray(), $round);
+    }
+
     /**
      * Return the geometric mean of the numeric data.
      *

tests/StatTest.php

@@ -334,6 +334,50 @@ public function test_pskewness_less_than_skewness_for_small_samples(): void
         $this->assertLessThan(abs($skewness), abs($pskewness));
     }
 
+    public function test_calculates_kurtosis_normal_like(): void
+    {
+        // A uniform-ish symmetric dataset: excess kurtosis near 0 or negative
+        $this->assertEqualsWithDelta(-1.2, Stat::kurtosis([1, 2, 3, 4, 5]), 0.1);
+    }
+
+    public function test_calculates_kurtosis_heavy_tails(): void
+    {
+        // Data with outliers should have positive excess kurtosis (leptokurtic)
+        $kurtosis = Stat::kurtosis([1, 2, 2, 2, 2, 2, 2, 2, 2, 50]);
+        $this->assertGreaterThan(0, $kurtosis);
+    }
+
+    public function test_calculates_kurtosis_light_tails(): void
+    {
+        // Uniform-like data should have negative excess kurtosis (platykurtic)
+        $kurtosis = Stat::kurtosis([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
+        $this->assertLessThan(0, $kurtosis);
+    }
+
+    public function test_calculates_kurtosis_with_rounding(): void
+    {
+        $kurtosis = Stat::kurtosis([1, 2, 2, 2, 2, 2, 2, 2, 2, 50], 4);
+        $this->assertEquals(round($kurtosis, 4), $kurtosis);
+    }
+
+    public function test_kurtosis_with_empty_array(): void
+    {
+        $this->expectException(InvalidDataInputException::class);
+        Stat::kurtosis([]);
+    }
+
+    public function test_kurtosis_with_three_elements(): void
+    {
+        $this->expectException(InvalidDataInputException::class);
+        Stat::kurtosis([1, 2, 3]);
+    }
+
+    public function test_kurtosis_with_identical_values(): void
+    {
+        $this->expectException(InvalidDataInputException::class);
+        Stat::kurtosis([5, 5, 5, 5]);
+    }
+
     public function test_calculates_geometric_mean(): void
     {
         $this->assertEquals(36, Stat::geometricMean([54, 24, 36], 2));

tests/StatisticTest.php

@@ -187,6 +187,12 @@ public function test_calculates_pskewness(): void
         $this->assertEqualsWithDelta(0.0, Statistics::make([1, 2, 3, 4, 5])->pskewness(), 1e-10);
     }
 
+    public function test_calculates_kurtosis(): void
+    {
+        // Uniform-like data: negative excess kurtosis
+        $this->assertLessThan(0, Statistics::make([1, 2, 3, 4, 5, 6, 7, 8, 9, 10])->kurtosis());
+    }
+
     public function test_calculates_geometric_mean(): void
     {
         $this->assertEquals(36, Statistics::make([54, 24, 36])->geometricMean(2));