Skip to content

Add simple regression summaries and Student t random variable #21

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
HubertRonald merged 7 commits into from
Jun 10, 2026
Merged

Add simple regression summaries and Student t random variable #21

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
cebc336
Add Student t distribution and regression helpers
HubertRonald Jun 10, 2026
94619d8
Add Student t and regression tests
HubertRonald Jun 10, 2026
058eba6
Add Student t and simple regression examples
HubertRonald Jun 10, 2026
759a791
Add LuaRocks rockspec for v0.8.0
HubertRonald Jun 10, 2026
0a21b48
Add regression release checks to workflows
HubertRonald Jun 10, 2026
61d2abc
Document simple regression and Student t helpers
HubertRonald Jun 10, 2026
3b55c2e
Add Student t and regression tests
HubertRonald Jun 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions .github/workflows/ci.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,6 +60,8 @@ jobs:
lua spec/test_bivariate.lua
lua spec/test_shape.lua
lua spec/test_probability.lua
lua spec/test_student_t.lua
lua spec/test_regression.lua

- name: Run examples
run: |
Expand All @@ -74,3 +76,5 @@ jobs:
lua examples/covariance_correlation.lua
lua examples/skewness_kurtosis.lua
lua examples/probability_helpers.lua
lua examples/student_t_distribution.lua
lua examples/simple_linear_regression.lua
7 changes: 5 additions & 2 deletions .github/workflows/publish-luarocks.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ on:
rockspec:
description: "Rockspec file to validate or publish"
required: true
default: "rockspec/luasf-0.7.0-1.rockspec"
default: "rockspec/luasf-0.8.0-1.rockspec"
type: string
publish:
description: "Publish to LuaRocks after validation"
Expand Down Expand Up @@ -52,7 +52,10 @@ jobs:

- name: Test probability helpers entry point
run: lua -e 'local stats = require("luasf"); print(stats.factorial(5)); print(stats.combinations(5,2)); print(stats.permutations_with_repetition(10,4))'


- name: Test LuaRocks package entry point
run: lua -e 'local stats = require("luasf"); print(stats.simple_linear_regression({1,2,3}, {2,4,6}).slope)'

- name: Test LuaSF compatibility entry point
run: lua -e 'local stats = require("LuaSF"); print(stats.sumF({1,2,3}))'

