LuaSF v0.5.0 - Modularization and Bivariate Statistics

LuaSF v0.5.0 - Modularization and Bivariate Statistics

This release reorganizes LuaSF — Lua Statistics Functions into a modular internal source layout and adds bivariate statistics helpers.

It builds on v0.4.0, which introduced summary statistics helpers and simulation-oriented examples.

Added

Bivariate statistics

Added new helpers for paired numeric arrays:

• covariance(x, y)
• correlation(x, y)
• pearson(x, y)

covariance(x, y) uses the sample covariance formula with n - 1.

correlation(x, y) computes Pearson correlation.

pearson(x, y) is provided as a readable alias for Pearson correlation.

Example:

local stats = require("luasf")

local x = {1, 2, 3, 4, 5}
local y = {2, 4, 6, 8, 10}

print(stats.covariance(x, y))
print(stats.correlation(x, y))
print(stats.pearson(x, y))

Bivariate tests

Added:

• spec/test_bivariate.lua

The new tests cover covariance, positive correlation, negative correlation, alias behavior, and validation errors.

Bivariate example

Added:

• examples/covariance_correlation.lua

This example demonstrates covariance and correlation using a simple relationship between study hours and exam scores.

Changed

Modular source layout

LuaSF is now internally organized into smaller modules:

• src/luasf/core.lua
• src/luasf/descriptive.lua
• src/luasf/sampling.lua
• src/luasf/distributions.lua
• src/luasf/bivariate.lua
• src/luasf/probability.lua
• src/luasf/validation.lua
• src/luasf/rng.lua

The public facade remains:

• src/luasf.lua

This preserves the main public entry point:

local stats = require("luasf")

Canonical module usage

Tests and examples now use the canonical LuaSF module name:

local stats = require("luasf")

Rockspec organization

Rockspec files were moved into a dedicated directory:

rockspec/

This prepares the project for cleaner future LuaRocks releases.

Documentation

Updated documentation for the modular layout and bivariate statistics:

• Updated README.md.
• Updated docs/api.md.
• Updated CHANGELOG.md.
• Updated CONTRIBUTING.md.

Testing

Tested locally with:

lua spec/test_stats.lua
lua spec/test_distributions.lua
lua spec/test_sampling.lua
lua spec/test_bivariate.lua

Examples can be run with:

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

Compatibility

This release does not remove or rename existing public functions.

Existing users can continue using:

local stats = require("luasf")
local stats = require("LuaSF")
local stats = require("LuaStat")

Legacy function names remain available.

Scope note

LuaSF remains focused on lightweight statistics, probability, random variables, sampling, and simulation utilities.

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