Adding zscores() and outliers() methods

Author: roberto-butti

CHANGELOG.md

@@ -9,6 +9,8 @@
 - Adding `sem()` method for standard error of the mean
 - Adding `meanAbsoluteDeviation()` method for mean absolute deviation — average distance from the mean
 - Adding `medianAbsoluteDeviation()` method for median absolute deviation — robust dispersion measure resistant to outliers
+- 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
 
 ## 1.2.5 - 2026-02-22
 - Adding `kurtosis()` method for excess kurtosis

README.md

@@ -87,6 +87,8 @@ The various mathematical statistics are listed below:
 | `pskewness()` | population (biased) skewness |
 | `kurtosis()` | excess kurtosis (sample formula, 0 for normal distribution) |
 | `coefficientOfVariation()` | coefficient of variation (CV%), relative dispersion as percentage |
+| `zscores()` | z-scores for each value — how many standard deviations from the mean |
+| `outliers()` | outlier detection based on z-score threshold |
 | `geometricMean()` | geometric mean |
 | `harmonicMean()` | harmonic mean |
 | `correlation()` | Pearson’s or Spearman’s rank correlation coefficient for two inputs |
@@ -482,6 +484,36 @@ $cv = Stat::coefficientOfVariation([10, 20, 30, 40, 50], population: true);
 // ~47.14 (population)
 ```
 
+#### Stat::zscores( array $data, ?int $round = null )
+Return the z-score for each value in the dataset. A z-score indicates how many standard deviations a value is from the mean. Z-scores are useful for standardizing data, comparing values from different distributions, and identifying outliers.
+
+The z-scores of any dataset always sum to zero, and values beyond ±2 or ±3 are typically considered unusual or outliers.
+
+Requires at least 2 data points and non-zero standard deviation.
+
+```php
+use HiFolks\Statistics\Stat;
+$zscores = Stat::zscores([2, 4, 4, 4, 5, 5, 7, 9]);
+// array of z-scores, one per value
+
+$zscores = Stat::zscores([2, 4, 4, 4, 5, 5, 7, 9], 2);
+// z-scores rounded to 2 decimal places
+```
+
+#### Stat::outliers( array $data, float $threshold = 3.0 )
+Return values from the dataset that are outliers based on z-score threshold. A value is considered an outlier if its absolute z-score exceeds the threshold.
+
+The default threshold of 3.0 is a widely used convention — in a normal distribution, about 99.7% of values fall within 3 standard deviations of the mean, so values beyond that are rare. Use a lower threshold (e.g. 2.0) for stricter detection, or a higher one for more lenient filtering.
+
+```php
+use HiFolks\Statistics\Stat;
+$outliers = Stat::outliers([1, 2, 3, 4, 5, 6, 7, 8, 9, 100]);
+// [100]
+
+$outliers = Stat::outliers([1, 2, 3, 4, 5, 6, 7, 8, 9, 10], 1.0);
+// values more than 1 stdev from the mean
+```
+
 #### 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

@@ -716,6 +716,62 @@ public static function medianAbsoluteDeviation(array $data, ?int $round = null):
         return Math::round((float) self::median($deviations), $round);
     }
 
+    /**
+     * Return the z-scores for each value in the dataset.
+     * A z-score indicates how many standard deviations a value is from the mean.
+     *
+     * Formula: zi = (xi - mean) / stdev
+     *
+     * @param  array<int|float>  $data
+     * @param  int|null  $round whether to round each z-score
+     * @return array<float> the z-scores
+     *
+     * @throws InvalidDataInputException if data size is less than 2 or stdev is zero
+     */
+    public static function zscores(array $data, ?int $round = null): array
+    {
+        $mean = self::mean($data);
+        $stdev = self::stdev($data);
+        if ($stdev == 0) {
+            throw new InvalidDataInputException(
+                "Z-scores are undefined when all values are identical (standard deviation is zero).",
+            );
+        }
+
+        $zscores = [];
+        foreach ($data as $value) {
+            $zscores[] = Math::round(($value - $mean) / $stdev, $round);
+        }
+
+        return $zscores;
+    }
+
+    /**
+     * Return values from the dataset that are outliers based on z-score threshold.
+     * A value is considered an outlier if its absolute z-score exceeds the threshold.
+     *
+     * The default threshold of 3.0 is a common convention (values more than 3 standard
+     * deviations from the mean).
+     *
+     * @param  array<int|float>  $data
+     * @param  float  $threshold  absolute z-score threshold (default 3.0)
+     * @return array<int|float> the outlier values
+     *
+     * @throws InvalidDataInputException if data size is less than 2 or stdev is zero
+     */
+    public static function outliers(array $data, float $threshold = 3.0): array
+    {
+        $zscores = self::zscores($data);
+        $outliers = [];
+        foreach ($data as $i => $value) {
+            if (abs($zscores[$i]) > $threshold) {
+                $outliers[] = $value;
+            }
+        }
+
+        return $outliers;
+    }
+
     /**
      * Return the variance from the numeric data.
      *

src/Statistics.php

@@ -297,6 +297,32 @@ public function medianAbsoluteDeviation(?int $round = null): float
         return Stat::medianAbsoluteDeviation($this->numericalArray(), $round);
     }
 
+    /**
+     * Return the z-scores for each value in the dataset.
+     *
+     * @param  int|null  $round whether to round each z-score
+     * @return array<float>
+     *
+     * @see Stat::zscores()
+     */
+    public function zscores(?int $round = null): array
+    {
+        return Stat::zscores($this->numericalArray(), $round);
+    }
+
+    /**
+     * Return values that are outliers based on z-score threshold.
+     *
+     * @param  float  $threshold  absolute z-score threshold (default 3.0)
+     * @return array<int|float>
+     *
+     * @see Stat::outliers()
+     */
+    public function outliers(float $threshold = 3.0): array
+    {
+        return Stat::outliers($this->numericalArray(), $threshold);
+    }
+
     /**
      * Return the variance from the numeric data
      *

tests/StatTest.php

@@ -1347,4 +1347,77 @@ public function test_median_absolute_deviation_empty_throws(): void
         $this->expectException(InvalidDataInputException::class);
         Stat::medianAbsoluteDeviation([]);
     }
+
+    // --- zscores ---
+
+    public function test_zscores(): void
+    {
+        $data = [2, 4, 4, 4, 5, 5, 7, 9];
+        $zscores = Stat::zscores($data);
+        $mean = (float) Stat::mean($data);
+        $stdev = Stat::stdev($data);
+
+        $this->assertCount(count($data), $zscores);
+        foreach ($data as $i => $value) {
+            $this->assertEqualsWithDelta(($value - $mean) / $stdev, $zscores[$i], 1e-10);
+        }
+    }
+
+    public function test_zscores_sum_to_zero(): void
+    {
+        $data = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
+        $zscores = Stat::zscores($data);
+        $this->assertEqualsWithDelta(0.0, array_sum($zscores), 1e-10);
+    }
+
+    public function test_zscores_with_rounding(): void
+    {
+        $data = [2, 4, 4, 4, 5, 5, 7, 9];
+        $zscores = Stat::zscores($data, 2);
+        foreach ($zscores as $z) {
+            $this->assertEquals(round($z, 2), $z);
+        }
+    }
+
+    public function test_zscores_identical_values_throws(): void
+    {
+        $this->expectException(InvalidDataInputException::class);
+        Stat::zscores([5, 5, 5, 5]);
+    }
+
+    public function test_zscores_too_few_data_throws(): void
+    {
+        $this->expectException(InvalidDataInputException::class);
+        Stat::zscores([5]);
+    }
+
+    // --- outliers ---
+
+    public function test_outliers_detects_extreme_values(): void
+    {
+        $data = [10, 10, 10, 10, 10, 10, 10, 10, 10, 10, 10, 10, 10, 10, 10, 10, 10, 10, 10, 100];
+        $outliers = Stat::outliers($data);
+        $this->assertContains(100, $outliers);
+    }
+
+    public function test_outliers_no_outliers(): void
+    {
+        $data = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
+        $outliers = Stat::outliers($data);
+        $this->assertEmpty($outliers);
+    }
+
+    public function test_outliers_custom_threshold(): void
+    {
+        $data = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
+        // With a very low threshold, more values are flagged
+        $outliers = Stat::outliers($data, 1.0);
+        $this->assertNotEmpty($outliers);
+    }
+
+    public function test_outliers_identical_values_throws(): void
+    {
+        $this->expectException(InvalidDataInputException::class);
+        Stat::outliers([5, 5, 5, 5]);
+    }
 }

tests/StatisticTest.php

@@ -316,4 +316,18 @@ public function test_median_absolute_deviation(): void
         $s = Statistics::make([1, 2, 3, 4, 5]);
         $this->assertEqualsWithDelta(1.0, $s->medianAbsoluteDeviation(), 1e-10);
     }
+
+    public function test_zscores(): void
+    {
+        $s = Statistics::make([2, 4, 4, 4, 5, 5, 7, 9]);
+        $zscores = $s->zscores();
+        $this->assertCount(8, $zscores);
+        $this->assertEqualsWithDelta(0.0, array_sum($zscores), 1e-10);
+    }
+
+    public function test_outliers(): void
+    {
+        $s = Statistics::make([10, 10, 10, 10, 10, 10, 10, 10, 10, 10, 10, 10, 10, 10, 10, 10, 10, 10, 10, 100]);
+        $this->assertContains(100, $s->outliers());
+    }
 }