Add shape statistics helpers

[HubertRonald]

Summary

This PR prepares LuaSF for v0.6.0 by adding shape statistics helpers focused on distribution shape analysis.

It builds on the modular source layout introduced in v0.5.0 and keeps the public API stable while adding new descriptive statistics capabilities.

What changed

Added shape statistics helpers

Added a new internal module:

src/luasf/shape.lua

The module adds:

stats.central_moment(array, order)
stats.skewness(array)
stats.kurtosis(array)
stats.excess_kurtosis(array)

These helpers make it possible to analyze the shape of numeric distributions using central moments, skewness, kurtosis, and excess kurtosis.

Updated public facade

Updated:

src/luasf.lua

to expose the new shape statistics helpers through the public LuaSF API:

local stats = require("luasf")

Added tests

Added:

spec/test_shape.lua

The new tests cover:

• Central moment calculation
• Skewness
• Kurtosis
• Excess kurtosis
• Validation for invalid inputs
• Behavior for constant arrays where shape statistics are undefined

Added example

Added:

examples/skewness_kurtosis.lua

This example demonstrates how to calculate skewness, kurtosis, and excess kurtosis for simple datasets.

Added LuaRocks rockspec

Added:

rockspec/luasf-0.6.0-1.rockspec

The rockspec prepares LuaSF for the v0.6.0 LuaRocks package release.

Updated workflows

Updated GitHub Actions workflows to include the new shape statistics test and example:

lua spec/test_shape.lua
lua examples/skewness_kurtosis.lua

Updated files:

.github/workflows/ci.yml
.github/workflows/publish-luarocks.yml

Updated documentation

Updated documentation for the new helpers:

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

Compatibility notes

This PR does not remove or rename existing public functions.

Existing usage remains supported:

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

Legacy function names remain available.

Testing

Tested locally with:

lua spec/test_stats.lua
lua spec/test_distributions.lua
lua spec/test_sampling.lua
lua spec/test_bivariate.lua
lua spec/test_shape.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
lua examples/skewness_kurtosis.lua

Release target

This PR prepares LuaSF for:

v0.6.0 - Shape Statistics

Scope note

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

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