philiprehberger-math_kit 0.2.3 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6e454a11061739fecb690a7246eb3b4120676ab809e103868b1c7b1c6772456f
-  data.tar.gz: c47a3d320f89cf3446cfe4f649e1b4ddc2f058f7cbaf1d5351e25d97a60f5499
+  metadata.gz: bfd866aacb1af07326cd0543912f1d088dec7cc9c7c06f217709a7bbc31f79d1
+  data.tar.gz: f747448a80beda06245efebbff03f3fb043c042bf625c9b8a7512debb9847e1b
 SHA512:
-  metadata.gz: c6e207c58fd8512f5ef5b61bab968d4379004d3d93a118dad5b340521615f3405270c64aa253665066568249e5ab6d41e1914da73cffa2a3e4203868dc2827f7
-  data.tar.gz: da21ff4a0bf20630b2cc46477147ad530ec79d9fdc563dea0900c972cb618d37a5ddead11b9210e8a0fee0e735c1141ed72f6ac04761b9e1065fd5dcd5c325a4
+  metadata.gz: 6b8b029f141507b9cd791c070ae2d9f5cec3f228182a58caaaf1ad7fce42512a2c62d364e8d1a68d7b204e096590d392ebd341042ada39b50c0b35053ed06974
+  data.tar.gz: 6ec476f44f0728ef45b6ce64806be76544b39a5f4831d2897f7ea2fd9bb0f9959df4fa1f7fba7a61cd8f842f76976935b47301da3353da340f5916a96748c65e

data/CHANGELOG.md

@@ -7,6 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-04-10
+
+### Added
+- `Stats.describe(values)` for summary statistics (count, mean, median, min, max, stddev, variance, percentiles)
+- `Stats.histogram(values, bins:)` for frequency distribution into equal-width bins
+- `Stats.weighted_mean(values, weights:)` for weighted arithmetic mean
+
 ## [0.2.3] - 2026-04-08
 
 ### Changed

data/README.md

@@ -43,6 +43,28 @@ Philiprehberger::MathKit::Stats.sum([1, 2, 3])                # => 6
 Philiprehberger::MathKit::Stats.range([1, 5, 3, 9, 2])        # => 8
 ```
 
+### Summary Statistics
+
+```ruby
+Philiprehberger::MathKit::Stats.describe([1, 2, 3, 4, 5])
+# => { count: 5, mean: 3.0, median: 3.0, min: 1.0, max: 5.0,
+#      stddev: 1.58..., variance: 2.5, p25: 2.0, p50: 3.0, p75: 4.0 }
+```
+
+### Weighted Mean
+
+```ruby
+Philiprehberger::MathKit::Stats.weighted_mean([10, 20, 30], weights: [3, 1, 1])
+# => 16.0
+```
+
+### Histogram
+
+```ruby
+Philiprehberger::MathKit::Stats.histogram([1, 2, 3, 4, 5, 6, 7, 8, 9, 10], bins: 5)
+# => [{ min: 1.0, max: 2.8, count: 2 }, { min: 2.8, max: 4.6, count: 2 }, ...]
+```
+
 ### Skewness and Kurtosis
 
 ```ruby
@@ -140,6 +162,9 @@ Philiprehberger::MathKit::MovingAverage.exponential([1, 2, 3, 4, 5], alpha: 0.5)
 | `.median_absolute_deviation(values)` | Median absolute deviation |
 | `.trimmed_mean(values, trim: 0.1)` | Trimmed mean (remove fraction from each end) |
 | `.winsorized_mean(values, trim: 0.1)` | Winsorized mean (clamp extremes) |
+| `.describe(values)` | Summary statistics hash (count, mean, median, min, max, stddev, percentiles) |
+| `.histogram(values, bins: 10)` | Frequency distribution as array of bin hashes |
+| `.weighted_mean(values, weights:)` | Weighted arithmetic mean |
 
 ### `Regression`
 

data/lib/philiprehberger/math_kit/stats.rb

@@ -291,6 +291,71 @@ module Philiprehberger
           mean(winsorized)
         end
 
+        # Summary statistics for a dataset
+        #
+        # @param values [Array<Numeric>] the input values
+        # @return [Hash] with :count, :mean, :median, :min, :max, :stddev, :variance, :p25, :p50, :p75
+        # @raise [ArgumentError] if values is empty
+        def describe(values)
+          raise ArgumentError, 'values must not be empty' if values.empty?
+
+          {
+            count: values.size,
+            mean: mean(values),
+            median: median(values),
+            min: values.min.to_f,
+            max: values.max.to_f,
+            stddev: values.size >= 2 ? stddev(values, population: false) : 0.0,
+            variance: values.size >= 2 ? variance(values, population: false) : 0.0,
+            p25: percentile(values, 25),
+            p50: percentile(values, 50),
+            p75: percentile(values, 75)
+          }
+        end
+
+        # Frequency distribution (histogram)
+        #
+        # @param values [Array<Numeric>] the input values
+        # @param bins [Integer] number of bins (default: 10)
+        # @return [Array<Hash>] array of { min:, max:, count: } hashes
+        # @raise [ArgumentError] if values is empty or bins < 1
+        def histogram(values, bins: 10)
+          raise ArgumentError, 'values must not be empty' if values.empty?
+          raise ArgumentError, 'bins must be at least 1' if bins < 1
+
+          min_val = values.min.to_f
+          max_val = values.max.to_f
+          width = max_val == min_val ? 1.0 : (max_val - min_val) / bins.to_f
+
+          result = Array.new(bins) do |i|
+            { min: min_val + (i * width), max: min_val + ((i + 1) * width), count: 0 }
+          end
+
+          values.each do |v|
+            idx = width.zero? ? 0 : ((v - min_val) / width).floor
+            idx = bins - 1 if idx >= bins
+            result[idx][:count] += 1
+          end
+
+          result
+        end
+
+        # Weighted arithmetic mean
+        #
+        # @param values [Array<Numeric>] the input values
+        # @param weights [Array<Numeric>] the corresponding weights
+        # @return [Float] the weighted mean
+        # @raise [ArgumentError] if arrays differ in size, are empty, or weights sum to zero
+        def weighted_mean(values, weights:)
+          raise ArgumentError, 'values must not be empty' if values.empty?
+          raise ArgumentError, 'values and weights must have the same size' if values.size != weights.size
+
+          total_weight = weights.sum.to_f
+          raise ArgumentError, 'weights must not sum to zero' if total_weight.zero?
+
+          values.zip(weights).sum { |v, w| v * w } / total_weight
+        end
+
         private
 
         # T-distribution critical values for common confidence levels

data/lib/philiprehberger/math_kit/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-math_kit
 version: !ruby/object:Gem::Version
-  version: 0.2.3
+  version: 0.3.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-09 00:00:00.000000000 Z
+date: 2026-04-10 00:00:00.000000000 Z
 dependencies: []
 description: Descriptive statistics, linear interpolation, rounding modes, and moving
   averages. Lightweight math toolkit with zero dependencies.