mini_histogram 0.1.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a1d07dadd88ba1bc23f7a24c225a8a7146a657f932122e4681843478ef61ec14
-  data.tar.gz: fed4add367a52b8dc55f67389877ed6444413c10899c6cb1979af262aa279f7c
+  metadata.gz: 3dc9a1c55d5d10c4c56a27b12ce42b3fdc5d2853997152e79850c081a0e2d07f
+  data.tar.gz: 5d5ef7440f2148b3154df577e7997195ff48a0be0d8194a0771517d3fd3e33a7
 SHA512:
-  metadata.gz: 407f81d19278447ed837bf983e7794a229eefeee71d5f68f1b1b20929e755057a5047296554c84ec0af6144f2340c6d08dd1770327aa1f28633b80ca01e5e0ef
-  data.tar.gz: 989f6b2acc56666c9c20c9bb05944a828ed2cef0cab0fc8a54fd7aa7ebb272e2ce7bbee37ecf465d489021be07cc1777e249d54f1fb088c4ffdfc754c3dddf60
+  metadata.gz: 306b0ca28c902e98ac3edcdbb829e9287615b8f4be470132c48c8bb8b76481f3fd0470b29ef402c4c68f5d65af45c59632e1405e9f29fb355f785b32c7064a04
+  data.tar.gz: 1b088faab263d9efc61d0b61247a24b2a78ced9748960e8bf7b2e70f33c4a19a0334975ef5c5cdda8872e022d2055c1006c001b2ce72819144eea8f99ca464f7

data/.github/workflows/check_changelog.yml

@@ -0,0 +1,10 @@
+name: Check Changelog
+on: [pull_request]
+jobs:
+ build:
+   runs-on: ubuntu-latest
+   steps:
+   - uses: actions/checkout@v1
+   - name: Check that CHANGELOG is touched
+     run: |
+       cat $GITHUB_EVENT_PATH | jq .pull_request.title |  grep -i '\[\(\(changelog skip\)\|\(ci skip\)\)\]' ||  git diff remotes/origin/${{ github.base_ref }} --name-only | grep CHANGELOG.md

data/.gitignore

@@ -6,3 +6,5 @@
 /pkg/
 /spec/reports/
 /tmp/
+
+Gemfile.lock

data/.travis.yml

@@ -7,4 +7,3 @@ rvm:
   - 2.5
   - 2.6
   - 2.7.0
-before_install: gem install bundler -v 2.1.2

data/CHANGELOG.md

