histogram-rb 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 697a2cb2bd4da96b74ed8bbbea30058ab1b98c9e83cbaffec4656614152a9d7e
+  data.tar.gz: ad1aa054124f41c1e32626d452d5b187b3b154ad32ca722e65eb182a9bc8c0f0
+SHA512:
+  metadata.gz: 196ec245d6ffacca8e9032e16fe37351b8eb21c9b48ef60c14c777f3830c6392de6dc2a8dcf64a6733fc4e0b1872b2477779cf54777bc2e424bd336a8a16ea53
+  data.tar.gz: 6baf9065d3154e1307875a14bbd49af4b7375fe954db26d517979ac453e459d0e81693648a7eaae75bb70425664707096fab0b9cbd4a3b14cc84840f152f1609

data/Gemfile

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec
+
+group :development do
+  gem "rake", "~> 13.0"
+  gem "pry-byebug"
+end
+
+group :test do
+  gem "minitest", "~> 5.0"
+  gem "minitest-reporters"
+end

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2022 derekstride
+
+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,110 @@
+# Histogram
+[![Ruby CI](https://github.com/DerekStride/histogram/actions/workflows/ruby.yml/badge.svg)](https://github.com/DerekStride/histogram/actions/workflows/ruby.yml) [![Publish new releases to rubygems](https://github.com/DerekStride/histogram/actions/workflows/publish-gem.yml/badge.svg)](https://github.com/DerekStride/histogram/actions/workflows/publish-gem.yml)
+
+Easily create a histogram from an array of values and allow easy rendering to the terminal.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'histogram-rb'
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install histogram-rb
+
+## Usage
+
+Initialize a Histogram with a list of values:
+
+```ruby
+histogram = Histogram.new(1000.times.map { Random.rand })
+```
+
+Then call render to get a print-friendly string, all parameters are optional.
+
+```ruby
+histogram.render(
+  title: "Uniform Distribution",
+  precision: 2,
+)
+```
+
+```
+                              Uniform Distribution
+═════════════════════════════════════════════════════════════════════════════════
+    x                       x           x           x           x          x
+    x           x           x           x           x           x          x
+    x           x           x           x           x           x          x
+    x           x           x           x           x           x          x
+    x           x           x           x           x           x          x
+    x           x           x           x           x           x          x
+    x           x           x           x           x           x          x
+    x           x           x           x           x           x          x
+    x           x           x           x           x           x          x
+    x           x           x           x           x           x          x
+    x           x           x           x           x           x          x
+    x           x           x           x           x           x          x
+─────────────────────────────────────────────────────────────────────────────────
+ 0.0-0.14   0.14-0.29   0.29-0.43   0.43-0.57   0.57-0.71   0.71-0.86   0.86-1.0
+ (150)      (128)       (154)       (145)       (136)       (150)       (137)
+```
+
+You can use the `border` parameter to specify a `terminal-table` border class to change the output. e.g.
+
+```ruby
+histogram.render(
+  title: "Normal Distribution",
+  precision: 2,
+  border: Terminal::Table::AsciiBorder.new,
+)
+```
+
+```
+                               Normal Distribution
+-----------+----------+----------+-----------+-----------+-----------+-----------
+                                       x
+                                       x
+                           x           x
+                           x           x
+                           x           x           x
+                           x           x           x           x
+                           x           x           x           x
+                x          x           x           x           x
+                x          x           x           x           x
+     x          x          x           x           x           x           x
+     x          x          x           x           x           x           x
+     x          x          x           x           x           x           x
+-----------+----------+----------+-----------+-----------+-----------+-----------
+ 0.02-0.16   0.16-0.3   0.3-0.44   0.44-0.57   0.57-0.71   0.71-0.85   0.85-0.98
+ (26)        (51)       (108)      (141)       (81)        (73)        (24)
+```
+## Development
+
+After checking out the repo, run `bundle install` to install dependencies. You can also run `bin/console` for an
+interactive prompt that will allow you to experiment.
+
+## Testing
+
+Running the unit tests with `bundle exec rake test`.
+
+The rendering portion of the histogram is harder to test with unit tests. Instead there is a script that will allow you
+to render histograms easily to enable visual tests.
+
+Examples:
+
+`bin/test`
+`bin/test -b ascii -p 2`
+`bin/test -t "Example Title" -b thick -p 2`
+`bin/test -t "Example Title" -b ascii -p 3`
+`bin/test -t "Normal Distribution" -d normal -p 2 -c 10000`
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task default: :test

data/histogram.gemspec

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative "lib/histogram/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "histogram-rb"
+  spec.version = Histogram::VERSION
+  spec.authors = ["derekstride"]
+  spec.email = ["derek@stride.host"]
+
+  spec.summary = "Easily convert an array of values into a histogram."
+  spec.description = "Easily convert an array of values into a histogram."
+  spec.homepage = "https://github.com/derekstride/histogram"
+  spec.license = "MIT"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (f == __FILE__) || f.match(%r{\A(?:(?:bin|test|spec|features)/|\.(?:git|travis|circleci)|appveyor)})
+    end
+  end
+
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency("terminal-table")
+end

data/lib/histogram/bin.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+Bin = Struct.new(:range, :count)

data/lib/histogram/bin_counter.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module BinCounter
+  extend self
+
+  def evaluate(values)
+    min, max = values.minmax
+
+    candidate =
+      if max - min <= 12 && (max.integer? || min.integer?)
+        (max - min).ceil
+      elsif max - min <= 1
+        10
+      elsif max - min <= 12
+        12
+      elsif Math.sqrt(max - min) <= 12
+        Math.sqrt(max - min).ceil
+      end
+
+    candidate || [Math.sqrt(values.size).ceil, 12].min
+  end
+end

data/lib/histogram/bin_packer.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+class BinPacker
+  attr_reader :bin_count, :min, :max
+
+  def initialize(bin_count, min, max)
+    @bin_count = bin_count
+    @max = max
+    @min = min
+  end
+
+  def bins(values)
+    groups = Array.new(bin_count) do |i|
+      f = min + i * bin_width
+      range_max = if f.is_a?(Integer)
+        f + bin_width - 1
+      else
+        f + bin_width.prev_float
+      end
+
+      Bin.new(f..range_max, 0)
+    end
+    binmax = groups.last.range.max
+    unless binmax >= max
+      groups << if bin_width == 1
+        Bin.new(max..max, 0)
+      else
+        Bin.new(binmax..(binmax + bin_width), 0)
+      end
+    end
+
+    values.each do |v|
+      bin = groups.detect { |bin| bin.range.include?(v) }
+      bin.count += 1
+    end
+
+    groups
+  end
+
+  def bin_width
+    if max.is_a?(Float) || min.is_a?(Float)
+      (max - min) / bin_count.to_f
+    else
+      ((max - min) / bin_count.to_f).ceil
+    end
+  end
+end

data/lib/histogram/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+class Histogram
+  VERSION = "0.1.1"
+end

data/lib/histogram.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require "histogram/bin"
+require "histogram/bin_packer"
+require "histogram/bin_counter"
+require "terminal-table"
+
+class Histogram
+  class Error < StandardError; end
+
+  attr_reader :bin_count
+
+  def initialize(values)
+    @values = values
+    @bin_count = BinCounter.evaluate(values)
+    @bin_packer = BinPacker.new(@bin_count, values.min, values.max)
+  end
+
+  def bin_width
+    @bin_packer.bin_width
+  end
+
+  def bins
+    @bins ||= @bin_packer.bins(values)
+  end
+
+  def render(title: nil, precision: 2, border: Terminal::Table::UnicodeBorder.new)
+    largest_bin = bins.max_by(&:count).count
+    max_marker_count = [largest_bin, 12].min
+    marker_width = largest_bin / max_marker_count
+
+    rows = max_marker_count.times.map do |y|
+      bins.size.times.map do |x|
+        value = if (bins[x].count / marker_width.to_f).ceil > y
+          "x"
+        else
+          ""
+        end
+        { value: value, alignment: :center }
+      end
+    end.reverse
+    rows << bins.map { |bin| "(#{bin.count})" }
+
+    border.top = false
+    border.left = false
+    border.right = false
+    border.data[:y] = " "
+    border.data[:n] = border.data[:nx]
+    border.data[:ai] = border.data[:ax]
+    border.data[:s] = border.data[:sx]
+
+    headings = bins.map do |bin|
+      min, max = bin.range.minmax
+      if min == max
+        min.to_s
+      else
+        "#{min.round(precision)}-#{max.round(precision)}"
+      end
+    end
+    options = {
+      headings: headings,
+      rows: rows,
+      style: {
+        border: border,
+      },
+    }
+    options[:title] = title if title
+
+    output = Terminal::Table.new(**options).to_s
+
+    lines = output.lines
+    lines.delete_at(1) # delete header seperator
+    header = if title
+      lines.delete_at(1)
+    else
+      lines.shift
+    end
+    totals = lines.delete_at(-2)
+    lines.last << "\n"
+    lines << header
+    lines << totals.chomp
+    lines.join
+  end
+
+  private
+
+  attr_reader :values, :title
+end

metadata

@@ -0,0 +1,69 @@
+--- !ruby/object:Gem::Specification
+name: histogram-rb
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- derekstride
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2022-07-09 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: terminal-table
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Easily convert an array of values into a histogram.
+email:
+- derek@stride.host
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- histogram.gemspec
+- lib/histogram.rb
+- lib/histogram/bin.rb
+- lib/histogram/bin_counter.rb
+- lib/histogram/bin_packer.rb
+- lib/histogram/version.rb
+homepage: https://github.com/derekstride/histogram
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/derekstride/histogram
+  source_code_uri: https://github.com/derekstride/histogram
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.7
+signing_key: 
+specification_version: 4
+summary: Easily convert an array of values into a histogram.
+test_files: []