Adding percentile() and coefficientOfVariation()

Author: roberto-butti

CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## 1.3.0 - WIP
 - 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
+- Adding `coefficientOfVariation()` method for relative dispersion (CV%), supporting both sample and population modes
 
 ## 1.2.5 - 2026-02-22
 - Adding `kurtosis()` method for excess kurtosis

README.md

@@ -73,13 +73,15 @@ The various mathematical statistics are listed below:
 | `quantiles()` | cut points dividing the range of a probability distribution into continuous intervals with equal probabilities (supports `exclusive` and `inclusive` methods) |
 | `thirdQuartile()` | 3rd quartile, is the value at which 75 percent of the data is below it |
 | `firstQuartile()` | first quartile, is the value at which 25 percent of the data is below it |
+| `percentile()` | value at any percentile (0–100) with linear interpolation |
 | `pstdev()` | Population standard deviation |
 | `stdev()` | Sample standard deviation |
 | `pvariance()` | variance for a population (supports pre-computed mean via `mu`) |
 | `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) |
+| `coefficientOfVariation()` | coefficient of variation (CV%), relative dispersion as percentage |
 | `geometricMean()` | geometric mean |
 | `harmonicMean()` | harmonic mean |
 | `correlation()` | Pearson’s or Spearman’s rank correlation coefficient for two inputs |
@@ -265,6 +267,20 @@ $percentile = Stat::thirdQuartile([98, 90, 70,18,92,92,55,83,45,95,88]);
 // 92.0
 ```
 
+#### Stat::percentile( array $data, float $p, ?int $round = null )
+Return the value at the given percentile of the data, using linear interpolation between adjacent data points (exclusive method, consistent with `quantiles()`).
+
+The percentile `$p` must be between 0 and 100. Requires at least 2 data points.
+
+```php
+use HiFolks\Statistics\Stat;
+$value = Stat::percentile([10, 20, 30, 40, 50, 60, 70, 80, 90, 100], 50);
+// 55.0 (median)
+
+$value = Stat::percentile([10, 20, 30, 40, 50, 60, 70, 80, 90, 100], 90);
+// 91.0
+```
+
 #### Stat::pstdev( array $data )
 Return the **Population** Standard Deviation, a measure of the amount of variation or dispersion of a set of values.
 A low standard deviation indicates that the values tend to be close to the mean of the set, while a high standard deviation indicates that the values are spread out over a wider range.