@@ -0,0 +1,25 @@
+## HEAD
+
+## 0.2.1
+
+- Added missing constant needed for plotting support (https://github.com/zombocom/mini_histogram/pull/4)
+
+## 0.2.0
+
+- Experimental plotting support added (https://github.com/zombocom/mini_histogram/pull/3)
+
+## 0.1.3
+
+- Handle edge cases (https://github.com/zombocom/mini_histogram/pull/2)
+
+## 0.1.2
+
+- Add `edge` as alias to `edges`
+
+## 0.1.1
+
+- Fix multi histogram weights, with set_average_edges! method (https://github.com/zombocom/mini_histogram/pull/1)
+
+## 0.1.0
+
+- First

data/README.md

@@ -1,4 +1,4 @@
-# MiniHistogram
+# MiniHistogram [![Build Status](https://travis-ci.org/zombocom/mini_histogram.svg?branch=master)](https://travis-ci.org/zombocom/mini_histogram)
 
 What's a histogram and why should you care? First read [Lies, Damned Lies, and Averages: Perc50, Perc95 explained for Programmers](https://schneems.com/2020/03/17/lies-damned-lies-and-averages-perc50-perc95-explained-for-programmers/). This library lets you build histograms in pure Ruby.
 
@@ -38,6 +38,43 @@ puts histogram.weights
 
 This means that the `array` here had three items between 0.0 and 2.0, four items between 4.0 and 6.0 and three items between 10.0 and 12.0
 
+## Plotting
+
+You can plot!
+
+```ruby
+require 'mini_histogram/plot'
+array = 50.times.map { rand(11.2..11.6) }
+histogram = MiniHistogram.new(array)
+puts histogram.plot
+```
+
+Will generate:
+
+```
+                  ┌                                        ┐
+   [11.2 , 11.25) ┤▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇ 9
+   [11.25, 11.3 ) ┤▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇ 6
+   [11.3 , 11.35) ┤▇▇▇▇▇▇▇▇▇▇▇▇▇ 4
+   [11.35, 11.4 ) ┤▇▇▇▇▇▇▇▇▇▇▇▇▇ 4
+   [11.4 , 11.45) ┤▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇ 11
+   [11.45, 11.5 ) ┤▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇ 5
+   [11.5 , 11.55) ┤▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇ 7
+   [11.55, 11.6 ) ┤▇▇▇▇▇▇▇▇▇▇▇▇▇ 4
+                  └                                        ┘
+                                  Frequency
+```
+
+Integrated plotting is an experimental currently, use with some caution. If you are on Ruby 2.4+ you can pass an instance of MiniHistogram to [unicode_plot.rb](https://github.com/red-data-tools/unicode_plot.rb):
+
+```ruby
+array = 50.times.map { rand(11.2..11.6) }
+histogram = MiniHistogram.new(array)
+puts UnicodePlot.histogram(histogram)
+```
+
+## Alternatives
+
 Alternatives to this gem include https://github.com/mrkn/enumerable-statistics/. I needed this gem to be able to calculate a "shared" or "average" edge value as seen in this PR https://github.com/mrkn/enumerable-statistics/pull/23. So that I could add histograms to derailed benchmarks: https://github.com/schneems/derailed_benchmarks/pull/169. This gem provides a `MiniHistogram.set_average_edges!` method to help there. Also this gem does not require a native extension compilation (faster to install, but performance is slower), and this gem does not extend or monkeypatch an core classes.
 
 [MiniHistogram API Docs](https://rubydoc.info/github/zombocom/mini_histogram/master/MiniHistogram)

data/Rakefile

@@ -19,8 +19,8 @@ task :bench do
 
   array = 1000.times.map { rand }
 
-  edges = MiniHistogram.edges(array)
-  my_weights = MiniHistogram.counts_from_edges(array, edges: edges)
+  histogram = MiniHistogram.new(array)
+  my_weights = histogram.weights
   puts array.histogram.weights == my_weights
   puts array.histogram.weights.inspect
   puts my_weights.inspect
@@ -29,8 +29,7 @@ task :bench do
   Benchmark.ips do |x|
     x.report("enumerable stats") { array.histogram }
     x.report("mini histogram  ") {
-      edges = MiniHistogram.edges(array)
-      MiniHistogram.counts_from_edges(array, edges: edges)
+      MiniHistogram.new(array).weights
     }
     x.compare!
   end

data/lib/mini_histogram.rb

@@ -1,5 +1,4 @@
 require "mini_histogram/version"
-require 'math'
 
 # A class for building histogram info
 #
@@ -20,13 +19,15 @@ require 'math'
 #
 class MiniHistogram
   class Error < StandardError; end
-  attr_reader :array, :left_p
+  attr_reader :array, :left_p, :max
 
-  def initialize(array, left_p: false, edges: nil)
+  def initialize(array, left_p: true, edges: nil)
     @array = array
     @left_p = left_p
     @edges = edges
     @weights = nil
+
+    @min, @max = array.minmax
   end
 
   def edges_min
@@ -37,14 +38,25 @@ class MiniHistogram
     edges.max
   end
 
+  def histogram(*_)
+    self
+  end
+
+  def closed
+    @left_p ? :left : :right
+  end
+
   # Sets the edge value to something new,
   # also clears any previously calculated values
-  def set_edges(value)
-    @edges = value
+  def update_values(edges:, max: )
+    @edges = edges
+    @max = max
     @weights = nil # clear memoized value
   end
 
   def bin_size
+    return 0 if edges.length <= 1
+
     edges[1] - edges[0]
   end
 
@@ -77,11 +89,12 @@ class MiniHistogram
   #   4 values between 4.0 and 6.0 and three values between 10.0 and 12.0
   def weights
     return @weights if @weights
+    return @weights = [] if array.empty?
 
     lo = edges.first
     step = edges[1] - edges[0]
 
-    max_index = ((array.max  - lo) / step).floor
+    max_index = ((@max  - lo) / step).floor
     @weights = Array.new(max_index + 1, 0)
 
     array.each do |x|
@@ -109,16 +122,18 @@ class MiniHistogram
   def edges
     return @edges if @edges
 
-    hi = array.max
-    lo = array.min
+    return @edges = [0.0] if array.empty?
 
-    nbins = sturges * 1.0
+    lo = @min
+    hi = @max
+
+    nbins = sturges.to_f
 
     if hi == lo
-      start = hi
+      start = lo
       step = 1.0
       divisor = 1.0
-      len = 1.0
+      len = 1
     else
       bw = (hi - lo) / nbins
       lbw = Math.log10(bw)
@@ -154,31 +169,37 @@ class MiniHistogram
         start = (lo * divisor).floor
         len = (hi * divisor - start).ceil
       end
+    end
 
-      if left_p
-        while (lo < start/divisor)
-          start -= step
-        end
-
-        while (start + (len - 1)*step)/divisor <= hi
-          len += 1
-        end
-      else
-        while lo <= start/divisor
-          start -= step
-        end
-        while (start + (len - 1)*step)/divisor < hi
-          len += 1
-        end
+    if left_p
+      while (lo < start/divisor)
+        start -= step
       end
 
-      @edges = []
-      len.next.times.each do
-        @edges << start/divisor
-        start += step
+      while (start + (len - 1)*step)/divisor <= hi
+        len += 1
+      end
+    else
+      while lo <= start/divisor
+        start -= step
+      end
+      while (start + (len - 1)*step)/divisor < hi
+        len += 1
       end
-      return @edges
     end
+
+    @edges = []
+    len.times.each do
+      @edges << start/divisor
+      start += step
+    end
+
+    return @edges
+  end
+  alias :edge :edges
+
+  def plot
+    raise "You must `require 'mini_histogram/plot'` to get this feature"
   end
 
   # Given an array of Histograms this function calcualtes
@@ -194,6 +215,8 @@ class MiniHistogram
     steps = array_of_histograms.map(&:bin_size)
     avg_step_size = steps.inject(&:+).to_f / steps.length
 
+    max_value = array_of_histograms.map(&:max).max
+
     max_edge = array_of_histograms.map(&:edges_max).max
     min_edge = array_of_histograms.map(&:edges_min).min
 
@@ -202,8 +225,9 @@ class MiniHistogram
       average_edges << average_edges.last + avg_step_size
     end
 
-    array_of_histograms.each {|h| h.set_edges(average_edges) }
+    array_of_histograms.each {|h| h.update_values(edges: average_edges, max: max_value) }
 
     return array_of_histograms
   end
 end
+

data/lib/mini_histogram/plot.rb

@@ -0,0 +1,716 @@
+# Plots the histogram in unicode characters
+#
+# Thanks to https://github.com/red-data-tools/unicode_plot.rb
+# it could not be used because the dependency enumerable-statistics has a hard
+# lock on a specific version of Ruby and this library needs to support older Rubies
+#
+# Example:
+#
+#   require 'mini_histogram/plot'
+#   array = 50.times.map { rand(11.2..11.6) }
+#   histogram = MiniHistogram.new(array)
+#   puts histogram.plot
+#
+class MiniHistogram
+  def plot(
+    nbins: nil,
+    closed: :left,
+    symbol: "▇",
+    **kw)
+    hist = self.histogram(*[nbins].compact, closed: closed)
+    edge, counts = hist.edge, hist.weights
+    labels = []
+    bin_width = edge[1] - edge[0]
+    pad_left, pad_right = 0, 0
+    (0 ... edge.length).each do |i|
+      val1 = float_round_log10(edge[i], bin_width)
+      val2 = float_round_log10(val1 + bin_width, bin_width)
+      a1 = val1.to_s.split('.', 2).map(&:length)
+      a2 = val2.to_s.split('.', 2).map(&:length)
+      pad_left  = [pad_left,  a1[0], a2[0]].max
+      pad_right = [pad_right, a1[1], a2[1]].max
+    end
+    l_str = hist.closed == :right ? "(" : "["
+    r_str = hist.closed == :right ? "]" : ")"
+    counts.each_with_index do |n, i|
+      val1 = float_round_log10(edge[i], bin_width)
+      val2 = float_round_log10(val1 + bin_width, bin_width)
+      a1 = val1.to_s.split('.', 2).map(&:length)
+      a2 = val2.to_s.split('.', 2).map(&:length)
+      labels[i] = "\e[90m#{l_str}\e[0m" +
+                  (" " * (pad_left - a1[0])) +
+                  val1.to_s +
+                  (" " * (pad_right - a1[1])) +
+                  "\e[90m, \e[0m" +
+                  (" " * (pad_left - a2[0])) +
+                  val2.to_s +
+                  (" " * (pad_right - a2[1])) +
+                  "\e[90m#{r_str}\e[0m"
+    end
+    xscale = kw.delete(:xscale)
+    xlabel = kw.delete(:xlabel) || ValueTransformer.transform_name(xscale, "Frequency")
+    barplot(labels, counts,
+            symbol: symbol,
+            xscale: xscale,
+            xlabel: xlabel,
+            **kw)
+  end
+
+  private def barplot(
+    *args,
+    width: 40,
+    color: :green,
+    symbol: "■",
+    border: :barplot,
+    xscale: nil,
+    xlabel: nil,
+    data: nil,
+    **kw)
+    case args.length
+    when 0
+      data = Hash(data)
+      keys = data.keys.map(&:to_s)
+      heights = data.values
+    when 2
+      keys = Array(args[0])
+      heights = Array(args[1])
+    else
+      raise ArgumentError, "invalid arguments"
+    end
+
+    unless keys.length == heights.length
+      raise ArgumentError, "The given vectors must be of the same length"
+    end
+    unless heights.min >= 0
+      raise ArgumentError, "All values have to be positive. Negative bars are not supported."
+    end
+
+    xlabel ||= ValueTransformer.transform_name(xscale)
+    plot = Barplot.new(heights, width, color, symbol, xscale,
+                       border: border, xlabel: xlabel,
+                       **kw)
+    keys.each_with_index do |key, i|
+      plot.annotate_row!(:l, i, key)
+    end
+
+    plot
+  end
+
+  private def float_round_log10(x, m)
+    if x == 0
+      0.0
+    elsif x > 0
+      x.round(ceil_neg_log10(m) + 1).to_f
+    else
+      -(-x).round(ceil_neg_log10(m) + 1).to_f
+    end
+  end
+
+  private def ceil_neg_log10(x)
+    if roundable?(-Math.log10(x))
+      (-Math.log10(x)).ceil
+    else
+      (-Math.log10(x)).floor
+    end
+  end
+
+  INT64_MIN = -9223372036854775808
+  INT64_MAX =  9223372036854775807
+  private def roundable?(x)
+    x.to_i == x && INT64_MIN <= x && x < INT64_MAX
+  end
+
+  module ValueTransformer
+    PREDEFINED_TRANSFORM_FUNCTIONS = {
+      log: Math.method(:log),
+      ln: Math.method(:log),
+      log10: Math.method(:log10),
+      lg: Math.method(:log10),
+      log2: Math.method(:log2),
+      lb: Math.method(:log2),
+    }.freeze
+
+    def transform_values(func, values)
+      return values unless func
+
+      unless func.respond_to?(:call)
+        func = PREDEFINED_TRANSFORM_FUNCTIONS[func]
+        unless func.respond_to?(:call)
+          raise ArgumentError, "func must be callable"
+        end
+      end
+
+      case values
+      when Numeric
+        func.(values)
+      else
+        values.map(&func)
+      end
+    end
+
+    module_function def transform_name(func, basename="")
+      return basename unless func
+      case func
+      when String, Symbol
+        name = func
+      when ->(f) { f.respond_to?(:name) }
+        name = func.name
+      else
+        name = "custom"
+      end
+      "#{basename} [#{name}]"
+    end
+  end
+
+
+  module BorderMaps
+    BORDER_SOLID = {
+      tl: "┌",
+      tr: "┐",
+      bl: "└",
+      br: "┘",
+      t:  "─",
+      l:  "│",
+      b:  "─",
+      r:  "│"
+    }.freeze
+
+    BORDER_CORNERS = {
+      tl: "┌",
+      tr: "┐",
+      bl: "└",
+      br: "┘",
+      t:  " ",
+      l:  " ",
+      b:  " ",
+      r:  " ",
+    }.freeze
+
+    BORDER_BARPLOT = {
+      tl: "┌",
+      tr: "┐",
+      bl: "└",
+      br: "┘",
+      t:  " ",
+      l:  "┤",
+      b:  " ",
+      r:  " ",
+    }.freeze
+  end
+
+  BORDER_MAP = {
+    solid:   BorderMaps::BORDER_SOLID,
+    corners: BorderMaps::BORDER_CORNERS,
+    barplot: BorderMaps::BORDER_BARPLOT,
+  }.freeze
+
+  module StyledPrinter
+    TEXT_COLORS = {
+      black:         "\033[30m",
+      red:           "\033[31m",
+      green:         "\033[32m",
+      yellow:        "\033[33m",
+      blue:          "\033[34m",
+      magenta:       "\033[35m",
+      cyan:          "\033[36m",
+      white:         "\033[37m",
+      gray:          "\033[90m",
+      light_black:   "\033[90m",
+      light_red:     "\033[91m",
+      light_green:   "\033[92m",
+      light_yellow:  "\033[93m",
+      light_blue:    "\033[94m",
+      light_magenta: "\033[95m",
+      light_cyan:    "\033[96m",
+      normal:        "\033[0m",
+      default:       "\033[39m",
+      bold:          "\033[1m",
+      underline:     "\033[4m",
+      blink:         "\033[5m",
+      reverse:       "\033[7m",
+      hidden:        "\033[8m",
+      nothing:       "",
+    }
+
+    0.upto(255) do |i|
+      TEXT_COLORS[i] = "\033[38;5;#{i}m"
+    end
+
+    TEXT_COLORS.freeze
+
+    DISABLE_TEXT_STYLE = {
+      bold:      "\033[22m",
+      underline: "\033[24m",
+      blink:     "\033[25m",
+      reverse:   "\033[27m",
+      hidden:    "\033[28m",
+      normal:    "",
+      default:   "",
+      nothing:   "",
+    }.freeze
+
+    COLOR_ENCODE = {
+      normal:  0b000,
+      blue:    0b001,
+      red:     0b010,
+      magenta: 0b011,
+      green:   0b100,
+      cyan:    0b101,
+      yellow:  0b110,
+      white:   0b111
+    }.freeze
+
+    COLOR_DECODE = COLOR_ENCODE.map {|k, v| [v, k] }.to_h.freeze
+
+    def print_styled(out, *args, bold: false, color: :normal)
+      return out.print(*args) unless color?(out)
+
+      str = StringIO.open {|sio| sio.print(*args); sio.close; sio.string }
+      color = :nothing if bold && color == :bold
+      enable_ansi = TEXT_COLORS.fetch(color, TEXT_COLORS[:default]) +
+                    (bold ? TEXT_COLORS[:bold] : "")
+      disable_ansi = (bold ? DISABLE_TEXT_STYLE[:bold] : "") +
+                     DISABLE_TEXT_STYLE.fetch(color, TEXT_COLORS[:default])
+      first = true
+      StringIO.open do |sio|
+        str.each_line do |line|
+          sio.puts unless first
+          first = false
+          continue if line.empty?
+          sio.print(enable_ansi, line, disable_ansi)
+        end
+        sio.close
+        out.print(sio.string)
+      end
+    end
+
+    def print_color(out, color, *args)
+      color = COLOR_DECODE[color]
+      print_styled(out, *args, color: color)
+    end
+
+    def color?(out)
+      (out && out.tty?) || false
+    end
+  end
+
+  module BorderPrinter
+    include StyledPrinter
+
+    def print_border_top(out, padding, length, border=:solid, color: :light_black)
+      return if border == :none
+      b = BORDER_MAP[border]
+      print_styled(out, padding, b[:tl], b[:t] * length, b[:tr], color: color)
+    end
+
+    def print_border_bottom(out, padding, length, border=:solid, color: :light_black)
+      return if border == :none
+      b = BORDER_MAP[border]
+      print_styled(out, padding, b[:bl], b[:b] * length, b[:br], color: color)
+    end
+  end
+
+  class Renderer
+    include BorderPrinter
+
+    def self.render(out, plot)
+      new(plot).render(out)
+    end
+
+    def initialize(plot)
+      @plot = plot
+      @out = nil
+    end
+
+    attr_reader :plot
+    attr_reader :out
+
+    def render(out)
+      @out = out
+      init_render
+
+      render_top
+      render_rows
+      render_bottom
+    end
+
+    private
+
+    def render_top
+      # plot the title and the top border
+      print_title(@border_padding, plot.title, p_width: @border_length, color: :bold)
+      puts if plot.title_given?
+
+      if plot.show_labels?
+        topleft_str  = plot.decorations.fetch(:tl, "")
+        topleft_col  = plot.colors_deco.fetch(:tl, :light_black)
+        topmid_str   = plot.decorations.fetch(:t, "")
+        topmid_col   = plot.colors_deco.fetch(:t, :light_black)
+        topright_str = plot.decorations.fetch(:tr, "")
+        topright_col = plot.colors_deco.fetch(:tr, :light_black)
+
+        if topleft_str != "" || topright_str != "" || topmid_str != ""
+            topleft_len  = topleft_str.length
+            topmid_len   = topmid_str.length
+            topright_len = topright_str.length
+            print_styled(out, @border_padding, topleft_str, color: topleft_col)
+            cnt = (@border_length / 2.0 - topmid_len / 2.0 - topleft_len).round
+            pad = cnt > 0 ? " " * cnt : ""
+            print_styled(out, pad, topmid_str, color: topmid_col)
+            cnt = @border_length - topright_len - topleft_len - topmid_len + 2 - cnt
+            pad = cnt > 0 ? " " * cnt : ""
+            print_styled(out, pad, topright_str, "\n", color: topright_col)
+        end
+      end
+
+      print_border_top(out, @border_padding, @border_length, plot.border)
+      print(" " * @max_len_r, @plot_padding, "\n")
+    end
+
+    # render all rows
+    def render_rows
+      (0 ... plot.n_rows).each {|row| render_row(row) }
+    end
+
+    def render_row(row)
+      # Current labels to left and right of the row and their length
+      left_str  = plot.labels_left.fetch(row, "")
+      left_col  = plot.colors_left.fetch(row, :light_black)
+      right_str = plot.labels_right.fetch(row, "")
+      right_col = plot.colors_right.fetch(row, :light_black)
+      left_len  = nocolor_string(left_str).length
+      right_len = nocolor_string(right_str).length
+
+      unless color?(out)
+        left_str  = nocolor_string(left_str)
+        right_str = nocolor_string(right_str)
+      end
+
+      # print left annotations
+      print(" " * plot.margin)
+      if plot.show_labels?
+        if row == @y_lab_row
+          # print ylabel
+          print_styled(out, plot.ylabel, color: :normal)
+          print(" " * (@max_len_l - plot.ylabel_length - left_len))
+        else
+          # print padding to fill ylabel length
+          print(" " * (@max_len_l - left_len))
+        end
+        # print the left annotation
+        print_styled(out, left_str, color: left_col)
+      end
+
+      # print left border
+      print_styled(out, @plot_padding, @b[:l], color: :light_black)
+
+      # print canvas row
+      plot.print_row(out, row)
+
+      #print right label and padding
+      print_styled(out, @b[:r], color: :light_black)
+      if plot.show_labels?
+        print(@plot_padding)
+        print_styled(out, right_str, color: right_col)
+        print(" " * (@max_len_r - right_len))
+      end
+      puts
+    end
+
+    def render_bottom
+      # draw bottom border and bottom labels
+      print_border_bottom(out, @border_padding, @border_length, plot.border)
+      print(" " * @max_len_r, @plot_padding)
+      if plot.show_labels?
+        botleft_str  = plot.decorations.fetch(:bl, "")
+        botleft_col  = plot.colors_deco.fetch(:bl, :light_black)
+        botmid_str   = plot.decorations.fetch(:b, "")
+        botmid_col   = plot.colors_deco.fetch(:b, :light_black)
+        botright_str = plot.decorations.fetch(:br, "")
+        botright_col = plot.colors_deco.fetch(:br, :light_black)
+
+        if botleft_str != "" || botright_str != "" || botmid_str != ""
+          puts
+          botleft_len  = botleft_str.length
+          botmid_len   = botmid_str.length
+          botright_len = botright_str.length
+          print_styled(out, @border_padding, botleft_str, color: botleft_col)
+          cnt = (@border_length / 2.0 - botmid_len / 2.0 - botleft_len).round
+          pad = cnt > 0 ? " " * cnt : ""
+          print_styled(out, pad, botmid_str, color: botmid_col)
+          cnt = @border_length - botright_len - botleft_len - botmid_len + 2 - cnt
+          pad = cnt > 0 ? " " * cnt : ""
+          print_styled(out, pad, botright_str, color: botright_col)
+        end
+
+        # abuse the print_title function to print the xlabel. maybe refactor this
+        puts if plot.xlabel_given?
+        print_title(@border_padding, plot.xlabel, p_width: @border_length)
+      end
+    end
+
+    def init_render
+      @b = BORDER_MAP[plot.border]
+      @border_length = plot.n_columns
+
+      # get length of largest strings to the left and right
+      @max_len_l = plot.show_labels? && !plot.labels_left.empty? ?
+        plot.labels_left.each_value.map {|l| nocolor_string(l).length }.max :
+        0
+      @max_len_r = plot.show_labels? && !plot.labels_right.empty? ?
+        plot.labels_right.each_value.map {|l| nocolor_string(l).length }.max :
+        0
+      if plot.show_labels? && plot.ylabel_given?
+        @max_len_l += plot.ylabel_length + 1
+      end
+
+      # offset where the plot (incl border) begins
+      @plot_offset = @max_len_l + plot.margin + plot.padding
+
+      # padding-string from left to border
+      @plot_padding = " " * plot.padding
+
+      # padding-string between labels and border
+      @border_padding = " " * @plot_offset
+
+      # compute position of ylabel
+      @y_lab_row = (plot.n_rows / 2.0).round - 1
+    end
+
+    def print_title(padding, title, p_width: 0, color: :normal)
+      return unless title && title != ""
+      offset = (p_width / 2.0 - title.length / 2.0).round
+      offset = [offset, 0].max
+      tpad = " " * offset
+      print_styled(out, padding, tpad, title, color: color)
+    end
+
+    def print(*args)
+      out.print(*args)
+    end
+
+    def puts(*args)
+      out.puts(*args)
+    end
+
+    def nocolor_string(str)
+      str.to_s.gsub(/\e\[[0-9]+m/, "")
+    end
+  end
+
+  class Plot
+    include StyledPrinter
+
+    DEFAULT_WIDTH = 40
+    DEFAULT_BORDER = :solid
+    DEFAULT_MARGIN = 3
+    DEFAULT_PADDING = 1
+
+    def initialize(title: nil,
+                   xlabel: nil,
+                   ylabel: nil,
+                   border: DEFAULT_BORDER,
+                   margin: DEFAULT_MARGIN,
+                   padding: DEFAULT_PADDING,
+                   labels: true)
+      @title = title
+      @xlabel = xlabel
+      @ylabel = ylabel
+      @border = border
+      @margin = check_margin(margin)
+      @padding = padding
+      @labels_left = {}
+      @colors_left = {}
+      @labels_right = {}
+      @colors_right = {}
+      @decorations = {}
+      @colors_deco = {}
+      @show_labels = labels
+      @auto_color = 0
+    end
+
+    attr_reader :title
+    attr_reader :xlabel
+    attr_reader :ylabel
+    attr_reader :border
+    attr_reader :margin
+    attr_reader :padding
+    attr_reader :labels_left
+    attr_reader :colors_left
+    attr_reader :labels_right
+    attr_reader :colors_right
+    attr_reader :decorations
+    attr_reader :colors_deco
+
+    def title_given?
+      title && title != ""
+    end
+
+    def xlabel_given?
+      xlabel && xlabel != ""
+    end
+
+    def ylabel_given?
+      ylabel && ylabel != ""
+    end
+
+    def ylabel_length
+      (ylabel && ylabel.length) || 0
+    end
+
+    def show_labels?
+      @show_labels
+    end
+
+    def annotate!(loc, value, color: :normal)
+      case loc
+      when :l
+        (0 ... n_rows).each do |row|
+          if @labels_left.fetch(row, "") == ""
+            @labels_left[row] = value
+            @colors_left[row] = color
+            break
+          end
+        end
+      when :r
+        (0 ... n_rows).each do |row|
+          if @labels_right.fetch(row, "") == ""
+            @labels_right[row] = value
+            @colors_right[row] = color
+            break
+          end
+        end
+      when :t, :b, :tl, :tr, :bl, :br
+        @decorations[loc] = value
+        @colors_deco[loc] = color
+      else
+        raise ArgumentError,
+          "unknown location to annotate (#{loc.inspect} for :t, :b, :l, :r, :tl, :tr, :bl, or :br)"
+      end
+    end
+
+    def annotate_row!(loc, row_index, value, color: :normal)
+      case loc
+      when :l
+        @labels_left[row_index] = value
+        @colors_left[row_index] = color
+      when :r
+        @labels_right[row_index] = value
+        @colors_right[row_index] = color
+      else
+        raise ArgumentError, "unknown location `#{loc}`, try :l or :r instead"
+      end
+    end
+
+    def render(out)
+      Renderer.render(out, self)
+    end
+
+    COLOR_CYCLE = [
+      :green,
+      :blue,
+      :red,
+      :magenta,
+      :yellow,
+      :cyan
+    ].freeze
+
+    def next_color
+      COLOR_CYCLE[@auto_color]
+    ensure
+      @auto_color = (@auto_color + 1) % COLOR_CYCLE.length
+    end
+
+    def to_s
+      StringIO.open do |sio|
+        render(sio)
+        sio.close
+        sio.string
+      end
+    end
+
+    private def check_margin(margin)
+      if margin < 0
+        raise ArgumentError, "margin must be >= 0"
+      end
+      margin
+    end
+
+    private def check_row_index(row_index)
+      unless 0 <= row_index && row_index < n_rows
+        raise ArgumentError, "row_index out of bounds"
+      end
+    end
+  end
+
+  class Barplot < Plot
+    include ValueTransformer
+
+    MIN_WIDTH = 10
+    DEFAULT_COLOR = :green
+    DEFAULT_SYMBOL = "■"
+
+    def initialize(bars, width, color, symbol, transform, **kw)
+      if symbol.length > 1
+        raise ArgumentError, "symbol must be a single character"
+      end
+      @bars = bars
+      @symbol = symbol
+      @max_freq, i = find_max(transform_values(transform, bars))
+      @max_len = bars[i].to_s.length
+      @width = [width, max_len + 7, MIN_WIDTH].max
+      @color = color
+      @symbol = symbol
+      @transform = transform
+      super(**kw)
+    end
+
+    attr_reader :max_freq
+    attr_reader :max_len
+    attr_reader :width
+
+    def n_rows
+      @bars.length
+    end
+
+    def n_columns
+      @width
+    end
+
+    def add_row!(bars)
+      @bars.concat(bars)
+      @max_freq, i = find_max(transform_values(@transform, bars))
+      @max_len = @bars[i].to_s.length
+    end
+
+    def print_row(out, row_index)
+      check_row_index(row_index)
+      bar = @bars[row_index]
+      max_bar_width = [width - 2 - max_len, 1].max
+      val = transform_values(@transform, bar)
+      bar_len = max_freq > 0 ?
+        ([val, 0].max.fdiv(max_freq) * max_bar_width).round :
+        0
+      bar_str = max_freq > 0 ? @symbol * bar_len : ""
+      bar_lbl = bar.to_s
+      print_styled(out, bar_str, color: @color)
+      print_styled(out, " ", bar_lbl, color: :normal)
+      pan_len = [max_bar_width + 1 + max_len - bar_len - bar_lbl.length, 0].max
+      pad = " " * pan_len.round
+      out.print(pad)
+    end
+
+    private def find_max(values)
+      i = j = 0
+      max = values[i]
+      while j < values.length
+        if values[j] > max
+          i, max = j, values[j]
+        end
+        j += 1
+      end
+      [max, i]
+    end
+  end
+end
+

data/lib/mini_histogram/version.rb

@@ -1,3 +1,3 @@
 class MiniHistogram
-  VERSION = "0.1.0"
+  VERSION = "0.2.1"
 end

data/mini_histogram.gemspec

@@ -26,4 +26,7 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   spec.add_development_dependency "m"
+  # Used for comparison testing, but only supports Ruby 2.4+
+  # spec.add_development_dependency "enumerable-statistics"
+  spec.add_development_dependency "benchmark-ips"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mini_histogram
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.1
 platform: ruby
 authors:
 - schneems
-autorequire: 
+autorequire:
 bindir: exe
 cert_chain: []
-date: 2020-03-21 00:00:00.000000000 Z
+date: 2020-09-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: m
@@ -24,6 +24,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: benchmark-ips
+  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: It makes histograms out of Ruby data. How cool is that!? Pretty cool
   if you ask me.
 email:
@@ -32,17 +46,19 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".github/workflows/check_changelog.yml"
 - ".gitignore"
 - ".travis.yml"
+- CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - Gemfile
-- Gemfile.lock
 - LICENSE.txt
 - README.md
 - Rakefile
 - bin/console
 - bin/setup
 - lib/mini_histogram.rb
+- lib/mini_histogram/plot.rb
 - lib/mini_histogram/version.rb
 - mini_histogram.gemspec
 homepage: https://github.com/zombocom/mini_histogram
@@ -50,7 +66,7 @@ licenses:
 - MIT
 metadata:
   homepage_uri: https://github.com/zombocom/mini_histogram
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -66,7 +82,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubygems_version: 3.1.2
-signing_key: 
+signing_key:
 specification_version: 4
 summary: A small gem for building histograms out of Ruby arrays
 test_files: []

data/Gemfile.lock

@@ -1,26 +0,0 @@
-PATH
-  remote: .
-  specs:
-    mini_histogram (0.1.0)
-
-GEM
-  remote: https://rubygems.org/
-  specs:
-    m (1.5.1)
-      method_source (>= 0.6.7)
-      rake (>= 0.9.2.2)
-    method_source (0.9.2)
-    minitest (5.14.0)
-    rake (12.3.3)
-
-PLATFORMS
-  ruby
-
-DEPENDENCIES
-  m
-  mini_histogram!
-  minitest (~> 5.0)
-  rake (~> 12.0)
-
-BUNDLED WITH
-   2.1.2