Expand Down
39 changes: 36 additions & 3 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,13 +10,46 @@ This project follows a lightweight changelog format inspired by [Keep a Changelo

### Planned

* Add more distribution and simulation-oriented examples.
* Explore a lightweight cross-reference with LuaHMF as a related pure-Lua math helper project.
* Add more distribution and simulation examples.
* Evaluate optional formula-based simple regression summaries while keeping ML workflows outside the current scope.
* Explore carefully scoped confidence interval or critical value helpers.

---

## [0.7.0] - 2026-06-07
## [0.8.0] - 2026-06-09

### Added

* Added Student's t random variable generator `studentTVA(df)`.
* Added modern aliases `student_t(df)` and `t_student(df)`.
* Added `src/luasf/regression.lua` for formula-based simple linear regression summaries.
* Added `simple_linear_regression(x, y)`.
* Added `predict(model, x)`.
* Added `fitted_values(model)`.
* Added `residuals(model)`.
* Added regression summary fields for coefficients, R, R², adjusted R², SSE, SSR, SST, MSE, RMSE, residual standard error, standard errors, and t statistics.
* Added ANOVA-style regression summary without p-values.
* Added `spec/test_student_t.lua`.
* Added `spec/test_regression.lua`.
* Added `examples/student_t_distribution.lua`.
* Added `examples/simple_linear_regression.lua`.
* Added `rockspec/luasf-0.8.0-1.rockspec`.

### Changed

* Updated the public facade to expose regression helpers.
* Updated GitHub Actions workflows to run Student's t and regression tests/examples.
* Updated LuaRocks workflow default rockspec path to `rockspec/luasf-0.8.0-1.rockspec`.
* Updated README, API documentation, and contributing notes.

### Scope

* LuaSF now includes formula-based simple regression summaries, but it does not compute p-values or confidence intervals.
* Multiple regression, non-linear regression, optimization-based modeling, and machine learning workflows remain outside the current scope.

---

## [0.7.0] - 2026-06-09

### Added

Expand Down
30 changes: 23 additions & 7 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@ LuaSF aims to provide:
* Probability and combinatorics helpers
* Pseudo-random variable generation
* Sampling utilities
* Formula-based simple regression summaries
* A small and readable Lua codebase
* Compatibility with the existing public API
* Useful examples for simulations, teaching, small scripts, and game/mod scripting
Expand All @@ -36,17 +37,20 @@ Good fits for LuaSF:
* Random variable generation
* Sampling and simulation utilities
* Formula-based statistical summaries
* Small examples and tests

Currently out of scope:

* Machine learning pipelines
* Large machine learning workflows
* Optimization-based model training
* Non-linear regression fitting
* Deep learning
* Non-linear regression engines
* Multiple regression requiring a full matrix algebra subsystem
* Native dependencies
* Large framework-style APIs
* Big integer dependencies
* Full statistical inference engines with p-value/CDF approximations unless carefully scoped and tested

For simple regression, LuaSF may report coefficients, R and R², sums of squares, standard errors, t statistics, and ANOVA-style summaries. Full p-values and confidence intervals are intentionally outside the current scope.

Formula-based simple regression summaries may be considered in the future, but ML-style model training is intentionally outside the current scope.

---

Expand Down Expand Up @@ -74,6 +78,7 @@ binomialVA
geometricVA
poissonVA
chiSquareVA
studentTVA
gamVA
lognoVA
lognoRandVA
Expand Down Expand Up @@ -103,6 +108,7 @@ src/
distributions.lua
bivariate.lua
probability.lua
regression.lua
shape.lua
validation.lua
rng.lua
Expand All @@ -116,7 +122,8 @@ Recommended module ownership:
* `bivariate.lua`: two-variable statistics such as covariance and correlation
* `sampling.lua`: sampling helpers
* `distributions.lua`: random variable generators
* `probability.lua`: future probability/combinatorics helpers
* `probability.lua`: probability/combinatorics helpers
* `regression.lua`: simple regression
* `validation.lua`: reusable input validation helpers
* `shape.lua`: skewness and kurtosis helpers
* `rng.lua`: random generator and seed helpers
Expand Down Expand Up @@ -155,6 +162,8 @@ lua spec/test_sampling.lua
lua spec/test_bivariate.lua
lua spec/test_shape.lua
lua spec/test_probability.lua
lua spec/test_student_t.lua
lua spec/test_regression.lua
```

Run examples:
Expand All @@ -171,6 +180,8 @@ lua examples/bootstrap_mean.lua
lua examples/covariance_correlation.lua
lua examples/skewness_kurtosis.lua
lua examples/probability_helpers.lua
lua examples/student_t_distribution.lua
lua examples/simple_linear_regression.lua
```

---
Expand Down Expand Up @@ -284,6 +295,7 @@ Before opening a pull request, please check:
* New modules are included in the rockspec draft when needed.
* Code remains readable and dependency-light.
* LuaRocks rockspec files are updated when preparing a package release.
* Rockspec modules are updated when new source files are added.
* CI workflows are updated when new tests or examples are added.


Expand All @@ -299,6 +311,7 @@ Prefer:
* Minimal dependencies
* Compatibility with Lua 5.1+
* Explicit validation for public helpers
* Small, focused modules
* Formula-based helpers when appropriate

Avoid:
Expand All @@ -308,12 +321,15 @@ Avoid:
* Adding native dependencies
* Overcomplicating the API
* Turning LuaSF into a machine learning framework
* Hidden behavior that makes examples harder to understand

---

## Future scope

Simple formula-based regression summaries may be considered later, but optimization-based models and ML workflows are outside the current scope.
* Explore carefully scoped confidence interval or critical value helpers.
* Explore a lightweight cross-reference with LuaHMF as a related pure-Lua math helper project.
* Add more distribution and simulation-oriented examples.

---

Expand Down
85 changes: 69 additions & 16 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,9 +31,9 @@

**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, and pseudo-random variable generation.
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, and LuaRocks packaging while preserving the existing public API.
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.

---

Expand All @@ -46,13 +46,16 @@ The project started around 2014 and was later published under the MIT License. I
* 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
Expand Down Expand Up @@ -220,12 +223,24 @@ print(stats.stvF(values)) -- sample standard deviation
| `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
Expand Down Expand Up @@ -337,6 +352,30 @@ print(stats.choice({"first", "second", "third"})) -- first
stats.reset_rng()
```

### Student's t random variable

```lua
local stats = require("luasf")

print(stats.student_t(10))
```

### Simple linear regression

```lua
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
Expand All @@ -353,6 +392,7 @@ LuaSF/
distributions.lua
bivariate.lua
probability.lua
regression.lua
validation.lua
rng.lua
spec/
Expand All @@ -362,6 +402,8 @@ LuaSF/
test_bivariate.lua
test_shape.lua
test_probability.lua
test_student_t.lua
test_regression.lua
examples/
dice_simulation.lua
normal_quality_control.lua
Expand All @@ -374,6 +416,8 @@ LuaSF/
covariance_correlation.lua
skewness_kurtosis.lua
probability_helpers.lua
student_t_distribution.lua
simple_linear_regression.lua
docs/
api.md
.github/
Expand All @@ -387,6 +431,7 @@ LuaSF/
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
Expand All @@ -409,28 +454,34 @@ eval "$(luarocks path --local)"
Run tests:

```bash
lua spec/test_stats.lua
lua spec/test_distributions.lua
lua spec/test_sampling.lua
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

```bash
lua examples/binomial_coin_flips.lua
lua examples/bootstrap_mean.lua
lua examples/covariance_correlation.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/normal_quality_control.lua
lua examples/poisson_arrivals.lua
lua examples/binomial_coin_flips.lua
lua examples/bootstrap_mean.lua
lua examples/covariance_correlation.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
```

---
Expand All @@ -450,24 +501,26 @@ lua examples/probability_helpers.lua
* Summary statistics helpers
* Shape statistics helpers
* Bivariate statistics helpers
* Probability helpers
* Probability and combinatorics helpers
* Sampling utilities
* Deterministic simulation support
* Student's t random variable generator
* Formula-based simple linear regression summaries
* LuaRocks publishing

### Planned
### Possible future work

* Lightweight cross-reference with LuaHMF
* More distribution and simulation examples
* Optional simple formula-based regression summaries, without turning LuaSF into a machine learning framework
* Lightweight cross-reference with LuaHMF
* Carefully scoped confidence interval or critical value helpers

---

## Scope

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

Optimization-based modeling, machine learning workflows, model training pipelines, and non-linear regression are intentionally outside the current scope of LuaSF.
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.

---

Expand Down
Loading
Loading