LuaSF: Lua Statistics Functions

LuaSF stands for Lua Statistics Functions.

LuaSF is a small, lightweight, pure-Lua library for descriptive statistics, shape statistics, bivariate statistics, probability helpers, sampling utilities, pseudo-random variable generation, and simple formula-based regression summaries.

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 modular source structure, additional statistics helpers, sampling utilities, probability helpers, LuaRocks packaging, and a compatibility-safe public API.

---

Why LuaSF?

• Pure Lua implementation
• No native dependencies
• Lua 5.1+ friendly
• Single-file friendly public API
• Modular internal source layout
• Basic descriptive statistics
• Summary statistics helpers
• Shape statistics helpers
• Bivariate statistics helpers
• Probability and combinatorics helpers
• Sampling utilities
• Discrete and continuous pseudo-random variables
• Simple formula-based regression summaries
• Compatible with the existing public LuaSF API
• Useful for simulations, teaching, small scripts, game/mod scripting, and lightweight statistical utilities

---

Installation

Option 1: LuaRocks

luarocks install luasf

Then use:

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:

local stats = require("LuaSF")

Option 3: Use the compatibility entry point

Older examples may use:

local stats = require("LuaStat")

This remains supported for compatibility.

Option 4: Use the source module directly

During development, load the implementation from src/:

local stats = require("src.luasf")

---

Quick start

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
print(stats.factorial(5))     -- 120
print(stats.combinations(5, 2)) -- 10

Legacy names are still available:

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

Shape statistics

Function	Description
central_moment(array, order)	Central moment using denominator n
skewness(array)	Standardized third central moment
kurtosis(array)	Pearson kurtosis
excess_kurtosis(array)	Fisher-style excess kurtosis, computed as kurtosis(array) - 3

Bivariate statistics

Function	Description
covariance(x, y)	Sample covariance using n - 1
correlation(x, y)	Pearson correlation coefficient
pearson(x, y)	Alias for correlation(x, y)

Probability helpers

Function	Description
factorial(n)	Factorial of a non-negative integer
permutations(n, r)	Ordered selections without repetition, also known as nPr
combinations(n, r)	Unordered selections without repetition, also known as nCr
permutations_with_repetition(n, r)	Ordered selections with repetition, calculated as n^r
combinations_with_repetition(n, r)	Unordered selections with repetition, calculated as C(n + r - 1, r)
permutations_without_repetition(n, r)	Alias for permutations(n, r)
combinations_without_repetition(n, r)	Alias for combinations(n, r)
multiset_permutations(counts)	Distinct arrangements of repeated item counts
nPr(n, r)	Alias for permutations(n, r)
nCr(n, r)	Alias for combinations(n, r)

These helpers use Lua numbers. Very large inputs may exceed the practical numeric precision or range of the Lua runtime.

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
studentTVA(df)	student_t(df)	Student's t 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.

Simple regression summaries

Function	Description
simple_linear_regression(x, y)	Formula-based simple linear regression summary
predict(model, x)	Predicts one value or a list of values
fitted_values(model)	Returns fitted values from a regression model
residuals(model)	Returns residuals from a regression model

LuaSF reports coefficients, R and R², sums of squares, mean squared error, residual standard error, standard errors, t statistics, and an ANOVA-style summary for simple regression. It does not compute p-values or confidence intervals.

---

Examples

Summary statistics

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)

Covariance and correlation

local stats = require("luasf")

local study_hours = {1, 2, 3, 4, 5}
local exam_scores = {50, 55, 65, 70, 80}

print(stats.covariance(study_hours, exam_scores))
print(stats.correlation(study_hours, exam_scores))

Twice two dice simulation

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

Normal distribution quality control sample

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:

-1.9688213737864
1.9688213737864

Random choice and sampling

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

local stats = require("luasf")

local items = {"low", "medium", "high"}
local weights = {1, 2, 7}

print(stats.weighted_choice(items, weights))

Deterministic custom RNG

local stats = require("luasf")

