philiprehberger-math_kit 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bfd866aacb1af07326cd0543912f1d088dec7cc9c7c06f217709a7bbc31f79d1
-  data.tar.gz: f747448a80beda06245efebbff03f3fb043c042bf625c9b8a7512debb9847e1b
+  metadata.gz: e5160a941a8d5e202674e87876873e770f8c1977e9a16bcc3123e58a5a6b665d
+  data.tar.gz: b3ec9ac5e16e4defa442e6c9470065540da9acbbe4281884b034a66d91ec5b57
 SHA512:
-  metadata.gz: 6b8b029f141507b9cd791c070ae2d9f5cec3f228182a58caaaf1ad7fce42512a2c62d364e8d1a68d7b204e096590d392ebd341042ada39b50c0b35053ed06974
-  data.tar.gz: 6ec476f44f0728ef45b6ce64806be76544b39a5f4831d2897f7ea2fd9bb0f9959df4fa1f7fba7a61cd8f842f76976935b47301da3353da340f5916a96748c65e
+  metadata.gz: 75957977d35a9313b370f65ab8c9bc99fa267eb0b14e93a4c2e802ef671ea5926991e871fc8794724dd3c58c1dec49accbca4d34ab181dac5907c257a4fcf998
+  data.tar.gz: ef5a5f0e61a225e88b8a232da5e60472a7aad51c0512163eb82a5e85207977fce943388142fcaa210252d8a104392a472a7069fc16dc38e2b5e70b5d4d9027e2

data/CHANGELOG.md

@@ -7,6 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-04-21
+
+### Added
+- `Stats.sum_of_squares(values)` — sum of squared deviations from the mean, a building block for variance, regression residuals, and ANOVA; returns 0.0 for empty or single-element inputs
+
+## [0.4.0] - 2026-04-15
+
+### Added
+- `Numeric` module with common integer and value helpers
+- `Numeric.factorial(n)` for non-negative integer factorial (arbitrary precision)
+- `Numeric.fibonacci(n)` for the n-th Fibonacci number via iterative O(n)/O(1) computation
+- `Numeric.gcd(a, b)` for greatest common divisor (accepts negative inputs)
+- `Numeric.lcm(a, b)` for least common multiple (accepts negative inputs)
+- `Numeric.clamp(value, min, max)` for constraining a value to a range
+
 ## [0.3.0] - 2026-04-10
 
 ### Added
@@ -66,3 +81,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Linear interpolation between sorted points with extrapolation
 - Rounding modes: bankers (round half to even), ceiling, floor, truncate with precision
 - Simple moving average and exponential moving average
+
+[Unreleased]: https://github.com/philiprehberger/rb-math-kit/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/philiprehberger/rb-math-kit/compare/v0.3.0...v0.4.0
+[0.3.0]: https://github.com/philiprehberger/rb-math-kit/compare/v0.2.3...v0.3.0
+[0.2.3]: https://github.com/philiprehberger/rb-math-kit/compare/v0.2.2...v0.2.3
+[0.2.2]: https://github.com/philiprehberger/rb-math-kit/compare/v0.2.1...v0.2.2
+[0.2.1]: https://github.com/philiprehberger/rb-math-kit/compare/v0.2.0...v0.2.1
+[0.2.0]: https://github.com/philiprehberger/rb-math-kit/compare/v0.1.2...v0.2.0
+[0.1.2]: https://github.com/philiprehberger/rb-math-kit/compare/v0.1.1...v0.1.2
+[0.1.1]: https://github.com/philiprehberger/rb-math-kit/compare/v0.1.0...v0.1.1
+[0.1.0]: https://github.com/philiprehberger/rb-math-kit/releases/tag/v0.1.0

data/README.md

@@ -41,6 +41,7 @@ Philiprehberger::MathKit::Stats.stddev([2, 4, 4, 4, 5, 5, 7, 9])    # => 2.0
 Philiprehberger::MathKit::Stats.percentile([1, 2, 3, 4, 5], 50)      # => 3.0
 Philiprehberger::MathKit::Stats.sum([1, 2, 3])                # => 6
 Philiprehberger::MathKit::Stats.range([1, 5, 3, 9, 2])        # => 8
+Philiprehberger::MathKit::Stats.sum_of_squares([1, 2, 3])     # => 2.0
 ```
 
 ### Summary Statistics
@@ -138,6 +139,16 @@ Philiprehberger::MathKit::MovingAverage.simple([1, 2, 3, 4, 5], window: 3)
 Philiprehberger::MathKit::MovingAverage.exponential([1, 2, 3, 4, 5], alpha: 0.5) # => [1.0, 1.5, 2.25, 3.125, 4.0625]
 ```
 
+### Numeric Helpers
+
+```ruby
+Philiprehberger::MathKit::Numeric.factorial(5)      # => 120
+Philiprehberger::MathKit::Numeric.fibonacci(10)     # => 55
+Philiprehberger::MathKit::Numeric.gcd(12, 18)       # => 6
+Philiprehberger::MathKit::Numeric.lcm(4, 6)         # => 12
+Philiprehberger::MathKit::Numeric.clamp(42, 0, 10)  # => 10
+```
+
 ## API
 
 ### `Stats`
@@ -151,6 +162,7 @@ Philiprehberger::MathKit::MovingAverage.exponential([1, 2, 3, 4, 5], alpha: 0.5)
 | `.stddev(values, population: true)` | Standard deviation |
 | `.percentile(values, p)` | Percentile (0-100) with linear interpolation |
 | `.sum(values)` | Sum of values |
+| `.sum_of_squares(values)` | Sum of squared deviations from the mean (0.0 for empty/single input) |
 | `.range(values)` | Max - min |
 | `.skewness(values)` | Sample skewness (Fisher-Pearson) |
 | `.kurtosis(values)` | Sample excess kurtosis (Fisher definition) |
