Merge pull request #13 from HubertRonald/feature/phase-5-statistics-examples

Add summary statistics helpers and simulation examples

Author: HubertRonald

CHANGELOG.md

@@ -8,12 +8,26 @@ This project follows a lightweight changelog format inspired by [Keep a Changelo
 
 ## [Unreleased]
 
+### Added
+
+* Added `mode(array)`.
+* Added `range(array)`.
+* Added `iqr(array)`.
+* Added `percentile(array, p)`.
+* Added `summary(array)`.
+* Added `examples/weighted_loot_drop.lua`.
+* Added `examples/monte_carlo_pi.lua`.
+* Added `examples/poisson_arrivals.lua`.
+* Added `examples/binomial_coin_flips.lua`.
+* Added `examples/bootstrap_mean.lua`.
+
 ### Planned
 
-* Continue improving documentation and examples.
-* Add manual GitHub Actions CI.
-* Add LuaRocks validation and publishing workflow improvements.
-* Consider additional statistics helpers and distribution examples.
+* Improve GitHub Actions CI with optional automatic checks for pull requests.
+* Improve LuaRocks validation and publishing workflows.
+* Add more distribution examples and simulation-oriented examples.
+* Explore a lightweight cross-reference with LuaHMF as a related pure-Lua math helper project.
+* Evaluate future combinatorics helpers such as `factorial`, `combinations`, and `permutations`.
 
 ---
 

README.md

@@ -44,6 +44,7 @@ The project started around 2014 and was later published under the MIT License. I
 * Lua 5.1+ friendly
 * Single-file friendly
 * Basic descriptive statistics
+* Summary statistics helpers
 * Sampling utilities
 * Discrete and continuous pseudo-random variables
 * Compatible with the existing public LuaSF API
@@ -107,6 +108,7 @@ print(stats.mean(values))     -- 3
 print(stats.stddev(values))   -- sample standard deviation
 print(stats.median(values))   -- 3
 print(stats.variance(values)) -- sample variance
+print(stats.summary(values).count) -- 5
 ```
 
 Legacy names are still available:
@@ -138,13 +140,18 @@ print(stats.stvF(values)) -- sample standard deviation
 
 ### Additional descriptive statistics
 
-| Function             | Description                         |
-| -------------------- | ----------------------------------- |
-| `variance(array)`    | Sample variance using `n - 1`       |
-| `median(array)`      | Median value                        |
-| `min(array)`         | Minimum value                       |
-| `max(array)`         | Maximum value                       |
-| `quantile(array, q)` | Quantile using linear interpolation |
+| Function               | Description                                                            |
+| ---------------------- | ---------------------------------------------------------------------- |
+| `variance(array)`      | Sample variance using `n - 1`                                          |
+| `median(array)`        | Median value                                                           |
+| `min(array)`           | Minimum value                                                          |
+| `max(array)`           | Maximum value                                                          |
+| `quantile(array, q)`   | Quantile using linear interpolation                                    |
+| `mode(array)`          | Most frequent value                                                    |
+| `range(array)`         | Difference between maximum and minimum                                 |
+| `iqr(array)`           | Interquartile range                                                    |
+| `percentile(array, p)` | Percentile where `p` is between `0` and `100`                          |
+| `summary(array)`       | Summary table with count, min, max, mean, median, variance, and stddev |
 
 ### Sampling utilities
 
@@ -202,6 +209,23 @@ for i = 1, #frequencies.counts do
 end
 ```
 
+### Summary statistics
+
+```lua
+local stats = require("luasf")
+
+local values = {10, 12, 14, 15, 18, 20}
+local result = stats.summary(values)
+
+print("Count:", result.count)
+print("Min:", result.min)
+print("Max:", result.max)
+print("Mean:", result.mean)
+print("Median:", result.median)
+print("Variance:", result.variance)
+print("Stddev:", result.stddev)
+```
+
 ### Normal distribution quality control sample
 
 ```lua
@@ -277,6 +301,11 @@ LuaSF/
     dice_simulation.lua
     normal_quality_control.lua
     gamma_distribution.lua
+    weighted_loot_drop.lua
+    monte_carlo_pi.lua
+    poisson_arrivals.lua
+    binomial_coin_flips.lua
+    bootstrap_mean.lua
   docs/
     api.md
   .github/
@@ -320,6 +349,11 @@ lua spec/test_sampling.lua
 lua examples/dice_simulation.lua
 lua examples/normal_quality_control.lua
 lua examples/gamma_distribution.lua
+lua examples/weighted_loot_drop.lua
+lua examples/monte_carlo_pi.lua
+lua examples/poisson_arrivals.lua
+lua examples/binomial_coin_flips.lua
+lua examples/bootstrap_mean.lua
 ```
 
 ---
@@ -342,11 +376,12 @@ lua examples/gamma_distribution.lua
 
 ### Planned
 
-* Manual GitHub Actions CI
-* LuaRocks package validation workflow
+* Improve GitHub Actions CI with optional automatic checks for pull requests
+* Improve LuaRocks validation and publishing workflows
 * More examples
 * More statistical helpers
-* Optional documentation generation
+* Lightweight cross-reference with LuaHMF
+* Future combinatorics helpers such as `factorial`, `combinations`, and `permutations`
 
 ---
 

docs/api.md

@@ -195,6 +195,101 @@ print(stats.quantile({1, 2, 3, 4, 5}, 0.5)) -- 3
 
 ---
 
+### `mode(array)`
+
+Returns the most frequent value in an array.
+
+If multiple values have the same frequency, LuaSF returns the first mode found after sorting the values.
+
+```lua
+local stats = require("luasf")
+
+print(stats.mode({1, 2, 2, 3})) -- 2
+```
+
+---
+
+### `range(array)`
+
+Returns the difference between the maximum and minimum values.
+
+```lua
+local stats = require("luasf")
+
+print(stats.range({3, 1, 10, 2})) -- 9
+```
+
+---
+
+### `iqr(array)`
+
+Returns the interquartile range.
+
+It is calculated as:
+
+```text
+quantile(array, 0.75) - quantile(array, 0.25)
+```
+
+Example:
+
+```lua
+local stats = require("luasf")
+
+print(stats.iqr({1, 2, 3, 4, 5})) -- 2
+```
+
+---
+
+### `percentile(array, p)`
+
+Returns the `p` percentile.
+
+`p` must be between `0` and `100`.
+
+```lua
+local stats = require("luasf")
+
+print(stats.percentile({1, 2, 3, 4, 5}, 50)) -- 3
+```
+
+---
+
+### `summary(array)`
+
+Returns a summary table with common descriptive statistics.
+
+The returned table includes:
+
+```lua
+{
+  count = number,
+  min = number,
+  max = number,
+  mean = number,
+  median = number,
+  variance = number or nil,
+  stddev = number or nil
+}
+```
+
+Example:
+
+```lua
+local stats = require("luasf")
+
+local result = stats.summary({1, 2, 3, 4, 5})
+
+print(result.count)    -- 5
+print(result.min)      -- 1
+print(result.max)      -- 5
+print(result.mean)     -- 3
+print(result.median)   -- 3
+print(result.variance) -- 2.5
+```
+
+---
+
 ## Sampling utilities
 
 ### `choice(array)`
@@ -673,6 +768,11 @@ stats.median
 stats.min
 stats.max
 stats.quantile
+stats.mode
+stats.range
+stats.iqr
+stats.percentile
+stats.summary
 stats.choice
 stats.shuffle
 stats.sample

examples/binomial_coin_flips.lua

@@ -0,0 +1,10 @@
+local stats = require("luasf")
+
+local flips = 10
+local probability_heads = 0.5
+local experiments = 20
+
+for i = 1, experiments do
+  local heads = stats.binomial(flips, probability_heads)
+  print("Experiment:", i, "Heads:", heads)
+end

examples/bootstrap_mean.lua

@@ -0,0 +1,25 @@
+local stats = require("luasf")
+
+local values = {10, 12, 14, 15, 18, 20}
+local bootstrap_means = {}
+local bootstrap_runs = 1000
+
+for run = 1, bootstrap_runs do
+  local sample = {}
+
+  for i = 1, #values do
+    sample[i] = stats.choice(values)
+  end
+
+  bootstrap_means[run] = stats.mean(sample)
+end
+
+local result = stats.summary(bootstrap_means)
+
+print("Bootstrap mean summary")
+print("Count:", result.count)
+print("Min:", result.min)
+print("Max:", result.max)
+print("Mean:", result.mean)
+print("Median:", result.median)
+print("Stddev:", result.stddev)

examples/monte_carlo_pi.lua

@@ -0,0 +1,17 @@
+local stats = require("luasf")
+
+local trials = 100000
+local inside = 0
+
+for _ = 1, trials do
+  local x = stats.uniform(-1, 1)
+  local y = stats.uniform(-1, 1)
+
+  if x * x + y * y <= 1 then
+    inside = inside + 1
+  end
+end
+
+local pi_estimate = 4 * inside / trials
+
+print("Pi estimate:", pi_estimate)

examples/poisson_arrivals.lua

@@ -0,0 +1,9 @@
+local stats = require("luasf")
+
+local lambda = 3
+local periods = 20
+
+for period = 1, periods do
+  local arrivals = stats.poisson(lambda)
+  print("Period:", period, "Arrivals:", arrivals)
+end

examples/weighted_loot_drop.lua

@@ -0,0 +1,16 @@
+local stats = require("luasf")
+
+local items = {"common", "rare", "epic", "legendary"}
+local weights = {80, 15, 4, 1}
+
+local drops = {}
+
+for i = 1, 1000 do
+  drops[i] = stats.weighted_choice(items, weights)
+end
+
+local frequencies = stats.frequency(drops)
+
+for i = 1, #frequencies.values do
+  print(frequencies.values[i], frequencies.counts[i])
+end

luasf-0.4.0-1.rockspec

@@ -0,0 +1,32 @@
+package = "luasf"
+version = "0.4.0-1"
+
+source = {
+  url = "git://github.com/HubertRonald/LuaSF.git",
+  tag = "v0.4.0"
+}
+
+description = {
+  summary = "Lua Statistics Functions",
+  detailed = [[
+LuaSF is a lightweight, pure-Lua library for descriptive statistics,
+summary statistics, sampling utilities, simulation examples, and random
+variable generation.
+  ]],
+  homepage = "https://github.com/HubertRonald/LuaSF",
+  license = "MIT",
+  maintainer = "Hubert Ronald"
+}
+
+dependencies = {
+  "lua >= 5.1"
+}
+
+build = {
+  type = "builtin",
+  modules = {
+    luasf = "src/luasf.lua",
+    LuaSF = "LuaSF.lua",
+    LuaStat = "LuaStat.lua"
+  }
+}