https://github.com/hubertronald/luasf
Lua Statistics Functions is a lightweight pure-Lua library for descriptive statistics and discrete/continuous pseudo-random variables.
https://github.com/hubertronald/luasf
distributions education gamedev lua lua-library luarocks math modding monte-carlo open-source probability pure-lua random random-variables scripting simulation statistics teaching
Last synced: 3 days ago
JSON representation
Lua Statistics Functions is a lightweight pure-Lua library for descriptive statistics and discrete/continuous pseudo-random variables.
- Host: GitHub
- URL: https://github.com/hubertronald/luasf
- Owner: HubertRonald
- License: mit
- Created: 2017-04-04T04:31:10.000Z (about 9 years ago)
- Default Branch: master
- Last Pushed: 2026-06-05T00:52:07.000Z (6 days ago)
- Last Synced: 2026-06-05T01:12:18.509Z (6 days ago)
- Topics: distributions, education, gamedev, lua, lua-library, luarocks, math, modding, monte-carlo, open-source, probability, pure-lua, random, random-variables, scripting, simulation, statistics, teaching
- Language: Lua
- Homepage:
- Size: 70.3 KB
- Stars: 6
- Watchers: 1
- Forks: 3
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# LuaSF: Lua Statistics Functions
**LuaSF** stands for **Lua Statistics Functions**.
LuaSF is a small, lightweight, pure-Lua library for descriptive statistics, sampling utilities, and pseudo-random variable generation.
The project started around 2014 and was later published under the MIT License. It has now been revived with compatibility improvements, tests, examples, documentation, a cleaner module structure, additional statistics helpers, sampling utilities, and LuaRocks packaging while preserving the existing public API.
---
## Why LuaSF?
* Pure Lua implementation
* No native dependencies
* 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
* Useful for simulations, teaching, small scripts, game/mod scripting, and lightweight statistical utilities
---
## Installation
### Option 1: LuaRocks
```bash
luarocks install luasf
```
Then use:
```lua
local stats = require("luasf")
print(stats.sum({1, 2, 3})) -- 6
```
### Option 2: Copy the file
Copy `LuaSF.lua` into your project and load it with:
```lua
local stats = require("LuaSF")
```
### Option 3: Use the compatibility entry point
Older examples may use:
```lua
local stats = require("LuaStat")
```
This remains supported for compatibility.
### Option 4: Use the source module directly
During development, load the implementation from `src/`:
```lua
local stats = require("src.luasf")
```
---
## Quick start
```lua
local stats = require("luasf")
local values = {1, 2, 3, 4, 5}
print(stats.sum(values)) -- 15
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:
```lua
local stats = require("LuaSF")
local values = {1, 2, 3, 4, 5}
print(stats.sumF(values)) -- 15
print(stats.avF(values)) -- 3
print(stats.stvF(values)) -- sample standard deviation
```
---
## API Overview
### Descriptive statistics
| Legacy name | Modern alias | Description |
| ------------------- | ------------------ | --------------------------------------- |
| `sumF(array)` | `sum(array)` | Sum of numeric values |
| `avF(array)` | `mean(array)` | Arithmetic mean |
| `stvF(array)` | `stddev(array)` | Sample standard deviation using `n - 1` |
| `frecuencyF(array)` | `frequency(array)` | Frequency distribution |
> `frecuencyF` keeps the original spelling for backward compatibility.
### 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 |
| `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
| Function | Description |
| --------------------------------- | ---------------------------------------------- |
| `choice(array)` | Returns one random item from an array |
| `shuffle(array)` | Returns a shuffled copy of an array |
| `sample(array, n)` | Returns `n` random items without replacement |
| `weighted_choice(items, weights)` | Returns one random item using weights |
| `set_rng(rng_function)` | Sets a custom random number generator |
| `reset_rng()` | Restores Lua's default random number generator |
### Random variables and distributions
| Legacy name | Modern alias | Description |
| -------------------------- | ---------------------------- | -------------------------------- |
| `nomalVA(mu, sig)` | `normal(mu, sig)` | Normal random variable |
| `normalVA(mu, sig)` | `normal(mu, sig)` | Normal random variable |
| `normal_inv_D(p, mu, sig)` | `inverse_normal(p, mu, sig)` | Approximate inverse normal value |
| `bernoulliVA(p)` | `bernoulli(p)` | Bernoulli random variable |
| `unifVA(min, max)` | `uniform(min, max)` | Uniform random variable |
| `expoVA(beta)` | `exponential(beta)` | Exponential random variable |
| `weibullVA(alpha, beta)` | `weibull(alpha, beta)` | Weibull random variable |
| `erlangVA(n, lambda)` | `erlang(n, lambda)` | Erlang random variable |
| `trianVA(a, b, c)` | `triangular(a, b, c)` | Triangular random variable |
| `binomialVA(n, p)` | `binomial(n, p)` | Binomial random variable |
| `geometricVA(p)` | `geometric(p)` | Geometric random variable |
| `poissonVA(lambda)` | `poisson(lambda)` | Poisson random variable |
| `chiSquareVA(n)` | `chi_square(n)` | Chi-square random variable |
| `gamVA(alpha, lambda)` | `gamma(alpha, lambda)` | Gamma random variable |
| `lognoVA(m, s)` | `lognormal(m, s)` | Log-normal random variable |
| `lognoRandVA(m, s)` | `lognormal(m, s)` | Log-normal random variable |
> `nomalVA` and `lognoRandVA` are preserved as compatibility aliases.
---
## Examples
### Twice two dice simulation
```lua
local stats = require("luasf")
local rolls = {}
for i = 1, 10000 do
rolls[i] = stats.rand(1, 6) + stats.rand(1, 6)
end
local frequencies = stats.frequency(rolls)
for i = 1, #frequencies.counts do
print("Frequency - Sum Number:", frequencies.values[i], frequencies.counts[i])
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
local stats = require("luasf")
local alpha = 5 / 100
print(stats.normal_inv_D(alpha / 2))
print(stats.normal_inv_D(1 - alpha / 2))
```
Expected output:
```text
-1.9688213737864
1.9688213737864
```
### Random choice and sampling
```lua
local stats = require("luasf")
local names = {"Lua", "Python", "R"}
print(stats.choice(names))
local selected = stats.sample(names, 2)
for i = 1, #selected do
print(selected[i])
end
```
### Weighted choice
```lua
local stats = require("luasf")
local items = {"low", "medium", "high"}
local weights = {1, 2, 7}
print(stats.weighted_choice(items, weights))
```
### Deterministic custom RNG
```lua
local stats = require("luasf")
stats.set_rng(function()
return 0.0
end)
print(stats.choice({"first", "second", "third"})) -- first
stats.reset_rng()
```
---
## Project structure
```text
LuaSF/
src/
luasf.lua
spec/
test_stats.lua
test_distributions.lua
test_sampling.lua
examples/
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/
workflows/
ci.yml
publish-luarocks.yml
LuaSF.lua
LuaStat.lua
README.md
CHANGELOG.md
CONTRIBUTING.md
LICENSE
luasf-0.2.0-1.rockspec
luasf-0.3.0-1.rockspec
```
---
## Running tests
Install `luaunit`:
```bash
luarocks install --local luaunit
eval "$(luarocks path --local)"
```
Run tests:
```bash
lua spec/test_stats.lua
lua spec/test_distributions.lua
lua spec/test_sampling.lua
```
---
## Running examples
```bash
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
```
---
## Roadmap
### Completed
* Compatibility-safe project revival
* Cleaner module structure
* Legacy API preservation
* Modern aliases
* Basic tests
* Examples
* API documentation
* Additional statistics helpers
* Sampling utilities
* Deterministic simulation support
* LuaRocks publishing
### Planned
* Improve GitHub Actions CI with optional automatic checks for pull requests
* Improve LuaRocks validation and publishing workflows
* More examples
* More statistical helpers
* Lightweight cross-reference with LuaHMF
* Future combinatorics helpers such as `factorial`, `combinations`, and `permutations`
---
## Author and Maintainer
**Hubert Ronald** — Creator, author, and maintainer of LuaSF.
GitHub: [HubertRonald](https://github.com/HubertRonald)
---
## Contributors
Thanks to the contributors who have helped improve LuaSF.
See the full list of contributors on GitHub:
[LuaSF contributors](https://github.com/HubertRonald/LuaSF/graphs/contributors?all=1)
---
## License
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.