lua examples/probability_helpers.lua

.github/workflows/ci.yml

@@ -12,6 +12,7 @@ on:
       - "examples/**"
       - "LuaSF.lua"
       - "LuaStat.lua"
+      - "rockspec/**"
       - "*.rockspec"
       - ".github/workflows/ci.yml"
 
@@ -58,6 +59,7 @@ jobs:
           lua spec/test_sampling.lua
           lua spec/test_bivariate.lua
           lua spec/test_shape.lua
+          lua spec/test_probability.lua
 
       - name: Run examples
         run: |
@@ -70,4 +72,5 @@ jobs:
           lua examples/binomial_coin_flips.lua
           lua examples/bootstrap_mean.lua
           lua examples/covariance_correlation.lua
-          lua examples/skewness_kurtosis.lua
+          lua examples/skewness_kurtosis.lua
+          lua examples/probability_helpers.lua

.github/workflows/publish-luarocks.yml

@@ -6,7 +6,7 @@ on:
       rockspec:
         description: "Rockspec file to validate or publish"
         required: true
-        default: "rockspec/luasf-0.6.0-1.rockspec"
+        default: "rockspec/luasf-0.7.0-1.rockspec"
         type: string
       publish:
         description: "Publish to LuaRocks after validation"
@@ -50,6 +50,9 @@ jobs:
       - name: Test shape statistics entry point
         run: lua -e 'local stats = require("luasf"); print(stats.skewness({1,2,3,4,5})); print(stats.kurtosis({1,2,3,4,5}))'
 
+      - 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 LuaSF compatibility entry point
         run: lua -e 'local stats = require("LuaSF"); print(stats.sumF({1,2,3}))'
 

CHANGELOG.md