@@ -198,6 +210,16 @@ Philiprehberger::MathKit::MovingAverage.exponential([1, 2, 3, 4, 5], alpha: 0.5)
 | `.simple(values, window:)` | Simple moving average |
 | `.exponential(values, alpha:)` | Exponential moving average |
 
+### `Numeric`
+
+| Method | Description |
+|--------|-------------|
+| `.factorial(n)` | Factorial of a non-negative integer |
+| `.fibonacci(n)` | N-th Fibonacci number (0-indexed) |
+| `.gcd(a, b)` | Greatest common divisor of two integers |
+| `.lcm(a, b)` | Least common multiple of two integers |
+| `.clamp(value, min, max)` | Clamp a numeric value between min and max |
+
 ## Development
 
 ```bash

data/lib/philiprehberger/math_kit/numeric.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module MathKit
+    # Numeric helpers for common integer and value operations
+    module Numeric
+      class << self
+        # Factorial of a non-negative integer (n!)
+        #
+        # @param n [Integer] a non-negative integer
+        # @return [Integer] the factorial of n
+        # @raise [ArgumentError] if n is negative or not an Integer
+        def factorial(n)
+          raise ArgumentError, 'factorial requires an Integer' unless n.is_a?(Integer)
+          raise ArgumentError, 'factorial requires a non-negative integer' if n.negative?
+
+          (1..n).reduce(1, :*)
+        end
+
+        # N-th Fibonacci number (0-indexed: fibonacci(0) = 0, fibonacci(1) = 1)
+        #
+        # Uses an iterative algorithm for O(n) time and O(1) space.
+        #
+        # @param n [Integer] a non-negative index
+        # @return [Integer] the n-th Fibonacci number
+        # @raise [ArgumentError] if n is negative or not an Integer
+        def fibonacci(n)
+          raise ArgumentError, 'fibonacci requires an Integer' unless n.is_a?(Integer)
+          raise ArgumentError, 'fibonacci requires a non-negative integer' if n.negative?
+
+          a = 0
+          b = 1
+          n.times { a, b = b, a + b }
+          a
+        end
+
+        # Greatest common divisor of two integers (Euclidean algorithm)
+        #
+        # @param a [Integer] first integer
+        # @param b [Integer] second integer
+        # @return [Integer] the non-negative greatest common divisor
+        # @raise [ArgumentError] if either argument is not an Integer
+        def gcd(a, b)
+          raise ArgumentError, 'gcd requires Integer arguments' unless a.is_a?(Integer) && b.is_a?(Integer)
+
+          a.abs.gcd(b.abs)
+        end
+
+        # Least common multiple of two integers
+        #
+        # @param a [Integer] first integer
+        # @param b [Integer] second integer
+        # @return [Integer] the non-negative least common multiple (0 if either is 0)
+        # @raise [ArgumentError] if either argument is not an Integer
+        def lcm(a, b)
+          raise ArgumentError, 'lcm requires Integer arguments' unless a.is_a?(Integer) && b.is_a?(Integer)
+
+          a.abs.lcm(b.abs)
+        end
+
+        # Clamp a numeric value between a minimum and maximum
+        #
+        # @param value [Numeric] the value to clamp
+        # @param min [Numeric] lower bound
+        # @param max [Numeric] upper bound
+        # @return [Numeric] the clamped value
+        # @raise [ArgumentError] if min is greater than max
+        def clamp(value, min, max)
+          raise ArgumentError, 'min must not be greater than max' if min > max
+
+          return min if value < min
+          return max if value > max
+
+          value
+        end
+      end
+    end
+  end
+end

data/lib/philiprehberger/math_kit/stats.rb

@@ -105,6 +105,19 @@ module Philiprehberger
           values.sum
         end
 
+        # Sum of squared deviations from the mean: \sum_i (x_i - mean)^2.
+        # Building block for variance, regression residuals, ANOVA, etc.
+        # Returns 0.0 for empty or single-element inputs.
+        #
+        # @param values [Array<Numeric>] the input values
+        # @return [Float] the sum of squares
+        def sum_of_squares(values)
+          return 0.0 if values.size < 2
+
+          avg = mean(values)
+          values.sum(0.0) { |v| (v - avg)**2 }
+        end
+
         # Range (max - min)
         #
         # @param values [Array<Numeric>] the input values

data/lib/philiprehberger/math_kit/version.rb

@@ -2,6 +2,6 @@
 
 module Philiprehberger
   module MathKit
-    VERSION = '0.3.0'
+    VERSION = '0.5.0'
   end
 end

data/lib/philiprehberger/math_kit.rb

@@ -6,6 +6,7 @@ require_relative 'math_kit/interpolation'
 require_relative 'math_kit/round'
 require_relative 'math_kit/moving_average'
 require_relative 'math_kit/regression'
+require_relative 'math_kit/numeric'
 
 module Philiprehberger
   module MathKit

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-math_kit
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-10 00:00:00.000000000 Z
+date: 2026-04-21 00:00:00.000000000 Z
 dependencies: []
 description: Descriptive statistics, linear interpolation, rounding modes, and moving
   averages. Lightweight math toolkit with zero dependencies.
@@ -24,6 +24,7 @@ files:
 - lib/philiprehberger/math_kit.rb
 - lib/philiprehberger/math_kit/interpolation.rb
 - lib/philiprehberger/math_kit/moving_average.rb
+- lib/philiprehberger/math_kit/numeric.rb
 - lib/philiprehberger/math_kit/regression.rb
 - lib/philiprehberger/math_kit/round.rb
 - lib/philiprehberger/math_kit/stats.rb