Add rank and percentile rank statistics

Author: roberto-butti

CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 1.5.1 - 2026-05-12
+- Adding `rank()` method for assigning 1-based ranks to data points, with support for `average`, `min`, `max`, `dense`, and `ordinal` tie strategies
+- Adding `percentileRank()` method for calculating the percentile position of a value, with `weak`, `strict`, `mean`, and `rank` variants
+- Adding fluent `Statistics::rank()` and `Statistics::percentileRank()` wrapper methods
+- Fixing `Statistics::tTestPaired()` to preserve the original input order for paired observations
+- Updating README documentation and examples for ranking and percentile-rank usage
+- Improving `Statistics` test coverage for two-sample and paired t-test wrappers
+
 ## 1.5.0 - 2026-03-07
 - Adding `logarithmicRegression()`, `powerRegression()`, and `exponentialRegression()` methods for non-linear regression models
 

README.md

@@ -79,6 +79,8 @@ The various mathematical statistics are listed below:
 | `thirdQuartile()` | 3rd quartile, is the value at which 75 percent of the data is below it |
 | `firstQuartile()` | first quartile, is the value at which 25 percent of the data is below it |
 | `percentile()` | value at any percentile (0–100) with linear interpolation |
+| `rank()` | rank each data point, with configurable tie handling |
+| `percentileRank()` | percentile position of a value within a dataset |
 | `pstdev()` | Population standard deviation |
 | `stdev()` | Sample standard deviation |
 | `sem()` | Standard error of the mean (SEM) — measures precision of the sample mean |
@@ -335,6 +337,45 @@ $value = Stat::percentile([10, 20, 30, 40, 50, 60, 70, 80, 90, 100], 90);
 // 91.0
 ```
 
+#### Stat::rank( array $data, string $method = Stat::RANK_AVERAGE )
+Return 1-based ranks for each data point, preserving the original array keys.
+
+The `$method` parameter controls how tied values are ranked:
+- `Stat::RANK_AVERAGE` (default): tied values receive the average rank.
+- `Stat::RANK_MIN`: tied values receive the lowest rank in the tied group.
+- `Stat::RANK_MAX`: tied values receive the highest rank in the tied group.
+- `Stat::RANK_DENSE`: tied values receive the same rank and ranks do not skip numbers.
+- `Stat::RANK_ORDINAL`: tied values are ranked by their sorted order, preserving input order inside ties.
+
+```php
+use HiFolks\Statistics\Stat;
+
+$ranks = Stat::rank([10, 20, 20, 30]);
+// [1, 2.5, 2.5, 4]
+
+$ranks = Stat::rank([10, 20, 20, 30], Stat::RANK_DENSE);
+// [1, 2, 2, 3]
+```
+
+#### Stat::percentileRank( array $data, int|float $value, string $kind = Stat::PERCENTILE_RANK_WEAK, ?int $round = null )
+Return the percentile position of a value within a dataset.
+
+The `$kind` parameter controls the calculation:
+- `Stat::PERCENTILE_RANK_WEAK` (default): percentage of values less than or equal to the value.
+- `Stat::PERCENTILE_RANK_STRICT`: percentage of values strictly less than the value.
+- `Stat::PERCENTILE_RANK_MEAN`: average of weak and strict percentile ranks.
+- `Stat::PERCENTILE_RANK_RANK`: average percentage rank for exact matches, falling back to mean when the value is absent.
+
+```php
+use HiFolks\Statistics\Stat;
+
+$rank = Stat::percentileRank([10, 20, 20, 30, 40], 20);
+// 60.0
+
+$rank = Stat::percentileRank([10, 20, 20, 30, 40], 20, Stat::PERCENTILE_RANK_STRICT);
+// 20.0
+```
+
 #### Stat::pstdev( array $data )
 Return the **Population** Standard Deviation, a measure of the amount of variation or dispersion of a set of values.
 A low standard deviation indicates that the values tend to be close to the mean of the set, while a high standard deviation indicates that the values are spread out over a wider range.

TODO.md

@@ -1,31 +1,56 @@
 ## Missing Functions
 
-
-
-
-### Correlation & Regression
-
-
-- Kendall tau correlation - another rank-based correlation
-- Multiple/polynomial regression
-
-### Hypothesis Testing
-
-- ~~T-test (two-sample, paired) — one-sample is done~~ DONE: `tTestTwoSample()` (Welch's) and `tTestPaired()`
-- Chi-squared test
-
-### Other Distributions (beyond Normal)
-
-- Chi-squared distribution
-- Binomial distribution
-- Poisson distribution
-- Uniform distribution
-- Exponential distribution
-
-
-
-
-### Ranking & Order Statistics
-
-- Rank - assign ranks to data points
-- Percentile rank - what percentile a given value falls at
+### Priority 1: Ranking & Order Statistics
+
+- DONE: `rank()` - assign ranks to data points.
+  - Supports tie strategies: `average`, `min`, `max`, `dense`, `ordinal`.
+- DONE: `percentileRank()` - calculate what percentile a given value falls at.
+  - Supports `weak`, `strict`, `mean`, and `rank` variants.
+
+### Priority 2: Correlation
+
+- `kendallTau()` - Kendall tau rank correlation.
+  - Useful for ordinal data and small samples.
+  - Complements the existing Pearson and Spearman support in `correlation()`.
+- Consider extending `correlation()` with a Kendall method option.
+
+### Priority 3: Hypothesis Testing
+
+- ~~T-test (two-sample, paired) - one-sample is done~~ DONE: `tTestTwoSample()` (Welch's) and `tTestPaired()`.
+- `chiSquaredTest()` - chi-squared goodness-of-fit test.
+- `chiSquaredIndependence()` - chi-squared test for contingency tables.
+
+### Priority 4: Distributions
+
+- `ChiSquaredDist`
+  - Needed for chi-squared tests.
+  - Include `pdf()`, `cdf()`, `invCdf()` if practical, mean, variance.
+- `BinomialDist`
+  - Include `pmf()`, `cdf()`, mean, variance, samples.
+- `PoissonDist`
+  - Include `pmf()`, `cdf()`, mean, variance, samples.
+- `ExponentialDist`
+  - Include `pdf()`, `cdf()`, `invCdf()`, mean, variance, samples.
+- `UniformDist`
+  - Include `pdf()`, `cdf()`, `invCdf()`, mean, variance, samples.
+
+### Priority 5: Statistics Wrapper Completeness
+
+Add fluent `Statistics` wrapper methods for existing `Stat` APIs where useful:
+
+- `correlation()`
+- `covariance()`
+- `linearRegression()`
+- `logarithmicRegression()`
+- `powerRegression()`
+- `exponentialRegression()`
+- `rSquared()`
+- `kde()`
+- `kdeRandom()`
+
+### Priority 6: Regression & Modeling
+
+- `polynomialRegression()` - fit polynomial models of configurable degree.
+- `multipleLinearRegression()` - fit linear models with multiple predictors.
+  - This likely needs a small matrix/linear-algebra helper layer.
+  - Add after simpler ranking, correlation, testing, and distribution work.