Modularize LuaSF and add bivariate statistics

.github/workflows/ci.yml

@@ -67,3 +67,5 @@ jobs:
           lua examples/poisson_arrivals.lua
           lua examples/binomial_coin_flips.lua
           lua examples/bootstrap_mean.lua
+          lua spec/test_bivariate.lua
+          lua examples/covariance_correlation.lua

CHANGELOG.md

@@ -10,6 +10,44 @@ This project follows a lightweight changelog format inspired by [Keep a Changelo
 
 ### Added
 
+* Added modular internal source layout under `src/luasf/`.
+* Added `src/luasf/core.lua`.
+* Added `src/luasf/validation.lua`.
+* Added `src/luasf/rng.lua`.
+* Added `src/luasf/descriptive.lua`.
+* Added `src/luasf/sampling.lua`.
+* Added `src/luasf/distributions.lua`.
+* Added `src/luasf/bivariate.lua`.
+* Added `src/luasf/probability.lua` as a placeholder for future probability helpers.
+* Added `covariance(x, y)`.
+* Added `correlation(x, y)`.
+* Added `pearson(x, y)` as an alias for `correlation(x, y)`.
+* Added `spec/test_bivariate.lua`.
+* Added `examples/covariance_correlation.lua`.
+* Added `rockspec/luasf-0.5.0-1.rockspec` as the next LuaRocks release draft.
+
+### Changed
+
+* Kept `src/luasf.lua` as the public facade module.
+* Preserved the existing public API while moving implementation details into smaller internal modules.
+* Moved LuaRocks specification files into the `rockspec/` directory.
+* Updated documentation to describe the modular layout and bivariate statistics helpers.
+* Updated CI expectations to include bivariate tests and the covariance/correlation example.
+
+### Planned
+
+* Add shape statistics helpers such as `skewness(array)` and `kurtosis(array)`.
+* Explore future probability helpers such as `factorial(n)`, `combinations(n, r)`, and `permutations(n, r)`.
+* Explore a lightweight cross-reference with LuaHMF as a related pure-Lua math helper project.
+* Consider simple formula-based regression summaries later, without turning LuaSF into a machine learning framework.
+* Add more distribution examples and simulation-oriented examples.
+
+---
+
+## [0.4.0] - 2026-06-04
+
+### Added
+
 * Added `mode(array)`.
 * Added `range(array)`.
 * Added `iqr(array)`.
@@ -20,14 +58,13 @@ This project follows a lightweight changelog format inspired by [Keep a Changelo
 * Added `examples/poisson_arrivals.lua`.
 * Added `examples/binomial_coin_flips.lua`.
 * Added `examples/bootstrap_mean.lua`.
+* Added `luasf-0.4.0-1.rockspec`.
 
-### Planned
+### Documentation
 
-* 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`.
+* Updated `README.md`.
+* Updated `docs/api.md`.
+* Updated `CHANGELOG.md`.
 
 ---
 

CONTRIBUTING.md

@@ -51,6 +51,45 @@ Modern aliases can be added, but legacy names should not be removed.
 
 ---
 
+## Source layout
+
+LuaSF exposes a stable public facade:
+
+```lua
+local stats = require("luasf")
+```
+
+The implementation is modularized under `src/luasf/`:
+
+```text
+src/
+  luasf.lua
+  luasf/
+    core.lua
+    descriptive.lua
+    sampling.lua
+    distributions.lua
+    bivariate.lua
+    probability.lua
+    validation.lua
+    rng.lua
+```
+
+When adding new functionality, prefer placing it in the most relevant internal module instead of growing `src/luasf.lua`.
+
+Recommended module ownership:
+
+* `descriptive.lua`: univariate descriptive statistics
+* `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
+* `validation.lua`: reusable input validation helpers
+* `rng.lua`: random generator and seed helpers
+* `core.lua`: small reusable internal utilities
+
+---
+
 ## Development setup
 
 Clone the repository:
@@ -72,6 +111,8 @@ Run tests:
 ```bash
 lua spec/test_stats.lua
 lua spec/test_distributions.lua
+lua spec/test_sampling.lua
+lua spec/test_bivariate.lua
 ```
 
 Run examples:
@@ -80,10 +121,37 @@ Run examples:
 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
+lua examples/covariance_correlation.lua
 ```
 
 ---
 
+## LuaRocks packaging
+
+Rockspec files are kept under:
+
+```text
+rockspec/
+```
+
+When adding new internal modules, update the next rockspec draft so LuaRocks knows how to package them.
+
+Before publishing, validate locally or through GitHub Actions:
+
+```bash
+luarocks lint rockspec/luasf-0.5.0-1.rockspec
+luarocks make rockspec/luasf-0.5.0-1.rockspec
+```
+
+Publishing should remain manual and intentional.
+
+---
+
 ## Branch naming
 
 Recommended branch names:
@@ -98,7 +166,8 @@ test/short-description
 Examples:
 
 ```text
-feature/add-median
+feature/modular-bivariate-stats
+feature/add-skewness-kurtosis
 fix/triangular-random-variable
 docs/improve-api
 test/add-distribution-ranges
@@ -113,6 +182,10 @@ Use clear and direct commit messages.
 Examples:
 
 ```text
+Modularize LuaSF source layout
+Add bivariate statistics helpers
+Add bivariate statistics tests
+Add covariance and correlation example
 Fix triangular random variable implementation
 Add frequency table tests
 Improve README examples
@@ -130,6 +203,7 @@ Before opening a pull request, please check:
 * Examples still run.
 * New functions include simple documentation.
 * New behavior includes at least one test.
+* New modules are included in the rockspec draft when needed.
 * Code remains readable and dependency-light.
 
 ---
@@ -143,13 +217,29 @@ Prefer:
 * Small functions
 * Minimal dependencies
 * Compatibility with Lua 5.1+
+* Formula-based helpers when appropriate
 
 Avoid:
 
 * Large rewrites without tests
 * Breaking legacy names
 * Adding native dependencies
 * Overcomplicating the API
+* Turning LuaSF into a machine learning framework
+
+---
+
+## Future scope
+
+Potential future additions include:
+
+* `skewness(array)`
+* `kurtosis(array)`
+* `factorial(n)`
+* `combinations(n, r)`
+* `permutations(n, r)`
+
+Simple formula-based regression summaries may be considered later, but optimization-based models and ML workflows are outside the current scope.
 
 ---