stats.set_rng(function()
  return 0.0
end)

print(stats.choice({"first", "second", "third"})) -- first

stats.reset_rng()

Student's t random variable

local stats = require("luasf")

print(stats.student_t(10))

Simple linear regression

local stats = require("luasf")

local x = {1, 2, 3, 4, 5}
local y = {3, 5, 7, 9, 11}

local model = stats.simple_linear_regression(x, y)

print(model.intercept) -- 1
print(model.slope)     -- 2
print(model.r_squared) -- 1
print(stats.predict(model, 6)) -- 13

---

Project structure

LuaSF/
  src/
    luasf.lua
    luasf/
      core.lua
      descriptive.lua
      shape.lua
      sampling.lua
      distributions.lua
      bivariate.lua
      probability.lua
      regression.lua
      validation.lua
      rng.lua
  spec/
    test_stats.lua
    test_distributions.lua
    test_sampling.lua
    test_bivariate.lua
    test_shape.lua
    test_probability.lua
    test_student_t.lua
    test_regression.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
    covariance_correlation.lua
    skewness_kurtosis.lua
    probability_helpers.lua
    student_t_distribution.lua
    simple_linear_regression.lua
  docs/
    api.md
  .github/
    workflows/
      ci.yml
      publish-luarocks.yml
  rockspec/
    luasf-0.2.0-1.rockspec
    luasf-0.3.0-1.rockspec
    luasf-0.4.0-1.rockspec
    luasf-0.5.0-1.rockspec
    luasf-0.6.0-1.rockspec
    luasf-0.7.0-1.rockspec
    luasf-0.8.0-1.rockspec
  LuaSF.lua
  LuaStat.lua
  README.md
  CHANGELOG.md
  CONTRIBUTING.md
  LICENSE

---

Running tests

Install luaunit:

luarocks install --local luaunit
eval "$(luarocks path --local)"

Run tests:

lua spec/test_bivariate.lua
lua spec/test_distributions.lua
lua spec/test_probability.lua
lua spec/test_regression.lua
lua spec/test_sampling.lua
lua spec/test_shape.lua
lua spec/test_stats.lua
lua spec/test_student_t.lua

---

Running examples

lua examples/binomial_coin_flips.lua
lua examples/bootstrap_mean.lua
lua examples/covariance_correlation.lua
lua examples/dice_simulation.lua
lua examples/gamma_distribution.lua
lua examples/monte_carlo_pi.lua
lua examples/normal_quality_control.lua
lua examples/poisson_arrivals.lua
lua examples/probability_helpers.lua
lua examples/simple_linear_regression.lua
lua examples/skewness_kurtosis.lua
lua examples/student_t_distribution.lua
lua examples/weighted_loot_drop.lua

---

Roadmap

Completed

• Compatibility-safe project revival
• Cleaner modular source structure
• Legacy API preservation
• Modern aliases
• Basic tests
• Examples
• API documentation
• Additional statistics helpers
• Summary statistics helpers
• Shape statistics helpers
• Bivariate statistics helpers
• Probability and combinatorics helpers
• Sampling utilities
• Deterministic simulation support
• Student's t random variable generator
• Formula-based simple linear regression summaries
• LuaRocks publishing

Possible future work

• More distribution and simulation examples
• Lightweight cross-reference with LuaHMF
• Carefully scoped confidence interval or critical value helpers

---

Scope

LuaSF is focused on lightweight statistics, probability, random variables, regression summaries, and simulation helpers.

Optimization-based modeling, machine learning workflows, model training pipelines, non-linear regression, and full statistical inference engines are intentionally outside the current scope of LuaSF.

---

Author and Maintainer

Hubert Ronald — Creator, author, and maintainer of LuaSF.

GitHub: HubertRonald

---

Contributors

Thanks to the contributors who have helped improve LuaSF.

See the full list of contributors on GitHub:

LuaSF contributors

---

License

This project is licensed under the MIT License. See the LICENSE file for details.