feat(linfa-clustering): add K-Modes clustering algorithm

[ethqnol]

Adds the K-Modes clustering algorithm for categorical data (Huang [1997, 1998]) to linfa-clustering.

Features & Implementation

• KModes algorithm
• Centroid Initialization Strategies:
  • KModesInit::Cao (Cao et al. [2009]): Density and dissimilarity-based initialization (default).
  • KModesInit::Huang (Huang [1998]): Frequency distribution sampling mapped to valid observations.
  • KModesInit::Random: Random sampling without replacement.
  • KModesInit::Precomputed: Precomputed mode matrices.
• Implements Linfa traits (Fit, PredictInplace, Predict, and ParamGuard) and generics
• Serde: Supports serde

Tests

• 31 tests covering all initializations, edge cases, numeric primitives, char/bool, and custom enums.
• 0 compiler warnings, 0 clippy warnings (-D warnings).

Benchmarks

Context

1. Battery power
2. Power saving mode enabled
3. Computer was not idle
4. No overheating
5. System Specs: Lenovo ThinkPad T14 Gen 6, 32 GiB Memory, AMD Ryzen™ AI 5 PRO 340, Fedora Linux 44 (Workstation Edition)

Bench Command Run

k_modes/Cao/1000x5      time:   [443.50 µs 446.40 µs 449.53 µs]
Found 18 outliers among 200 measurements (9.00%)
  6 (3.00%) high mild
  12 (6.00%) high severe
k_modes/Huang/1000x5    time:   [275.47 µs 276.79 µs 278.27 µs]
Found 5 outliers among 200 measurements (2.50%)
  2 (1.00%) high mild
  3 (1.50%) high severe
k_modes/Random/1000x5   time:   [198.50 µs 199.39 µs 200.34 µs]
Found 15 outliers among 200 measurements (7.50%)
  4 (2.00%) high mild
  11 (5.50%) high severe
k_modes/Cao/10000x5     time:   [4.4744 ms 4.4933 ms 4.5127 ms]
Found 1 outliers among 200 measurements (0.50%)
  1 (0.50%) high mild
k_modes/Huang/10000x5   time:   [2.6658 ms 2.6754 ms 2.6862 ms]
Found 26 outliers among 200 measurements (13.00%)
  12 (6.00%) high mild
  14 (7.00%) high severe
k_modes/Random/10000x5  time:   [1.9282 ms 1.9344 ms 1.9409 ms]
Found 4 outliers among 200 measurements (2.00%)
  4 (2.00%) high mild
k_modes/Cao/20000x5     time:   [8.7388 ms 8.7966 ms 8.8637 ms]
Found 20 outliers among 200 measurements (10.00%)
  4 (2.00%) high mild
  16 (8.00%) high severe
k_modes/Huang/20000x5   time:   [5.2519 ms 5.2634 ms 5.2806 ms]
Found 6 outliers among 200 measurements (3.00%)
  3 (1.50%) high mild
  3 (1.50%) high severe
k_modes/Random/20000x5  time:   [3.7843 ms 3.7953 ms 3.8083 ms]
Found 11 outliers among 200 measurements (5.50%)
  3 (1.50%) high mild
  8 (4.00%) high severe
Benchmarking k_modes/Cao/1000x10: Warming up for 10.000 s
Warning: Unable to complete 200 samples in 10.0s. You may wish to increase target time to 17.1s, enable flat sampling, or reduce sample count to 100.
k_modes/Cao/1000x10     time:   [826.12 µs 826.94 µs 827.90 µs]
Found 25 outliers among 200 measurements (12.50%)
  3 (1.50%) low mild
  13 (6.50%) high mild
  9 (4.50%) high severe
Benchmarking k_modes/Huang/1000x10: Warming up for 10.000 s
Warning: Unable to complete 200 samples in 10.0s. You may wish to increase target time to 16.2s, enable flat sampling, or reduce sample count to 110.
k_modes/Huang/1000x10   time:   [816.65 µs 823.28 µs 832.01 µs]
Found 20 outliers among 200 measurements (10.00%)
  5 (2.50%) high mild
  15 (7.50%) high severe
Benchmarking k_modes/Random/1000x10: Warming up for 10.000 s
Warning: Unable to complete 200 samples in 10.0s. You may wish to increase target time to 13.0s, enable flat sampling, or reduce sample count to 120.
k_modes/Random/1000x10  time:   [648.65 µs 651.07 µs 655.27 µs]
Found 19 outliers among 200 measurements (9.50%)
  1 (0.50%) low severe
  4 (2.00%) low mild
  8 (4.00%) high mild
  6 (3.00%) high severe
k_modes/Cao/10000x10    time:   [8.1208 ms 8.1327 ms 8.1481 ms]
Found 1 outliers among 200 measurements (0.50%)
  1 (0.50%) high severe
k_modes/Huang/10000x10  time:   [4.3849 ms 4.3925 ms 4.4030 ms]
Found 2 outliers among 200 measurements (1.00%)
  1 (0.50%) high mild
  1 (0.50%) high severe
k_modes/Random/10000x10 time:   [4.9257 ms 4.9415 ms 4.9578 ms]
Found 1 outliers among 200 measurements (0.50%)
  1 (0.50%) high mild
k_modes/Cao/20000x10    time:   [16.348 ms 16.389 ms 16.435 ms]
Found 9 outliers among 200 measurements (4.50%)
  5 (2.50%) high mild
  4 (2.00%) high severe
k_modes/Huang/20000x10  time:   [8.8251 ms 8.8467 ms 8.8719 ms]
Found 2 outliers among 200 measurements (1.00%)
  2 (1.00%) high severe
k_modes/Random/20000x10 time:   [7.1454 ms 7.1971 ms 7.2607 ms]
Found 17 outliers among 200 measurements (8.50%)
  9 (4.50%) high mild
  8 (4.00%) high severe

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 78.80%. Comparing base (3b411a4) to head (3d4ab5f).

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #455      +/-   ##
==========================================
+ Coverage   77.93%   78.80%   +0.86%     
==========================================
  Files         104      107       +3     
  Lines        7547     7854     +307     
==========================================
+ Hits         5882     6189     +307     
  Misses       1665     1665              

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.