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:

localstats=require("luasf")
print(stats.sum({1, 2, 3})) -- 6

Option 2: Copy the file

Copy LuaSF.lua into your project and load it with:

localstats=require("LuaSF")

Option 3: Use the compatibility entry point

Older examples may use:

localstats=require("LuaStat")

This remains supported for compatibility.

Option 4: Use the source module directly

During development, load the implementation from src/:

localstats=require("src.luasf")

Quick start

localstats=require("luasf")
localvalues= {1, 2, 3, 4, 5}
print(stats.sum(values)) -- 15print(stats.mean(values)) -- 3print(stats.stddev(values)) -- sample standard deviationprint(stats.median(values)) -- 3print(stats.variance(values)) -- sample varianceprint(stats.summary(values).count) -- 5print(stats.factorial(5)) -- 120print(stats.combinations(5, 2)) -- 10

Legacy names are still available:

localstats=require("LuaSF")
localvalues= {1, 2, 3, 4, 5}
print(stats.sumF(values)) -- 15print(stats.avF(values)) -- 3print(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

localstats=require("luasf")
localvalues= {10, 12, 14, 15, 18, 20}
localresult=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

localstats=require("luasf")
localstudy_hours= {1, 2, 3, 4, 5}
localexam_scores= {50, 55, 65, 70, 80}
print(stats.covariance(study_hours, exam_scores))
print(stats.correlation(study_hours, exam_scores))

Twice two dice simulation

localstats=require("luasf")
localrolls= {}
fori=1, 10000dorolls[i] =stats.rand(1, 6) +stats.rand(1, 6)
endlocalfrequencies=stats.frequency(rolls)
fori=1, #frequencies.countsdoprint("Frequency - Sum Number:", frequencies.values[i], frequencies.counts[i])
end

Normal distribution quality control sample

localstats=require("luasf")
localalpha=5/100print(stats.normal_inv_D(alpha/2))
print(stats.normal_inv_D(1-alpha/2))

Expected output:

-1.9688213737864
1.9688213737864

Random choice and sampling

localstats=require("luasf")
localnames= {"Lua", "Python", "R"}
print(stats.choice(names))
localselected=stats.sample(names, 2)
fori=1, #selecteddoprint(selected[i])
end

Weighted choice

localstats=require("luasf")
localitems= {"low", "medium", "high"}
localweights= {1, 2, 7}
print(stats.weighted_choice(items, weights))

Deterministic custom RNG

localstats=require("luasf")
stats.set_rng(function()
return0.0end)
print(stats.choice({"first", "second", "third"})) -- firststats.reset_rng()

Student's t random variable

localstats=require("luasf")
print(stats.student_t(10))

Simple linear regression

localstats=require("luasf")
localx= {1, 2, 3, 4, 5}
localy= {3, 5, 7, 9, 11}
localmodel=stats.simple_linear_regression(x, y)
print(model.intercept) -- 1print(model.slope) -- 2print(model.r_squared) -- 1print(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.

Name		Name	Last commit message	Last commit date
Latest commit History 114 Commits
.github/workflows		.github/workflows
docs		docs
examples		examples
rockspec		rockspec
spec		spec
src		src
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
LuaSF.lua		LuaSF.lua
LuaStat.lua		LuaStat.lua
README.md		README.md

Folders and files

Latest commit

History

Repository files navigation

LuaSF: Lua Statistics Functions

Why LuaSF?

Installation

Option 1: LuaRocks

Option 2: Copy the file

Option 3: Use the compatibility entry point

Option 4: Use the source module directly

Quick start

API Overview

Descriptive statistics

Additional descriptive statistics

Shape statistics

Bivariate statistics

Probability helpers

Sampling utilities

Random variables and distributions

Simple regression summaries

Examples

Summary statistics

Covariance and correlation

Twice two dice simulation

Normal distribution quality control sample

Random choice and sampling

Weighted choice

Deterministic custom RNG

Student's t random variable

Simple linear regression

Project structure

Running tests

Running examples

Roadmap

Completed

Possible future work

Scope

Author and Maintainer

Contributors

License

About

Topics

Resources

Contributing

Stars

Watchers

Forks

Releases

Contributors

Languages