Modularize LuaSF and add bivariate statistics

[HubertRonald]

Summary

This PR prepares LuaSF for v0.5.0 by modularizing the internal source layout and adding bivariate statistics helpers.

The goal is to make the codebase easier to maintain and extend while preserving the existing public API, legacy function names, compatibility entry points, and LuaRocks usage.

What changed

Modular source layout

Refactored the previous single-file implementation into smaller internal modules under src/luasf/:

• 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 keeps the public usage stable:

local stats = require("luasf")

Added bivariate statistics

Added the following modern API helpers:

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

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

correlation(x, y) and pearson(x, y) provide Pearson correlation.

Added tests

Added bivariate statistics tests:

• spec/test_bivariate.lua

The tests cover:

• Positive covariance
• Positive correlation
• Negative correlation
• pearson(x, y) alias
• Array length validation
• Constant-vector validation for correlation

Added example

Added a new example:

• examples/covariance_correlation.lua

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

Updated CI

Updated CI to include:

lua spec/test_bivariate.lua
lua examples/covariance_correlation.lua

Rockspec organization

Moved rockspec files into a dedicated rockspec/ directory.

This keeps package metadata better organized as LuaSF continues to release new versions.

Documentation

Updated documentation for the modular layout and bivariate statistics:

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

Compatibility notes

This PR does not remove or rename existing public functions.

Legacy API names remain available, including:

stats.sumF(array)
stats.avF(array)
stats.stvF(array)
stats.frecuencyF(array)
stats.nomalVA(mu, sig)
stats.normalVA(mu, sig)
stats.normal_inv_D(p, mu, sig)
stats.bernoulliVA(p)
stats.unifVA(min, max)
stats.expoVA(beta)
stats.weibullVA(alpha, beta)
stats.erlangVA(n, lambda)
stats.trianVA(a, b, c)
stats.binomialVA(n, p)
stats.geometricVA(p)
stats.poissonVA(lambda)
stats.chiSquareVA(n)
stats.gamVA(alpha, lambda)
stats.lognoVA(m, s)
stats.lognoRandVA(m, s)

Compatibility entry points also remain available:

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

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

Release target

This PR prepares LuaSF for:

v0.5.0 - Modularization and Bivariate Statistics

Scope note

This release keeps LuaSF focused on lightweight statistics, probability, random variables, sampling, and simulation utilities.

Machine learning workflows, optimization-based modeling, non-linear regression, and training pipelines remain outside the current scope of LuaSF.