@@ -10,15 +10,52 @@ This project follows a lightweight changelog format inspired by [Keep a Changelo
 
 ### Planned
 
-* Continue improving examples and documentation.
 * Explore a lightweight cross-reference with LuaHMF as a related pure-Lua math helper project.
-* Evaluate future probability helpers such as `factorial`, `combinations`, and `permutations`.
+* Add more distribution and simulation examples.
 * Evaluate optional formula-based simple regression summaries while keeping ML workflows outside the current scope.
-* Add more distribution examples and simulation-oriented examples.
 
 ---
 
-## [0.6.0] - 2026-06-07
+## [0.7.0] - 2026-06-07
+
+### Added
+
+* Implemented `src/luasf/probability.lua` with probability and combinatorics helpers.
+* Added `factorial(n)`.
+* Added `permutations(n, r)` for ordered selections without repetition.
+* Added `combinations(n, r)` for unordered selections without repetition.
+* Added `permutations_with_repetition(n, r)` for ordered selections with repetition.
+* Added `combinations_with_repetition(n, r)` for unordered selections with repetition.
+* Added `permutations_without_repetition(n, r)` as an alias for `permutations(n, r)`.
+* Added `combinations_without_repetition(n, r)` as an alias for `combinations(n, r)`.
+* Added `nPr(n, r)` as an alias for `permutations(n, r)`.
+* Added `nCr(n, r)` as an alias for `combinations(n, r)`.
+* Added `multiset_permutations(counts)` for distinct arrangements of repeated item groups.
+* Added `spec/test_probability.lua`.
+* Added `examples/probability_helpers.lua`.
+* Added `rockspec/luasf-0.7.0-1.rockspec`.
+
+### Changed
+
+* Updated CI to run probability helper tests and the new probability example.
+* Updated the LuaRocks publishing workflow default rockspec path to `rockspec/luasf-0.7.0-1.rockspec`.
+* Updated README, API documentation, changelog, and contribution notes for probability helpers.
+
+### Notes
+
+Probability helpers distinguish common combinatorics cases:
+
+* Ordered selections without repetition: `permutations(n, r)` and `nPr(n, r)`.
+* Ordered selections with repetition: `permutations_with_repetition(n, r)`.
+* Unordered selections without repetition: `combinations(n, r)` and `nCr(n, r)`.
+* Unordered selections with repetition: `combinations_with_repetition(n, r)`.
+* Repeated item arrangements: `multiset_permutations(counts)`.
+
+Lua numbers may lose precision for very large combinatorial values. LuaSF intentionally keeps these helpers lightweight and dependency-free instead of adding big integer support.
+
+---
+
+## [0.6.0] - 2026-06-08
 
 ### Added
 

CONTRIBUTING.md

@@ -14,6 +14,7 @@ LuaSF aims to provide:
 * Summary statistics helpers
 * Shape statistics helpers such as skewness and kurtosis
 * Bivariate statistics helpers such as covariance and correlation
+* Probability and combinatorics helpers
 * Pseudo-random variable generation
 * Sampling utilities
 * A small and readable Lua codebase
@@ -153,6 +154,7 @@ lua spec/test_distributions.lua
 lua spec/test_sampling.lua
 lua spec/test_bivariate.lua
 lua spec/test_shape.lua
+lua spec/test_probability.lua
 ```
 
 Run examples:
@@ -168,10 +170,45 @@ lua examples/binomial_coin_flips.lua
 lua examples/bootstrap_mean.lua
 lua examples/covariance_correlation.lua
 lua examples/skewness_kurtosis.lua
+lua examples/probability_helpers.lua
 ```
 
 ---
 
+## Probability helper guidelines
+
+Probability and combinatorics helpers should live in:
+
+```text
+src/luasf/probability.lua
+```
+
+Tests should live in:
+
+```text
+spec/test_probability.lua
+```
+
+Examples should live in:
+
+```text
+examples/probability_helpers.lua
+```
+
+Probability and combinatorics helpers should remain lightweight and formula-based.
+
+For combinatorics helpers, please be explicit about whether order matters and whether repetition is allowed:
+
+* `permutations(n, r)` for ordered selections without repetition.
+* `combinations(n, r)` for unordered selections without repetition.
+* `permutations_with_repetition(n, r)` for ordered selections with repetition.
+* `combinations_with_repetition(n, r)` for unordered selections with repetition.
+* `multiset_permutations(counts)` for arrangements of repeated item groups.
+
+Please keep in mind that Lua numbers may lose precision for very large combinatorial values. LuaSF should remain dependency-free and should not add big integer libraries unless the project scope changes significantly.
+
+---
+
 ## LuaRocks packaging
 
 Rockspec files are kept under:
@@ -185,8 +222,8 @@ When adding new internal modules, update the next rockspec draft so LuaRocks kno
 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
+luarocks lint rockspec/luasf-0.7.0-1.rockspec
+luarocks make rockspec/luasf-0.7.0-1.rockspec
 ```
 
 Publishing should remain manual and intentional.
@@ -246,6 +283,9 @@ Before opening a pull request, please check:
 * New behavior includes at least one test.
 * 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.
+* CI workflows are updated when new tests or examples are added.
+
 
 ---
 
@@ -258,6 +298,7 @@ Prefer:
 * Small functions
 * Minimal dependencies
 * Compatibility with Lua 5.1+
+* Explicit validation for public helpers
 * Formula-based helpers when appropriate
 
 Avoid:
@@ -272,12 +313,6 @@ Avoid:
 
 ## Future scope
 
-Potential future additions include:
-
-* `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.
 
 ---

README.md

@@ -31,9 +31,9 @@
 
 **LuaSF** stands for **Lua Statistics Functions**.
 
-LuaSF is a small, lightweight, pure-Lua library for descriptive statistics, 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, and pseudo-random variable generation.
 
-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 module structure, additional statistics helpers, sampling utilities, 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, and LuaRocks packaging while preserving the existing public API.
 
 ---
 
@@ -47,6 +47,7 @@ The project started around 2014 and was later published under the MIT License. I
 * Basic descriptive statistics
 * Summary statistics helpers
 * Bivariate statistics helpers
+* Probability and combinatorics helpers
 * Sampling utilities
 * Discrete and continuous pseudo-random variables
 * Compatible with the existing public LuaSF API
@@ -111,6 +112,8 @@ print(stats.stddev(values))   -- sample standard deviation
 print(stats.median(values))   -- 3
 print(stats.variance(values)) -- sample variance
 print(stats.summary(values).count) -- 5
+print(stats.factorial(5))     -- 120
+print(stats.combinations(5, 2)) -- 10
 ```
 
 Legacy names are still available:
@@ -172,6 +175,23 @@ print(stats.stvF(values)) -- sample standard deviation
 | `correlation(x, y)` | Pearson correlation coefficient |
 | `pearson(x, y)` | Alias for `correlation(x, y)` |
 
+### Probability helpers
+
+| Function                                | Description                                                            |
+| --------------------------------------- | ---------------------------------------------------------------------- |
+| `factorial(n)`                          | Factorial of a non-negative integer                                    |
+| `permutations(n, r)`                    | Ordered selections without repetition, also known as `nPr`             |
+| `combinations(n, r)`                    | Unordered selections without repetition, also known as `nCr`           |
+| `permutations_with_repetition(n, r)`    | Ordered selections with repetition, calculated as `n^r`                |
+| `combinations_with_repetition(n, r)`    | Unordered selections with repetition, calculated as `C(n + r - 1, r)`  |
+| `permutations_without_repetition(n, r)` | Alias for `permutations(n, r)`                                         |
+| `combinations_without_repetition(n, r)` | Alias for `combinations(n, r)`                                         |
+| `multiset_permutations(counts)`         | Distinct arrangements of repeated item counts                          |
+| `nPr(n, r)`                             | Alias for `permutations(n, r)`                                         |
+| `nCr(n, r)`                             | Alias for `combinations(n, r)`                                         |
+
+> These helpers use Lua numbers. Very large inputs may exceed the practical numeric precision or range of the Lua runtime.
+
 ### Sampling utilities
 
 | Function                          | Description                                    |
@@ -341,6 +361,7 @@ LuaSF/
     test_sampling.lua
     test_bivariate.lua
     test_shape.lua
+    test_probability.lua
   examples/
     dice_simulation.lua
     normal_quality_control.lua
@@ -352,6 +373,7 @@ LuaSF/
     bootstrap_mean.lua
     covariance_correlation.lua
     skewness_kurtosis.lua
+    probability_helpers.lua
   docs/
     api.md
   .github/
@@ -364,6 +386,7 @@ LuaSF/
     luasf-0.4.0-1.rockspec
     luasf-0.5.0-1.rockspec
     luasf-0.6.0-1.rockspec
+    luasf-0.7.0-1.rockspec
   LuaSF.lua
   LuaStat.lua
   README.md
@@ -390,6 +413,7 @@ lua spec/test_stats.lua
 lua spec/test_distributions.lua
 lua spec/test_sampling.lua
 lua spec/test_bivariate.lua
+lua spec/test_probability.lua
 ```
 
 ---
@@ -406,6 +430,7 @@ 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
 ```
 
 ---
@@ -423,17 +448,18 @@ lua examples/covariance_correlation.lua
 * API documentation
 * Additional statistics helpers
 * Summary statistics helpers
+* Shape statistics helpers
 * Bivariate statistics helpers
+* Probability helpers
 * Sampling utilities
 * Deterministic simulation support
 * LuaRocks publishing
 
 ### Planned
 
-* More distribution and simulation examples
 * Lightweight cross-reference with LuaHMF
-* Future probability helpers such as `factorial`, `combinations`, and `permutations`
-* Optional formula-based simple regression summaries
+* More distribution and simulation examples
+* Optional simple formula-based regression summaries, without turning LuaSF into a machine learning framework
 
 ---