@@ -359,6 +375,25 @@ $kurtosis = Stat::kurtosis([1, 2, 2, 2, 2, 2, 2, 2, 2, 50]);
 // positive (leptokurtic, heavier tails due to outlier)
 ```
 
+#### Stat::coefficientOfVariation( array $data, ?int $round = null, bool $population = false )
+The coefficient of variation (CV) is the ratio of the standard deviation to the mean, expressed as a percentage. It measures relative variability and is useful for comparing dispersion across datasets with different units or scales.
+
+By default it uses the sample standard deviation. Pass `population: true` to use the population standard deviation instead.
+
+Requires at least 2 data points (sample) or 1 (population). Throws if the mean is zero.
+
+```php
+use HiFolks\Statistics\Stat;
+$cv = Stat::coefficientOfVariation([10, 20, 30, 40, 50]);
+// ~52.70 (sample)
+
+$cv = Stat::coefficientOfVariation([10, 20, 30, 40, 50], round: 2);
+// 52.7
+
+$cv = Stat::coefficientOfVariation([10, 20, 30, 40, 50], population: true);
+// ~47.14 (population)
+```
+
 #### 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.

src/Stat.php

@@ -412,6 +412,52 @@ public static function thirdQuartile(array $data): mixed
         return $quartiles[2];
     }
 
+    /**
+     * Return the value at the given percentile of the data.
+     *
+     * Uses linear interpolation between adjacent data points,
+     * consistent with the exclusive quantile method.
+     *
+     * @param  array<int|float>  $data
+     * @param  float  $p  percentile in range 0..100
+     * @param  int|null  $round whether to round the result
+     * @return float the interpolated value at the given percentile
+     *
+     * @throws InvalidDataInputException if the data has fewer than 2 elements or p is out of range
+     */
+    public static function percentile(array $data, float $p, ?int $round = null): float
+    {
+        $count = self::count($data);
+        if ($count < 2) {
+            throw new InvalidDataInputException(
+                "Percentile requires at least 2 data points.",
+            );
+        }
+        if ($p < 0 || $p > 100) {
+            throw new InvalidDataInputException(
+                "Percentile must be between 0 and 100.",
+            );
+        }
+
+        sort($data);
+
+        // Exclusive method: rank = p/100 * (n + 1), 1-based index
+        $rank = ($p / 100) * ($count + 1);
+
+        if ($rank <= 1) {
+            return Math::round((float) $data[0], $round);
+        }
+        if ($rank >= $count) {
+            return Math::round((float) $data[$count - 1], $round);
+        }
+
+        $lower = (int) floor($rank) - 1;
+        $fraction = $rank - floor($rank);
+        $interpolated = $data[$lower] + $fraction * ($data[$lower + 1] - $data[$lower]);
+
+        return Math::round($interpolated, $round);
+    }
+
     /**
      * Return the **population** standard deviation,
      * a measure of the amount of variation or dispersion of a set of values.
@@ -625,6 +671,37 @@ public static function kurtosis(array $data, ?int $round = null): float
         return Math::round($kurtosis, $round);
     }
 
+    /**
+     * Return the coefficient of variation (CV) of the data.
+     * The coefficient of variation is the ratio of the standard deviation
+     * to the mean, expressed as a percentage. It measures relative variability
+     * and is useful for comparing dispersion across datasets with different units or scales.
+     *
+     * @param  array<int|float>  $data
+     * @param  int|null  $round whether to round the result
+     * @param  bool  $population if true, use population stdev/mean; otherwise sample
+     * @return float the coefficient of variation as a percentage
+     *
+     * @throws InvalidDataInputException if the data has fewer than 2 elements (sample)
+     *         or is empty (population), or if the mean is zero
+     */
+    public static function coefficientOfVariation(
+        array $data,
+        ?int $round = null,
+        bool $population = false,
+    ): float {
+        $mean = self::mean($data);
+        if ($mean == 0) {
+            throw new InvalidDataInputException(
+                "Coefficient of variation is undefined when the mean is zero.",
+            );
+        }
+
+        $sd = $population ? self::pstdev($data) : self::stdev($data);
+
+        return Math::round(($sd / abs($mean)) * 100, $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

@@ -307,6 +307,32 @@ public function kurtosis(?int $round = null): float
         return Stat::kurtosis($this->numericalArray(), $round);
     }
 
+    /**
+     * Return the value at the given percentile.
+     *
+     * @param  float  $p  percentile in range 0..100
+     * @param  int|null  $round whether to round the result
+     *
+     * @see Stat::percentile()
+     */
+    public function percentile(float $p, ?int $round = null): float
+    {
+        return Stat::percentile($this->numericalArray(), $p, $round);
+    }
+
+    /**
+     * Return the coefficient of variation (CV%) of the numeric data.
+     *
+     * @param  int|null  $round whether to round the result
+     * @param  bool  $population if true, use population stdev/mean
+     *
+     * @see Stat::coefficientOfVariation()
+     */
+    public function coefficientOfVariation(?int $round = null, bool $population = false): float
+    {
+        return Stat::coefficientOfVariation($this->numericalArray(), $round, $population);
+    }
+
     /**
      * Return the geometric mean of the numeric data.
      *

tests/StatTest.php

@@ -1015,4 +1015,105 @@ public function test_kde_random_triweight_covers_both_signs(): void
             $this->assertIsFloat($value);
         }
     }
+
+    // --- percentile ---
+
+    public function test_percentile_median_matches(): void
+    {
+        $data = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
+        $p50 = Stat::percentile($data, 50);
+        $this->assertEqualsWithDelta(Stat::median($data), $p50, 1e-10);
+    }
+
+    public function test_percentile_quartiles(): void
+    {
+        $data = [2, 4, 6, 8, 10, 12, 14, 16, 18, 20];
+        $q1 = Stat::percentile($data, 25);
+        $q3 = Stat::percentile($data, 75);
+        $this->assertEqualsWithDelta(Stat::firstQuartile($data), $q1, 1e-10);
+        $this->assertEqualsWithDelta(Stat::thirdQuartile($data), $q3, 1e-10);
+    }
+
+    public function test_percentile_boundaries(): void
+    {
+        $data = [10, 20, 30, 40, 50];
+        $this->assertEqualsWithDelta(10.0, Stat::percentile($data, 0), 1e-10);
+        $this->assertEqualsWithDelta(50.0, Stat::percentile($data, 100), 1e-10);
+    }
+
+    public function test_percentile_rounding(): void
+    {
+        $data = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
+        $result = Stat::percentile($data, 33, 2);
+        $this->assertEquals(round($result, 2), $result);
+    }
+
+    public function test_percentile_too_few_data_throws(): void
+    {
+        $this->expectException(InvalidDataInputException::class);
+        Stat::percentile([1], 50);
+    }
+
+    public function test_percentile_out_of_range_throws(): void
+    {
+        $this->expectException(InvalidDataInputException::class);
+        Stat::percentile([1, 2, 3], 101);
+    }
+
+    public function test_percentile_negative_throws(): void
+    {
+        $this->expectException(InvalidDataInputException::class);
+        Stat::percentile([1, 2, 3], -1);
+    }
+
+    // --- coefficientOfVariation ---
+
+    public function test_coefficient_of_variation(): void
+    {
+        $data = [10, 20, 30, 40, 50];
+        $expected = (Stat::stdev($data) / abs((float) Stat::mean($data))) * 100;
+        $this->assertEqualsWithDelta($expected, Stat::coefficientOfVariation($data), 1e-10);
+    }
+
+    public function test_coefficient_of_variation_population(): void
+    {
+        $data = [10, 20, 30, 40, 50];
+        $expected = (Stat::pstdev($data) / abs((float) Stat::mean($data))) * 100;
+        $this->assertEqualsWithDelta($expected, Stat::coefficientOfVariation($data, population: true), 1e-10);
+    }
+
+    public function test_coefficient_of_variation_rounding(): void
+    {
+        $data = [10, 20, 30, 40, 50];
+        $result = Stat::coefficientOfVariation($data, 2);
+        $this->assertEquals(round($result, 2), $result);
+    }
+
+    public function test_coefficient_of_variation_low_dispersion(): void
+    {
+        // Nearly identical values → low CV
+        $data = [100, 100.1, 99.9, 100.2, 99.8];
+        $cv = Stat::coefficientOfVariation($data);
+        $this->assertLessThan(1.0, $cv);
+    }
+
+    public function test_coefficient_of_variation_zero_mean_throws(): void
+    {
+        $this->expectException(InvalidDataInputException::class);
+        Stat::coefficientOfVariation([-1, 0, 1]);
+    }
+
+    public function test_coefficient_of_variation_negative_mean(): void
+    {
+        $data = [-10, -20, -30];
+        // Should use abs(mean), so CV is still positive
+        $cv = Stat::coefficientOfVariation($data);
+        $this->assertGreaterThan(0, $cv);
+    }
+
+    public function test_coefficient_of_variation_too_few_data_throws(): void
+    {
+        $this->expectException(InvalidDataInputException::class);
+        Stat::coefficientOfVariation([5]);
+    }
 }

tests/StatisticTest.php

@@ -241,4 +241,36 @@ public function test_min_with_empty_array(): void
     {
         $this->assertEquals(0, Statistics::make([])->min());
     }
+
+    public function test_percentile(): void
+    {
+        $s = Statistics::make([10, 20, 30, 40, 50, 60, 70, 80, 90, 100]);
+        $this->assertEqualsWithDelta($s->median(), $s->percentile(50), 1e-10);
+        $this->assertEqualsWithDelta($s->firstQuartile(), $s->percentile(25), 1e-10);
+        $this->assertEqualsWithDelta($s->thirdQuartile(), $s->percentile(75), 1e-10);
+    }
+
+    public function test_percentile_with_rounding(): void
+    {
+        $s = Statistics::make([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
+        $result = $s->percentile(33, 2);
+        $this->assertEquals(round($result, 2), $result);
+    }
+
+    public function test_coefficient_of_variation(): void
+    {
+        $s = Statistics::make([10, 20, 30, 40, 50]);
+        $cv = $s->coefficientOfVariation();
+        $this->assertGreaterThan(0, $cv);
+
+        $cvPop = $s->coefficientOfVariation(population: true);
+        $this->assertLessThan($cv, $cvPop);
+    }
+
+    public function test_coefficient_of_variation_with_rounding(): void
+    {
+        $s = Statistics::make([10, 20, 30, 40, 50]);
+        $result = $s->coefficientOfVariation(2);
+        $this->assertEquals(round($result, 2), $result);
+    }
 }