Adding sem() method

Author: roberto-butti

CHANGELOG.md

@@ -6,6 +6,7 @@
 - Adding `coefficientOfVariation()` method for relative dispersion (CV%), supporting both sample and population modes
 - Adding `trimmedMean()` method for robust central tendency — computes the mean after removing outliers from each side
 - Adding `weightedMedian()` method for computing the median with weighted observations
+- Adding `sem()` method for standard error of the mean
 
 ## 1.2.5 - 2026-02-22
 - Adding `kurtosis()` method for excess kurtosis

README.md

@@ -78,6 +78,7 @@ The various mathematical statistics are listed below:
 | `percentile()` | value at any percentile (0–100) with linear interpolation |
 | `pstdev()` | Population standard deviation |
 | `stdev()` | Sample standard deviation |
+| `sem()` | Standard error of the mean (SEM) — measures precision of the sample mean |
 | `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 |
@@ -341,6 +342,22 @@ $stdev = Stat::stdev([1.5, 2.5, 2.5, 2.75, 3.25, 4.75], 4);
 // 1.0811
 ```
 
+#### Stat::sem( array $data, ?int $round = null )
+Return the standard error of the mean (SEM). SEM measures how precisely the sample mean estimates the population mean. It decreases as the sample size grows.
+
+Formula: `stdev / sqrt(n)`
+
+Requires at least 2 data points.
+
+```php
+use HiFolks\Statistics\Stat;
+$sem = Stat::sem([2, 4, 4, 4, 5, 5, 7, 9]);
+// 0.7559...
+
+$sem = Stat::sem([2, 4, 4, 4, 5, 5, 7, 9], 4);
+// 0.7559
+```
+
 #### Stat::variance ( array $data, ?int $round = null, int|float|null $xbar = null)
 Variance is a measure of dispersion of data points from the mean.
 Low variance indicates that data points are generally similar and do not vary widely from the mean.

src/Stat.php

@@ -642,6 +642,23 @@ public static function stdev(array $data, ?int $round = null): float
         return Math::round(sqrt($variance), $round);
     }
 
+    /**
+     * Return the standard error of the mean (SEM).
+     * SEM measures how precisely the sample mean estimates the population mean.
+     *
+     * Formula: stdev / sqrt(n)
+     *
+     * @param  array<int|float>  $data
+     * @param  int|null  $round whether to round the result
+     * @return float the standard error of the mean
+     *
+     * @throws InvalidDataInputException if data size is less than 2
+     */
+    public static function sem(array $data, ?int $round = null): float
+    {
+        return Math::round(self::stdev($data) / sqrt(self::count($data)), $round);
+    }
+
     /**
      * Return the variance from the numeric data.
      *

src/Statistics.php

@@ -261,6 +261,18 @@ public function stdev(?int $round = null): float
         return Stat::stdev($this->numericalArray(), $round);
     }
 
+    /**
+     * Return the standard error of the mean (SEM).
+     *
+     * @param  int|null  $round whether to round the result
+     *
+     * @see Stat::sem()
+     */
+    public function sem(?int $round = null): float
+    {
+        return Stat::sem($this->numericalArray(), $round);
+    }
+
     /**
      * Return the variance from the numeric data
      *

tests/StatTest.php

@@ -1237,4 +1237,33 @@ public function test_weighted_median_zero_weight_throws(): void
         $this->expectException(InvalidDataInputException::class);
         Stat::weightedMedian([1, 2, 3], [1, 0, 1]);
     }
+
+    // --- sem ---
+
+    public function test_sem(): void
+    {
+        $data = [2, 4, 4, 4, 5, 5, 7, 9];
+        $expected = Stat::stdev($data) / sqrt(Stat::count($data));
+        $this->assertEqualsWithDelta($expected, Stat::sem($data), 1e-10);
+    }
+
+    public function test_sem_with_rounding(): void
+    {
+        $data = [2, 4, 4, 4, 5, 5, 7, 9];
+        $result = Stat::sem($data, 4);
+        $this->assertEquals(round($result, 4), $result);
+    }
+
+    public function test_sem_decreases_with_larger_sample(): void
+    {
+        $small = [1, 2, 3, 4, 5];
+        $large = [1, 2, 3, 4, 5, 1, 2, 3, 4, 5];
+        $this->assertGreaterThan(Stat::sem($large), Stat::sem($small));
+    }
+
+    public function test_sem_too_few_data_throws(): void
+    {
+        $this->expectException(InvalidDataInputException::class);
+        Stat::sem([5]);
+    }
 }

tests/StatisticTest.php

@@ -3,6 +3,7 @@
 namespace HiFolks\Statistics\Tests;
 
 use HiFolks\Statistics\Exception\InvalidDataInputException;
+use HiFolks\Statistics\Stat;
 use HiFolks\Statistics\Statistics;
 use PHPUnit\Framework\TestCase;
 
@@ -296,4 +297,11 @@ public function test_weighted_median(): void
         // Heavy weight on 3 → weighted median is 3
         $this->assertEqualsWithDelta(3.0, $s->weightedMedian([1, 1, 10]), 1e-10);
     }
+
+    public function test_sem(): void
+    {
+        $s = Statistics::make([2, 4, 4, 4, 5, 5, 7, 9]);
+        $expected = Stat::stdev([2, 4, 4, 4, 5, 5, 7, 9]) / sqrt(8);
+        $this->assertEqualsWithDelta($expected, $s->sem(), 1e-10);
+    }
 }