philiprehberger-math_kit 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b0ee57bd765f6a85f692da57097963ad6a2b24ccb6d3aa72a933f116faf9d7ec
+  data.tar.gz: a07eca98e2878406fb271187fd77e3d5628153ae0e19d74063998510478b631d
+SHA512:
+  metadata.gz: 1c202b40a1dfbd0282d15573433558b0fdacc071a4f33fe7c3cf1547415a3e93a0aa12cd218573069109c659921a97690d3b2a9f8c0b895f573a60c6f651a72e
+  data.tar.gz: 9ce0bf2fa3522a4a9cc922a564ac8102a1b5327e876ed223a43374514809a97311295ed8e5a69dd530ba9634571fbb07ce19b0233ba2067b61d88fbb6a353af1

data/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to this gem will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-03-26
+
+### Added
+- Initial release
+- Descriptive statistics: mean, median, mode, variance, stddev, percentile, sum, range
+- 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

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 philiprehberger
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,111 @@
+# philiprehberger-math_kit
+
+[![Tests](https://github.com/philiprehberger/rb-math-kit/actions/workflows/ci.yml/badge.svg)](https://github.com/philiprehberger/rb-math-kit/actions/workflows/ci.yml)
+[![Gem Version](https://badge.fury.io/rb/philiprehberger-math_kit.svg)](https://rubygems.org/gems/philiprehberger-math_kit)
+[![License](https://img.shields.io/github/license/philiprehberger/rb-math-kit)](LICENSE)
+[![Sponsor](https://img.shields.io/badge/sponsor-GitHub%20Sponsors-ec6cb9)](https://github.com/sponsors/philiprehberger)
+
+Common math and statistics utilities for Ruby. Descriptive statistics, linear interpolation, rounding modes, and moving averages with zero dependencies.
+
+## Requirements
+
+- Ruby >= 3.1
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "philiprehberger-math_kit"
+```
+
+Or install directly:
+
+```bash
+gem install philiprehberger-math_kit
+```
+
+## Usage
+
+```ruby
+require "philiprehberger/math_kit"
+```
+
+### Statistics
+
+```ruby
+Philiprehberger::MathKit::Stats.mean([1, 2, 3, 4, 5])       # => 3.0
+Philiprehberger::MathKit::Stats.median([3, 1, 4, 1, 5])      # => 3.0
+Philiprehberger::MathKit::Stats.mode([1, 2, 2, 3])            # => [2]
+Philiprehberger::MathKit::Stats.variance([2, 4, 4, 4, 5, 5, 7, 9])  # => 4.0
+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
+```
+
+Sample variance and standard deviation:
+
+```ruby
+Philiprehberger::MathKit::Stats.variance([2, 4, 4, 4, 5, 5, 7, 9], population: false)  # => 4.571...
+Philiprehberger::MathKit::Stats.stddev([2, 4, 4, 4, 5, 5, 7, 9], population: false)    # => 2.138...
+```
+
+### Interpolation
+
+```ruby
+points = [[0, 0], [5, 10], [10, 20]]
+Philiprehberger::MathKit::Interpolation.linear(points, 2.5)  # => 5.0
+Philiprehberger::MathKit::Interpolation.linear(points, 7.5)  # => 15.0
+```
+
+### Rounding
+
+```ruby
+Philiprehberger::MathKit::Round.bankers(2.5)                  # => 2.0 (round half to even)
+Philiprehberger::MathKit::Round.bankers(3.5)                  # => 4.0
+Philiprehberger::MathKit::Round.ceiling(2.1)                  # => 3.0
+Philiprehberger::MathKit::Round.floor(2.9)                    # => 2.0
+Philiprehberger::MathKit::Round.truncate(2.9)                 # => 2.0
+Philiprehberger::MathKit::Round.truncate(-2.9)                # => -2.0
+Philiprehberger::MathKit::Round.bankers(2.55, precision: 1)   # => 2.6
+```
+
+### Moving Averages
+
+```ruby
+Philiprehberger::MathKit::MovingAverage.simple([1, 2, 3, 4, 5], window: 3)      # => [2.0, 3.0, 4.0]
+Philiprehberger::MathKit::MovingAverage.exponential([1, 2, 3, 4, 5], alpha: 0.5) # => [1.0, 1.5, 2.25, 3.125, 4.0625]
+```
+
+## API
+
+| Method | Description |
+|--------|-------------|
+| `Stats.mean(values)` | Arithmetic mean |
+| `Stats.median(values)` | Median (middle value or average of two middle) |
+| `Stats.mode(values)` | Mode(s) as array |
+| `Stats.variance(values, population: true)` | Population or sample variance |
+| `Stats.stddev(values, population: true)` | Standard deviation |
+| `Stats.percentile(values, p)` | Percentile (0-100) |
+| `Stats.sum(values)` | Sum of values |
+| `Stats.range(values)` | Max - min |
+| `Interpolation.linear(points, x)` | Linear interpolation between points |
+| `Round.bankers(value, precision: 0)` | Banker's rounding (round half to even) |
+| `Round.ceiling(value, precision: 0)` | Round up |
+| `Round.floor(value, precision: 0)` | Round down |
+| `Round.truncate(value, precision: 0)` | Truncate toward zero |
+| `MovingAverage.simple(values, window:)` | Simple moving average |
+| `MovingAverage.exponential(values, alpha:)` | Exponential moving average |
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec      # Run tests
+bundle exec rubocop    # Check code style
+```
+
+## License
+
+MIT

data/lib/philiprehberger/math_kit/interpolation.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module MathKit
+    module Interpolation
+      class << self
+        # Linear interpolation between sorted points
+        #
+        # @param points [Array<Array(Numeric, Numeric)>] sorted array of [x, y] pairs
+        # @param x [Numeric] the x value to interpolate at
+        # @return [Float] the interpolated y value
+        # @raise [ArgumentError] if fewer than 2 points or x is out of range
+        def linear(points, x)
+          raise ArgumentError, 'at least 2 points are required' if points.size < 2
+
+          sorted = points.sort_by(&:first)
+
+          if x <= sorted.first[0]
+            return extrapolate(sorted[0], sorted[1], x) if x < sorted.first[0]
+
+            return sorted.first[1].to_f
+          end
+
+          if x >= sorted.last[0]
+            return extrapolate(sorted[-2], sorted[-1], x) if x > sorted.last[0]
+
+            return sorted.last[1].to_f
+          end
+
+          # Find the bracketing pair
+          i = sorted.index { |pt| pt[0] >= x }
+          return sorted[i][1].to_f if sorted[i][0] == x
+
+          interpolate_between(sorted[i - 1], sorted[i], x)
+        end
+
+        private
+
+        def interpolate_between(p1, p2, x)
+          x1, y1 = p1
+          x2, y2 = p2
+          t = (x - x1).to_f / (x2 - x1)
+          (y1 + (t * (y2 - y1))).to_f
+        end
+
+        def extrapolate(p1, p2, x)
+          interpolate_between(p1, p2, x)
+        end
+      end
+    end
+  end
+end

data/lib/philiprehberger/math_kit/moving_average.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module MathKit
+    module MovingAverage
+      class << self
+        # Simple moving average
+        #
+        # @param values [Array<Numeric>] the input values
+        # @param window [Integer] the window size
+        # @return [Array<Float>] the SMA values (size = values.size - window + 1)
+        # @raise [ArgumentError] if window is larger than values or less than 1
+        def simple(values, window:)
+          raise ArgumentError, 'window must be at least 1' if window < 1
+          raise ArgumentError, 'window must not exceed values size' if window > values.size
+
+          (0..(values.size - window)).map do |i|
+            values[i, window].sum.to_f / window
+          end
+        end
+
+        # Exponential moving average
+        #
+        # @param values [Array<Numeric>] the input values
+        # @param alpha [Float] the smoothing factor (0 < alpha <= 1)
+        # @return [Array<Float>] the EMA values (same size as input)
+        # @raise [ArgumentError] if alpha is out of range or values is empty
+        def exponential(values, alpha:)
+          raise ArgumentError, 'values must not be empty' if values.empty?
+          raise ArgumentError, 'alpha must be between 0 (exclusive) and 1 (inclusive)' if alpha <= 0 || alpha > 1
+
+          result = [values.first.to_f]
+          values[1..].each do |v|
+            result << ((alpha * v) + ((1 - alpha) * result.last))
+          end
+          result
+        end
+      end
+    end
+  end
+end

data/lib/philiprehberger/math_kit/round.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module MathKit
+    module Round
+      class << self
+        # Banker's rounding (round half to even)
+        #
+        # @param value [Numeric] the value to round
+        # @param precision [Integer] number of decimal places
+        # @return [Float] the rounded value
+        def bankers(value, precision: 0)
+          multiplier = 10**precision
+          scaled = value * multiplier
+
+          # Check if exactly at the halfway point
+          if halfway?(scaled)
+            floored = scaled.floor
+            # Round to even
+            if floored.even?
+              floored.to_f / multiplier
+            else
+              (floored + 1).to_f / multiplier
+            end
+          else
+            scaled.round.to_f / multiplier
+          end
+        end
+
+        # Round up (ceiling)
+        #
+        # @param value [Numeric] the value to round
+        # @param precision [Integer] number of decimal places
+        # @return [Float] the rounded value
+        def ceiling(value, precision: 0)
+          multiplier = 10**precision
+          (value * multiplier).ceil.to_f / multiplier
+        end
+
+        # Round down (floor)
+        #
+        # @param value [Numeric] the value to round
+        # @param precision [Integer] number of decimal places
+        # @return [Float] the rounded value
+        def floor(value, precision: 0)
+          multiplier = 10**precision
+          (value * multiplier).floor.to_f / multiplier
+        end
+
+        # Truncate toward zero
+        #
+        # @param value [Numeric] the value to truncate
+        # @param precision [Integer] number of decimal places
+        # @return [Float] the truncated value
+        def truncate(value, precision: 0)
+          multiplier = 10**precision
+          (value * multiplier).truncate.to_f / multiplier
+        end
+
+        private
+
+        def halfway?(scaled)
+          fractional = (scaled - scaled.floor).abs
+          (fractional - 0.5).abs < 1e-9
+        end
+      end
+    end
+  end
+end

data/lib/philiprehberger/math_kit/stats.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module MathKit
+    module Stats
+      class << self
+        # Arithmetic mean of values
+        #
+        # @param values [Array<Numeric>] the input values
+        # @return [Float] the arithmetic mean
+        # @raise [ArgumentError] if values is empty
+        def mean(values)
+          raise ArgumentError, 'values must not be empty' if values.empty?
+
+          sum(values).to_f / values.size
+        end
+
+        # Median (middle value or average of two middle values)
+        #
+        # @param values [Array<Numeric>] the input values
+        # @return [Float] the median
+        # @raise [ArgumentError] if values is empty
+        def median(values)
+          raise ArgumentError, 'values must not be empty' if values.empty?
+
+          sorted = values.sort
+          mid = sorted.size / 2
+
+          if sorted.size.odd?
+            sorted[mid].to_f
+          else
+            (sorted[mid - 1] + sorted[mid]).to_f / 2
+          end
+        end
+
+        # Mode(s) — most frequently occurring value(s)
+        #
+        # @param values [Array<Numeric>] the input values
+        # @return [Array<Numeric>] the mode(s) as an array
+        # @raise [ArgumentError] if values is empty
+        def mode(values)
+          raise ArgumentError, 'values must not be empty' if values.empty?
+
+          freq = values.tally
+          max_count = freq.values.max
+          freq.select { |_, count| count == max_count }.keys
+        end
+
+        # Population or sample variance
+        #
+        # @param values [Array<Numeric>] the input values
+        # @param population [Boolean] true for population variance, false for sample
+        # @return [Float] the variance
+        # @raise [ArgumentError] if values is empty or sample variance with fewer than 2 values
+        def variance(values, population: true)
+          raise ArgumentError, 'values must not be empty' if values.empty?
+
+          n = values.size
+          raise ArgumentError, 'sample variance requires at least 2 values' if !population && n < 2
+
+          avg = mean(values)
+          sum_sq = values.sum { |v| (v - avg)**2 }
+          divisor = population ? n : n - 1
+          sum_sq.to_f / divisor
+        end
+
+        # Standard deviation
+        #
+        # @param values [Array<Numeric>] the input values
+        # @param population [Boolean] true for population stddev, false for sample
+        # @return [Float] the standard deviation
+        def stddev(values, population: true)
+          Math.sqrt(variance(values, population: population))
+        end
+
+        # Percentile (0-100) using linear interpolation
+        #
+        # @param values [Array<Numeric>] the input values
+        # @param p [Numeric] the percentile (0-100)
+        # @return [Float] the percentile value
+        # @raise [ArgumentError] if values is empty or p is out of range
+        def percentile(values, p)
+          raise ArgumentError, 'values must not be empty' if values.empty?
+          raise ArgumentError, 'percentile must be between 0 and 100' if p.negative? || p > 100
+
+          sorted = values.sort
+          return sorted.first.to_f if p.zero?
+          return sorted.last.to_f if p == 100
+
+          rank = (p / 100.0) * (sorted.size - 1)
+          lower = rank.floor
+          upper = rank.ceil
+
+          return sorted[lower].to_f if lower == upper
+
+          fraction = rank - lower
+          (sorted[lower] + (fraction * (sorted[upper] - sorted[lower]))).to_f
+        end
+
+        # Sum of values
+        #
+        # @param values [Array<Numeric>] the input values
+        # @return [Numeric] the sum
+        def sum(values)
+          values.sum
+        end
+
+        # Range (max - min)
+        #
+        # @param values [Array<Numeric>] the input values
+        # @return [Numeric] the range
+        # @raise [ArgumentError] if values is empty
+        def range(values)
+          raise ArgumentError, 'values must not be empty' if values.empty?
+
+          values.max - values.min
+        end
+      end
+    end
+  end
+end

data/lib/philiprehberger/math_kit/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module MathKit
+    VERSION = '0.1.0'
+  end
+end

data/lib/philiprehberger/math_kit.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require_relative 'math_kit/version'
+require_relative 'math_kit/stats'
+require_relative 'math_kit/interpolation'
+require_relative 'math_kit/round'
+require_relative 'math_kit/moving_average'
+
+module Philiprehberger
+  module MathKit
+    class Error < StandardError; end
+  end
+end

metadata

@@ -0,0 +1,58 @@
+--- !ruby/object:Gem::Specification
+name: philiprehberger-math_kit
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Philip Rehberger
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-03-27 00:00:00.000000000 Z
+dependencies: []
+description: Descriptive statistics, linear interpolation, rounding modes, and moving
+  averages. Lightweight math toolkit with zero dependencies.
+email:
+- me@philiprehberger.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/philiprehberger/math_kit.rb
+- lib/philiprehberger/math_kit/interpolation.rb
+- lib/philiprehberger/math_kit/moving_average.rb
+- lib/philiprehberger/math_kit/round.rb
+- lib/philiprehberger/math_kit/stats.rb
+- lib/philiprehberger/math_kit/version.rb
+homepage: https://github.com/philiprehberger/rb-math-kit
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/philiprehberger/rb-math-kit
+  source_code_uri: https://github.com/philiprehberger/rb-math-kit
+  changelog_uri: https://github.com/philiprehberger/rb-math-kit/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/philiprehberger/rb-math-kit/issues
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Common math and statistics utilities for Ruby
+test_files: []