statistics.rb 0.5.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d48404847c10c54ef090f41c5dc470e3ca6409ab07918828b6181e54836bc22b
+  data.tar.gz: 42f80e662e6834081f993c168e96e75451be5a83106bbe8ebe0a2260a47f84c1
+SHA512:
+  metadata.gz: eca8442077f05a25a936475b44c5d6cc75b6a1f009ec1ec15e4803d4b43727c554b4036a1c3ae44e674acacb4c5c0d4605aca24783998cdd13962a86bca887f5
+  data.tar.gz: 14e9b21b4db384c2bd01bed96d7889c88949fb45a1e2c352df721d9af974ff1daf91e020bcac211b6f94639aafd3d63a16ac3d9a0d27f38f65ce87ade157cefd

data/CHANGELOG

@@ -0,0 +1,92 @@
+# CHANGELOG
+
+## [0.5.0] - 20260503
+## Bin.bin_for_value, Bin split, gem scaffolding
+
+1. + Bin.bin_for_value (wraps index_for_value, now private)
+2. ~ Histogram#allocate_values: Use Bin.bin_for_value
+3. ~ Bin split out to lib/Statistics/Histogram/Bin.rb
+4. + lib/statistics.rb
+5. + lib/Statistics/VERSION.rb
+6. + statistics.rb.gemspec
+7. + Gemfile
+8. + Rakefile
+9. + README.md
+10. + LICENSE
+11. + test/Statistics/Histogram_test.rb
+12. + test/Statistics/Histogram/Bin_test.rb
+
+
+## [0.4.0] - 20260502
+## Bin instances and consolidated class methods
+
+1. + Bin instances (count-tracking via increment, attr_reader :interval)
+2. ~ Bin.width: handles bin_width, bin_count, zero-range, and method selection
+3. + Bin.boundaries (from 0.3.0)
+4. + Bin.index_for_value (was Histogram#index_for_value)
+5. + Bin.data_range
+6. ~ class << self for class methods with private boundary
+7. ~ attr_reader :count replaces hand-written method
+
+
+## [0.3.0] - 20260417
+## Hash-based bins, Bin as class-methods-only
+
+1. + Bin.boundaries class method
+2. ~ initialize: delegates to Bin.width and Bin.boundaries
+3. ~ Bin: hash-based bins (no Bin instances), Bin is class-methods-only
+4. - index_for_value (inlined back into allocate_values)
+5. - determine_bin_width (replaced by Bin.width delegation)
+6. - zero-range guard
+
+
+## [0.2.0] - 20260417
+## Count-tracking, interval, zero-range guard
+
+1. ~ Bin: count-tracking via increment instead of storing values in array
+2. ~ Bin: attr_reader :interval instead of :range
+3. + Bin#empty? checks @count == 0 instead of @values.empty?
+4. + determine_bin_width: zero-range guard
+5. + index_for_value extracted from allocate_values
+
+
+## [0.1.1] - 20260417
+## Extract determine_bin_width
+
+1. ~ initialize: extracted determine_bin_width from one-liner
+2. /compute_boundaries/calculate_boundaries/
+
+
+## [0.1.0] - 20260417
+## Bin class
+
+1. + Statistics::Histogram::Bin
+2. ~ allocate_values: creates Bin instances instead of hash entries
+
+
+## [0.0.0] - 20260417
+## Statistics::Histogram
+
+1. + lib/Statistics/Histogram.rb
+2. - lib/BinWidth.rb
+
+
+## 20260416
+## BinWidth 0.1.0 to 0.2.0: Reintroduce all named strategies
+
+1. /0.1.0/0.2.0/
+2. Reintroduce all named strategies.
+
+
+## 20260416
+## BinWidth 0.0.0 to 0.1.0: Tuneable root generalisation
+
+1. /0.0.0/0.1.0/
+2. + tuneable_root as the general form
+3. ~ square_root rewritten as range * n^(-1/2) form
+
+
+## 20260416
+## BinWidth 0.0.0
+
+1. + lib/BinWidth.rb

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 thoran
+
+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,80 @@
+# statistics.rb
+
+A statistics library for Ruby.
+
+## Installation
+
+```
+gem install statistics.rb
+```
+
+Or add to your Gemfile:
+
+```ruby
+gem 'statistics.rb'
+```
+
+## Usage
+
+### Histogram
+
+Create a histogram from an array of numeric values:
+
+```ruby
+require 'statistics.rb'
+
+values = [1.2, 3.4, 5.6, 7.8, 2.3, 4.5, 6.7, 8.9, 3.2, 5.4]
+
+h = Statistics::Histogram.new(values)
+puts h
+```
+
+Output:
+
+```
+    1.20...3.63  |   3 | ****************************************
+    3.63...6.07  |   3 | ****************************************
+    6.07...8.50  |   2 | ***************************
+    8.50...10.93 |   1 | *************
+```
+
+#### Automatic bin width
+
+By default, bin width is calculated using the square root rule: `data_range / sqrt(n)`.
+
+#### Manual bin width
+
+```ruby
+h = Statistics::Histogram.new(values, bin_width: 2.0)
+```
+
+#### Manual bin count
+
+```ruby
+h = Statistics::Histogram.new(values, bin_count: 5)
+```
+
+#### Querying the histogram
+
+```ruby
+h.bins          # => [#<Bin ...>, #<Bin ...>, ...]
+h.boundaries    # => [1.2, 3.77, 6.34, ...]
+h.bin_count     # => 4
+h.mode          # => #<Bin interval=1.2...3.77 count=3>
+
+h.bins.first.interval  # => 1.2...3.77
+h.bins.first.count     # => 3
+h.bins.first.width     # => 2.57
+h.bins.first.empty?    # => false
+```
+
+## Roadmap
+
+- Optional per-bin value storage
+- Additional bin width methods (Freedman-Diaconis, Scott, Sturges, cube root, tuneable root)
+- Composable statistical primitives (Percentile, StandardDeviation, IQR)
+- Aligned/neat bin boundaries
+
+## License
+
+MIT

data/Rakefile

@@ -0,0 +1,7 @@
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.test_files = FileList['test/**/*_test.rb']
+end
+
+task default: :test

data/lib/Statistics/Histogram/Bin.rb

@@ -0,0 +1,76 @@
+# Statistics/Histogram/Bin.rb
+# Statistics::Histogram::Bin
+
+module Statistics
+  class Histogram
+    class Bin
+      class << self
+        def width(values, bin_width: nil, bin_count: nil, method: :square_root)
+          if bin_width
+            bin_width
+          elsif bin_count
+            data_range(values) / bin_count.to_f
+          elsif data_range(values) == 0
+            1.0
+          else
+            send("#{method}_width", values)
+          end
+        end
+
+        def count(values, method: :square_root)
+          send("#{method}_count", values)
+        end
+
+        def data_range(values)
+          values.last - values.first
+        end
+
+        def boundaries(values, bin_width: nil, bin_count: nil, method: :square_root)
+          w = bin_width || width(values, bin_count: bin_count, method: method)
+          values.first.step(to: values.last + w, by: w).to_a
+        end
+
+        def bin_for_value(value, bins, bottom_boundary, bin_width)
+          index = index_for_value(value, bins.count, bottom_boundary, bin_width)
+          bins[index]
+        end
+
+        private
+
+        def index_for_value(value, bin_count, bottom_boundary, bin_width)
+          i = ((value - bottom_boundary) / bin_width).floor
+          i >= bin_count ? bin_count - 1 : i
+        end
+
+        def square_root_width(values)
+          data_range(values) * values.size ** (-1.0 / 2)
+        end
+
+        def square_root_count(values)
+          Math.sqrt(values.size).ceil
+        end
+      end # class << self
+
+      attr_reader :count, :interval
+
+      def increment
+        @count += 1
+      end
+
+      def width
+        @interval.end - @interval.begin
+      end
+
+      def empty?
+        @count == 0
+      end
+
+      private
+
+      def initialize(interval)
+        @interval = interval
+        @count = 0
+      end
+    end
+  end
+end

data/lib/Statistics/Histogram.rb

@@ -0,0 +1,46 @@
+# Statistics/Histogram.rb
+# Statistics::Histogram
+
+require_relative './Histogram/Bin'
+
+module Statistics
+  class Histogram
+    attr_reader :bins, :boundaries
+
+    def mode
+      @bins.max_by(&:count)
+    end
+
+    def bin_count
+      @bins.size
+    end
+
+    def to_s
+      max_count = @bins.map(&:count).max
+      @bins.map do |bin|
+        bar = '*' * ((bin.count.to_f / max_count) * 40).round
+        format('%8.2f...%-8.2f | %3d | %s', bin.interval.begin, bin.interval.end, bin.count, bar)
+      end.join("\n")
+    end
+
+    private
+
+    def initialize(values, bin_width: nil, bin_count: nil, method: :square_root)
+      raise ArgumentError, 'Values must not be empty' if values.empty?
+      @values = values.map(&:to_f).sort
+      @bin_width = Bin.width(@values, bin_width: bin_width, bin_count: bin_count, method: method)
+      @boundaries = Bin.boundaries(@values, bin_width: @bin_width)
+      @bins = allocate_values
+    end
+
+    def allocate_values
+      bins = @boundaries.each_cons(2).map{|lower, upper| Bin.new(lower...upper)}
+      bottom_boundary = @boundaries.first
+      @values.each do |value|
+        bin = Bin.bin_for_value(value, bins, bottom_boundary, @bin_width)
+        bin.increment
+      end
+      bins
+    end
+  end
+end

data/lib/Statistics/VERSION.rb

@@ -0,0 +1,6 @@
+# Statistics/VERSION.rb
+# Statistics::VERSION
+
+module Statistics
+  VERSION = '0.5.0'
+end

data/lib/statistics.rb

@@ -0,0 +1,4 @@
+# statistics.rb
+
+require_relative './Statistics/VERSION'
+require_relative './Statistics/Histogram'

data/statistics.rb.gemspec

@@ -0,0 +1,46 @@
+require_relative './lib/Statistics/VERSION'
+
+class Gem::Specification
+  def dependencies=(gems)
+    gems.each{|gem| add_dependency(*gem)}
+  end
+
+  def development_dependencies=(gems)
+    gems.each{|gem| add_development_dependency(*gem)}
+  end
+end
+
+Gem::Specification.new do |spec|
+  spec.name = 'statistics.rb'
+
+  spec.version = Statistics::VERSION
+  spec.date = '2026-05-03'
+
+  spec.summary = "A statistics library for Ruby."
+  spec.description = "A composable statistics library for Ruby. Histogram with automatic bin width calculation and composable Bin class."
+
+  spec.author = 'thoran'
+  spec.email = 'code@thoran.com'
+  spec.homepage = 'http://github.com/thoran/statistics'
+  spec.license = 'MIT'
+
+  spec.required_ruby_version = '>= 2.7'
+
+  spec.files = [
+    Dir['lib/**/*.rb'],
+    Dir['test/**/*.rb'],
+    'CHANGELOG',
+    'Gemfile',
+    'LICENSE',
+    'Rakefile',
+    'README.md',
+    'statistics.rb.gemspec',
+  ].flatten
+
+  spec.require_paths = ['lib']
+
+  spec.development_dependencies = %w{
+    rake
+    minitest
+  }
+end

data/test/Statistics/Histogram/Bin_test.rb

@@ -0,0 +1,95 @@
+# test/Statistics/Histogram/Bin_test.rb
+
+require 'minitest/autorun'
+
+require_relative '../../../lib/Statistics/Histogram/Bin'
+
+describe Statistics::Histogram::Bin do
+  describe '.width' do
+    it 'calculates square root width by default' do
+      values = (1..100).to_a.map(&:to_f)
+      width = Statistics::Histogram::Bin.width(values)
+      expected = (values.last - values.first) * values.size ** (-1.0 / 2)
+      _(width).must_be_close_to expected
+    end
+
+    it 'returns explicit bin_width when provided' do
+      values = (1..100).to_a.map(&:to_f)
+      width = Statistics::Histogram::Bin.width(values, bin_width: 7.5)
+      _(width).must_equal 7.5
+    end
+
+    it 'calculates width from bin_count when provided' do
+      values = (1..100).to_a.map(&:to_f)
+      width = Statistics::Histogram::Bin.width(values, bin_count: 10)
+      _(width).must_be_close_to 9.9
+    end
+
+    it 'returns 1.0 for zero-range data' do
+      values = [5.0, 5.0, 5.0]
+      width = Statistics::Histogram::Bin.width(values)
+      _(width).must_equal 1.0
+    end
+  end
+
+  describe '.boundaries' do
+    it 'returns an array starting at the minimum value' do
+      values = (1..10).to_a.map(&:to_f)
+      boundaries = Statistics::Histogram::Bin.boundaries(values, bin_width: 3.0)
+      _(boundaries.first).must_equal 1.0
+    end
+
+    it 'extends past the maximum value' do
+      values = (1..10).to_a.map(&:to_f)
+      boundaries = Statistics::Histogram::Bin.boundaries(values, bin_width: 3.0)
+      _(boundaries.last).must_be :>=, 10.0
+    end
+  end
+
+  describe '.bin_for_value' do
+    it 'returns the correct bin' do
+      bins = [5.0, 10.0, 15.0, 20.0].each_cons(2).map do |lower, upper|
+        Statistics::Histogram::Bin.new(lower...upper)
+      end
+      bin = Statistics::Histogram::Bin.bin_for_value(7.0, bins, 5.0, 5.0)
+      _(bin.interval).must_equal(5.0...10.0)
+    end
+
+    it 'clamps to the last bin for values at the upper boundary' do
+      bins = [5.0, 10.0, 15.0].each_cons(2).map do |lower, upper|
+        Statistics::Histogram::Bin.new(lower...upper)
+      end
+      bin = Statistics::Histogram::Bin.bin_for_value(15.0, bins, 5.0, 5.0)
+      _(bin.interval).must_equal(10.0...15.0)
+    end
+  end
+
+  describe 'instance methods' do
+    before do
+      @bin = Statistics::Histogram::Bin.new(1.0...5.0)
+    end
+
+    it 'starts with count of zero' do
+      _(@bin.count).must_equal 0
+    end
+
+    it 'increments count' do
+      @bin.increment
+      @bin.increment
+      _(@bin.count).must_equal 2
+    end
+
+    it 'reports width' do
+      _(@bin.width).must_equal 4.0
+    end
+
+    it 'is empty when count is zero' do
+      _(@bin.empty?).must_equal true
+    end
+
+    it 'is not empty after increment' do
+      @bin.increment
+      _(@bin.empty?).must_equal false
+    end
+  end
+end

data/test/Statistics/Histogram_test.rb

@@ -0,0 +1,147 @@
+# test/Statistics/Histogram_test.rb
+
+require 'minitest/autorun'
+
+require_relative '../../lib/Statistics/Histogram'
+
+describe Statistics::Histogram do
+  describe 'with default bin width' do
+    before do
+      @values = (1..25).to_a
+      @histogram = Statistics::Histogram.new(@values)
+    end
+
+    it 'creates bins' do
+      _(@histogram.bins).wont_be_empty
+    end
+
+    it 'allocates all values' do
+      total = @histogram.bins.map(&:count).sum
+      _(total).must_equal @values.size
+    end
+
+    it 'uses square root rule for bin count' do
+      _((@histogram.bin_count - Math.sqrt(@values.size).ceil).abs).must_be :<=, 1
+    end
+  end
+
+  describe 'with explicit bin_width' do
+    before do
+      @values = (1..10).to_a
+      @histogram = Statistics::Histogram.new(@values, bin_width: 5.0)
+    end
+
+    it 'creates bins of the specified width' do
+      _(@histogram.bins.first.width.round(10)).must_equal 5.0
+    end
+
+    it 'allocates all values' do
+      total = @histogram.bins.map(&:count).sum
+      _(total).must_equal @values.size
+    end
+  end
+
+  describe 'with explicit bin_count' do
+    before do
+      @values = (1..10).to_a
+      @histogram = Statistics::Histogram.new(@values, bin_count: 3)
+    end
+
+    it 'creates approximately the requested number of bins' do
+      _((@histogram.bin_count - 3).abs).must_be :<=, 1
+    end
+
+    it 'allocates all values' do
+      total = @histogram.bins.map(&:count).sum
+      _(total).must_equal @values.size
+    end
+  end
+
+  describe '#mode' do
+    it 'returns the bin with the highest count' do
+      values = [1, 1, 1, 1, 5, 5, 10]
+      histogram = Statistics::Histogram.new(values, bin_width: 3.0)
+      mode_bin = histogram.mode
+      _(mode_bin.interval.cover?(1)).must_equal true
+    end
+  end
+
+  describe '#bin_count' do
+    it 'returns the number of bins' do
+      values = [1, 2, 3, 4, 5]
+      histogram = Statistics::Histogram.new(values, bin_count: 2)
+      _(histogram.bin_count).must_be :>=, 1
+    end
+  end
+
+  describe '#boundaries' do
+    before do
+      @values = [5, 10, 15, 20]
+      @histogram = Statistics::Histogram.new(@values, bin_width: 5.0)
+    end
+
+    it 'starts at the minimum value' do
+      _(@histogram.boundaries.first).must_equal 5.0
+    end
+
+    it 'extends past the maximum value' do
+      _(@histogram.boundaries.last).must_be :>=, 20.0
+    end
+
+    it 'has one more boundary than bins' do
+      _(@histogram.boundaries.size).must_equal @histogram.bin_count + 1
+    end
+  end
+
+  describe '#to_s' do
+    before do
+      @values = [1, 2, 3, 4, 5]
+      @histogram = Statistics::Histogram.new(@values, bin_count: 2)
+    end
+
+    it 'returns a string' do
+      _(@histogram.to_s).must_be_kind_of String
+    end
+
+    it 'contains bar characters' do
+      _(@histogram.to_s).must_include '*'
+    end
+  end
+
+  describe 'with identical values' do
+    before do
+      @values = [5, 5, 5, 5, 5]
+      @histogram = Statistics::Histogram.new(@values)
+    end
+
+    it 'does not raise' do
+      _(@histogram.bins).wont_be_empty
+    end
+
+    it 'puts all values in one bin' do
+      _(@histogram.bins.map(&:count).sum).must_equal 5
+    end
+  end
+
+  describe 'with empty values' do
+    it 'raises ArgumentError' do
+      _{Statistics::Histogram.new([])}.must_raise ArgumentError
+    end
+  end
+
+  describe 'with a single value' do
+    it 'creates a histogram with one bin' do
+      histogram = Statistics::Histogram.new([42])
+      _(histogram.bins.map(&:count).sum).must_equal 1
+    end
+  end
+
+  describe 'with float values' do
+    it 'handles floats correctly' do
+      values = [1.1, 2.2, 3.3, 4.4, 5.5, 6.6, 7.7, 8.8, 9.9]
+      histogram = Statistics::Histogram.new(values, bin_width: 3.0)
+      total = histogram.bins.map(&:count).sum
+      _(total).must_equal values.size
+    end
+  end
+end

metadata

@@ -0,0 +1,80 @@
+--- !ruby/object:Gem::Specification
+name: statistics.rb
+version: !ruby/object:Gem::Version
+  version: 0.5.0
+platform: ruby
+authors:
+- thoran
+bindir: bin
+cert_chain: []
+date: 2026-05-03 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: A composable statistics library for Ruby. Histogram with automatic bin
+  width calculation and composable Bin class.
+email: code@thoran.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- lib/Statistics/Histogram.rb
+- lib/Statistics/Histogram/Bin.rb
+- lib/Statistics/VERSION.rb
+- lib/statistics.rb
+- statistics.rb.gemspec
+- test/Statistics/Histogram/Bin_test.rb
+- test/Statistics/Histogram_test.rb
+homepage: http://github.com/thoran/statistics
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.7'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.10
+specification_version: 4
+summary: A statistics library for Ruby.
+test_files: []