tessella 0.3.0

data/lib/tessella/kinds/bar.rb

@@ -0,0 +1,344 @@
+# frozen_string_literal: true
+
+module Tessella
+    # Building one bar's row of cells: the fill run, the optional
+    # eighths partial cell, the track run, the value label, padding.
+    # Kept apart from Bar so Bar's own class body stays under budget.
+    module BarCells
+        EIGHTHS = " ▏▎▍▌▋▊▉".chars.freeze
+
+        private
+
+        def cell(char, color = nil) = Cell.new(char: char, color: color)
+
+        def bar_fraction(value, max_val)
+            return 0.0 unless max_val.positive?
+
+            [@xscale.call(value), 0].max.fdiv(max_val)
+        end
+
+        def bar_glyphs(fraction, max_bar_width)
+            return [(fraction * max_bar_width).round, nil] unless @eighths
+
+            units = (fraction * max_bar_width * 8).round
+            full, rem = units.divmod(8)
+            [full, rem.zero? ? nil : EIGHTHS[rem]]
+        end
+
+        def bar_cells(full, partial, color)
+            cells = Array.new(full) { cell(@fill, color) }
+            cells << cell(partial, color) if partial
+            cells
+        end
+
+        def middle_cells(full, partial, max_bar_width)
+            return [] unless @track
+
+            used = full + (partial ? 1 : 0)
+            remain = max_bar_width - used
+            remain.positive? ? Array.new(remain) { cell(@track) } : []
+        end
+
+        def label_cells(value)
+            Axis.label(value).each_char.map { |ch| cell(ch) }
+        end
+
+        def pad_cells(cells, ew)
+            pad = [ew - cells.length, 0].max
+            cells + Array.new(pad) { Cell.blank }
+        end
+    end
+
+    # Bars over values of both signs: the bar area splits at a zero
+    # column into a negative zone and a positive one, each as wide as
+    # its share of the data's span; negative bars grow left from zero,
+    # positive ones right, and the value labels follow the whole area,
+    # so zero is one column on every row. Without a negative value Bar
+    # keeps unicode_plot's layout. A negative bar's fractional end, at
+    # its left, is a right half block (Unicode has no right eighths).
+    module SignedBars
+        RIGHT_HALF = "▐"
+
+        private
+
+        def signed? = @bars.any? { |_, value, _| @xscale.call(value).negative? }
+
+        def signed_rows
+            values = @bars.map { |_, value, _| @xscale.call(value) }
+            max_len = signed_label_width
+            ew = effective_width(max_len)
+            zones = signed_zones(values, [ew - 2 - max_len, 1].max)
+            @bars.each_with_index.map do |(_, value, color), i|
+                signed_row(values[i], value, color, zones, ew)
+            end
+        end
+
+        # scaled places the bar, value (as given) labels it.
+        def signed_row(scaled, value, color, zones, ew)
+            cells = signed_cells(scaled, color, zones)
+            pad_cells(cells + [Cell.blank] + label_cells(value), ew)
+        end
+
+        # Every label, not only the largest value's: "-12.5" can be the
+        # widest, and each row must end at the same column.
+        def signed_label_width
+            @bars.map { |_, value, _| Axis.label(value).length }.max
+        end
+
+        def signed_zones(values, area)
+            neg = -values.min
+            pos = [values.max, 0].max
+            neg_w = (area * neg.fdiv(neg + pos)).round
+            [neg_w, area - neg_w, neg, pos]
+        end
+
+        def signed_cells(value, color, zones)
+            neg_w, pos_w, neg, pos = zones
+            return left_bar(-value.fdiv(neg), neg_w, color) + gap(pos_w) if
+                value.negative?
+
+            fraction = pos.positive? ? value.fdiv(pos) : 0.0
+            gap(neg_w) + right_bar(fraction, pos_w, color)
+        end
+
+        def left_bar(fraction, width, color)
+            full, half = left_glyphs(fraction, width)
+            gap(width - full - half) +
+                Array.new(half) { cell(RIGHT_HALF, color) } +
+                Array.new(full) { cell(@fill, color) }
+        end
+
+        def left_glyphs(fraction, width)
+            return [(fraction * width).round, 0] unless @eighths
+
+            (fraction * width * 2).round.divmod(2)
+        end
+
+        def right_bar(fraction, width, color)
+            cells = bar_cells(*bar_glyphs(fraction, width), color)
+            cells + gap(width - cells.size)
+        end
+
+        def gap(count)
+            Array.new([count, 0].max) { @track ? cell(@track) : Cell.blank }
+        end
+    end
+
+    # Horizontal bars for (label, value) pairs (DESIGN.md, "Chart and
+    # kinds"): rows of cells laid out directly, one per bar, not on a
+    # pixel canvas, handed to Frame with border :bar -- as
+    # unicode_plot's barplot frame. Chart lends option checking and
+    # ascii/colour handling; its canvas and draw_series go unused.
+    class Bar < Chart
+        include BarCells
+        include SignedBars
+        include BarLayouts
+        include ColumnBars
+        include DotRowBars
+        include MultiBars
+        include MultiBarRows
+        include MultiBarColumns
+
+        OPTIONS = (Chart::OPTIONS +
+                   %i[fill eighths track orientation blocks stacked
+                      series]).freeze
+        MIN_WIDTH = 10
+        DEFAULT_FILL = "█"
+        ASCII_FILL = "#"
+        DEFAULT_TRACK = "·"
+        ASCII_TRACK = "."
+
+        def initialize(**opts)
+            super
+            @fill = fill_option(opts)
+            @eighths = @ascii ? false : opts.fetch(:eighths, true)
+            @track = track_option(opts)
+            check_layout!(opts)
+            @bars = []
+        end
+
+        # values: a number per label, or an Array per label, one value a
+        # series (MultiBars).
+        def add(labels, values, color: nil)
+            labels = Array(labels)
+            return add_multi(labels, Array(values)) if
+                Array(values).first.is_a?(Array)
+
+            bar_color = color || auto_color
+            values = Check.finite!(Array(values), "value")
+            Check.same_size!(labels, values, %w[labels values])
+            labels.zip(values).each do |label, value|
+                @bars << [label, value, bar_color]
+            end
+            self
+        end
+
+        private
+
+        def default_border = :bar
+        def default_xlabel_basename = ""
+
+        def fill_option(opts)
+            fill = opts[:fill] || (@ascii ? ASCII_FILL : DEFAULT_FILL)
+            if fill.length != 1
+                raise ArgumentError,
+                      "fill must be one character: #{fill.inspect}"
+            end
+            fill
+        end
+
+        def track_option(opts)
+            return opts[:track] if opts.key?(:track)
+
+            @ascii ? ASCII_TRACK : DEFAULT_TRACK
+        end
+
+        def frame
+            return Frame.new(**multi_frame_options) if multi?
+
+            Frame.new(**(classic? ? frame_options : layout_frame_options))
+        end
+
+        def frame_options
+            { body: rows, border: @border, ascii: @ascii, color: @color_on,
+              title: @opts[:title], xlabel: xlabel, ylabel: @opts[:ylabel],
+              left: left_labels }
+        end
+
+        def xlabel
+            @opts[:xlabel] || auto_xlabel
+        end
+
+        def auto_xlabel
+            xscale = @opts[:xscale]
+            base = default_xlabel_basename
+            return base.empty? ? nil : base unless xscale
+
+            "#{base} [#{xscale}]"
+        end
+
+        def left_labels
+            @bars.each_with_index.to_h { |(label, *), i| [i, label.to_s] }
+        end
+
+        def reference
+            return [0.0, 0] if @bars.empty?
+
+            transformed = @bars.map { |_, value, _| @xscale.call(value) }
+            max_val = transformed.max
+            idx = transformed.index(max_val)
+            [max_val, Axis.label(@bars[idx][1]).length]
+        end
+
+        def effective_width(max_len)
+            [width, max_len + 7, MIN_WIDTH].max
+        end
+
+        def rows
+            return signed_rows if signed?
+
+            max_val, max_len = reference
+            ew = effective_width(max_len)
+            @bars.map do |_, value, color|
+                bar_row(value, color, max_val, max_len, ew)
+            end
+        end
+
+        def bar_row(value, color, max_val, max_len, ew)
+            max_bar_width = [ew - 2 - max_len, 1].max
+            fraction = bar_fraction(value, max_val)
+            full, partial = bar_glyphs(fraction, max_bar_width)
+            cells = bar_cells(full, partial, color)
+            cells += middle_cells(full, partial, max_bar_width)
+            cells << Cell.blank
+            cells += label_cells(value)
+            pad_cells(cells, ew)
+        end
+    end
+
+    # Frequency bars over Stats.histogram's bins (DESIGN.md): the same
+    # engine as Bar, fed bin labels and counts instead of given ones.
+    class Histogram < Bar
+        def add(values, bins: nil, closed: :left, color: nil)
+            values = Check.finite!(Array(values), "value")
+            hist = Stats.histogram(values, bins: bins, closed: closed)
+            @pairs = edge_pairs(hist).first(hist.counts.size)
+            super(bin_labels(hist), hist.counts, color: color)
+        end
+
+        private
+
+        def default_xlabel_basename = "Frequency"
+        def column_value_label = "Frequency"
+
+        # Columns sit on a continuous axis: its two ends, not names.
+        def column_names(_slot)
+            { bottom: [Axis.label(@pairs.first[0]),
+                       Axis.label(@pairs.last[1])] }
+        end
+
+        def group_label(first, last)
+            "#{Axis.label(@pairs[first][0])}..#{Axis.label(@pairs[last][1])}"
+        end
+
+        def bin_labels(hist)
+            pairs = edge_pairs(hist)
+            pad = label_padding(pairs.flatten)
+            lb, rb = hist.closed == :right ? ["(", "]"] : ["[", ")"]
+            pairs.first(hist.counts.size).map do |lo, hi|
+                "#{lb}#{pad_num(lo, pad)}, #{pad_num(hi, pad)}#{rb}"
+            end
+        end
+
+        def edge_pairs(hist)
+            edges = hist.edges
+            step = edges.size > 1 ? edges[1] - edges[0] : 1.0
+            edges.map { |e| bin_pair(e, step) }
+        end
+
+        def bin_pair(edge, step)
+            lo = round_edge(edge, step)
+            [lo, round_edge(lo + step, step)]
+        end
+
+        def round_edge(value, step)
+            digits = round_digits(step)
+            if value.negative?
+                (-(-value).round(digits)).to_f
+            else
+                value.round(digits).to_f
+            end
+        end
+
+        def round_digits(step)
+            return 1 if step.zero?
+
+            v = -Math.log10(step)
+            (v == v.to_i ? v.ceil : v.floor) + 1
+        end
+
+        def label_padding(values)
+            parts = values.map { |v| v.to_s.split(".", 2) }
+            [parts.map { |a| a[0].length }.max,
+             parts.map { |a| (a[1] || "").length }.max]
+        end
+
+        def pad_num(value, pad)
+            left, right = pad
+            whole, frac = value.to_s.split(".", 2)
+            (" " * (left - whole.length)) + value.to_s +
+                (" " * (right - frac.length))
+        end
+    end
+
+    # (labels, values, **opts): a new Bar chart with one set of bars.
+    def self.bar(*, **)
+        Bar.new(**).add(*)
+    end
+
+    # (values, bins: nil, closed: :left, **opts): a histogram over
+    # Stats.histogram's bins.
+    def self.histogram(values, bins: nil, closed: :left, **)
+        Histogram.new(**).add(values, bins: bins, closed: closed)
+    end
+end

data/lib/tessella/kinds/box.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+module Tessella
+    # The five-glyph shapes for one box-and-whisker row, unicode and
+    # ascii, by its position within the three rows a box takes
+    # (DESIGN.md's box, as unicode_plot's boxplot draws it: a corner
+    # border with blank sides, found only here -- Frame has no such
+    # border type, so Box builds it into the body cells instead of
+    # asking Frame for one).
+    module BoxShapes
+        UNICODE_SHAPES = [
+            { min: "╷", line: " ", fill: "─", lbox: "┌",
+              median: "┬", rbox: "┐", max: "╷" },
+            { min: "├", line: "─", fill: " ", lbox: "┤",
+              median: "│", rbox: "├", max: "┤" },
+            { min: "╵", line: " ", fill: "─", lbox: "└",
+              median: "┴", rbox: "┘", max: "╵" }
+        ].freeze
+
+        # One glyph, one ASCII byte: a whisker meeting the box (├ ┤)
+        # and a whisker end cap (╷ ╵) or a vertical box side (│) all
+        # become "|" rather than colliding into each other's corner or
+        # line glyph; a corner or median end (┌ ┐ └ ┘ ┬ ┴) becomes "+";
+        # a horizontal line (─) becomes "-".
+        GLYPH_MAP = {
+            "┌" => "+", "┐" => "+", "└" => "+", "┘" => "+",
+            "┬" => "+", "┴" => "+",
+            "├" => "|", "┤" => "|",
+            "─" => "-", "│" => "|",
+            "╷" => "|", "╵" => "|"
+        }.freeze
+
+        ASCII_SHAPES = UNICODE_SHAPES.map do |shape|
+            shape.transform_values { |ch| GLYPH_MAP.fetch(ch, ch) }
+        end.freeze
+
+        UNICODE_CORNERS = ["┌", "┐", "└", "┘"].freeze
+        ASCII_CORNERS = UNICODE_CORNERS.map { |ch| GLYPH_MAP.fetch(ch, ch) }
+                                       .freeze
+
+        CORNERS = { unicode: UNICODE_CORNERS, ascii: ASCII_CORNERS }.freeze
+
+        private
+
+        def cell(char, color = nil) = Cell.new(char: char, color: color)
+
+        def corners = CORNERS[@ascii ? :ascii : :unicode]
+
+        def shapes = @ascii ? ASCII_SHAPES : UNICODE_SHAPES
+
+        def border_row(top, ew)
+            tl, tr, bl, br = corners
+            left, right = top ? [tl, tr] : [bl, br]
+            [cell(left)] + Array.new(ew) { cell(" ") } + [cell(right)]
+        end
+
+        def shape_row(cols, row, ew, color)
+            chars = Array.new(ew, " ")
+            paint_shape!(chars, cols, shapes[row])
+            [cell(" ")] + chars.map { |ch| cell(ch, color) } + [cell(" ")]
+        end
+
+        def paint_shape!(chars, cols, shape)
+            spans(cols, shape).each do |lo, hi, ch|
+                fill_span!(chars, lo, hi, ch)
+            end
+            place_marks!(chars, cols, shape)
+        end
+
+        def spans(cols, shape)
+            [[cols[0], cols[1] - 1, shape[:line]],
+             [cols[1], cols[2] - 1, shape[:fill]],
+             [cols[2], cols[3] - 1, shape[:fill]],
+             [cols[3], cols[4] - 1, shape[:line]]]
+        end
+
+        def fill_span!(chars, lo, hi, ch)
+            (lo...hi).each { |i| chars[i] = ch }
+        end
+
+        def place_marks!(chars, cols, shape)
+            marks(shape).each_with_index { |ch, i| chars[cols[i] - 1] = ch }
+        end
+
+        def marks(shape)
+            [shape[:min], shape[:lbox], shape[:median], shape[:rbox],
+             shape[:max]]
+        end
+    end
+
+    # One or several box-and-whisker plots over samples (DESIGN.md,
+    # "Chart and kinds"): three rows of cells per box, laid out
+    # directly -- no pixel canvas, no Frame border (see BoxShapes) --
+    # from Stats.percentiles. Chart lends option checking and
+    # ascii/colour handling; its canvas and draw_series go unused.
+    class Box < Chart
+        include BoxShapes
+
+        OPTIONS = (Chart::OPTIONS + %i[orientation]).freeze
+        MIN_WIDTH = 10
+
+        def initialize(**opts)
+            super
+            @boxes = []
+            @orientation = opts.fetch(:orientation, :horizontal)
+            return if BarLayouts::ORIENTATIONS.include?(@orientation)
+
+            raise ArgumentError, "unknown orientation: #{@orientation.inspect}"
+        end
+
+        def add(names, samples, color: nil)
+            box_color = color || auto_color
+            names = Array(names)
+            Check.same_size!(names, Array(samples), %w[names samples])
+            names.zip(samples).each do |name, sample|
+                values = Array(sample).map(&@xscale)
+                raise ValueError, "sample #{name} is empty" if values.empty?
+
+                @boxes << [name.to_s, Check.finite!(values, "sample"),
+                           box_color]
+            end
+            self
+        end
+
+        private
+
+        def frame
+            Frame.new(**(upright? ? upright_options : frame_options))
+        end
+
+        def frame_options
+            { body: rows, border: :none, ascii: @ascii, color: @color_on,
+              title: @opts[:title], xlabel: @opts[:xlabel],
+              ylabel: @opts[:ylabel], left: left_labels }
+        end
+
+        def left_labels
+            @boxes.each_with_index.to_h { |(name, *), i| [(i * 3) + 2, name] }
+                  .reject { |_, v| v.to_s.empty? }
+        end
+
+        def effective_width = [width, MIN_WIDTH].max
+
+        def box_limits
+            values = @boxes.flat_map { |_, sample, _| sample }
+            Axis.limits(values, @opts[:xlim])
+        end
+
+        def rows
+            lo, hi = box_limits
+            ew = effective_width
+            [border_row(true, ew), *box_rows(lo, hi, ew),
+             border_row(false, ew), bottom_row(lo, hi, ew)]
+        end
+
+        def box_rows(lo, hi, ew)
+            @boxes.flat_map do |_, sample, color|
+                box_shape(sample, lo, hi, ew, color)
+            end
+        end
+
+        def box_shape(sample, lo, hi, ew, color)
+            cols = columns(Stats.percentiles(sample, [0, 25, 50, 75, 100]),
+                           lo, hi, ew)
+            (0..2).map { |row| shape_row(cols, row, ew, color) }
+        end
+
+        def columns(values, lo, hi, ew)
+            values.map { |v| scale_column(v, lo, hi, ew) }
+        end
+
+        def scale_column(v, lo, hi, ew)
+            pos = (v - lo).fdiv(hi - lo) * ew
+            pos.round(half: :even).clamp(1, ew).to_i
+        end
+
+        def bottom_row(lo, hi, ew)
+            min_s = Axis.tick(lo)
+            max_s = Axis.tick(hi)
+            mid_s = Axis.tick((lo + hi) / 2.0)
+            bottom_text(min_s, mid_s, max_s, ew).each_char.map { |c| cell(c) }
+        end
+
+        def bottom_text(min_s, mid_s, max_s, ew)
+            cnt1 = left_gap(ew, mid_s, min_s)
+            cnt2 = right_gap(ew, min_s, mid_s, max_s, cnt1)
+            text = min_s + pad(cnt1) + mid_s + pad(cnt2) + max_s
+            pad_to(text, ew + 2)
+        end
+
+        def left_gap(ew, mid_s, min_s)
+            ((ew / 2.0) - (mid_s.length / 2.0) - min_s.length).round
+        end
+
+        def right_gap(ew, min_s, mid_s, max_s, cnt1)
+            ew - max_s.length - min_s.length - mid_s.length + 2 - cnt1
+        end
+
+        def pad(count) = count.positive? ? " " * count : ""
+
+        def pad_to(text, len)
+            return text[0, len] if text.length >= len
+
+            text + (" " * (len - text.length))
+        end
+    end
+
+    # (names, samples, **opts): a new Box chart; samples is an Array
+    # of Arrays, one per name.
+    def self.box(*, **)
+        Box.new(**).add(*)
+    end
+end

data/lib/tessella/kinds/box_upright.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module Tessella
+    # orientation: :vertical for Box: each box three columns wide, the
+    # whiskers running up and down, the value axis on the left (top,
+    # middle and bottom ticks), the names under the boxes. Rows from
+    # the top: a cap at the maximum, the whisker, the box from Q3 to
+    # Q1 with the median across it, the whisker, a cap at the minimum.
+    # When two of them land on one row, the later in that order wins,
+    # so the median always shows. Kept apart from Box so Box's own
+    # class body stays under budget.
+    module UprightBoxes
+        UPRIGHT = {
+            cap_top: "╶┬╴", cap_bottom: "╶┴╴", whisker: " │ ",
+            side: "│ │", q3: "┌┴┐", q1: "└┬┘", median: "├─┤"
+        }.freeze
+
+        UPRIGHT_ASCII = {
+            cap_top: "-+-", cap_bottom: "-+-", whisker: " | ",
+            side: "| |", q3: "+-+", q1: "+-+", median: "|-|"
+        }.freeze
+
+        private
+
+        def upright? = @orientation == :vertical
+
+        def upright_options
+            lo, hi = upright_limits
+            slot = upright_slot
+            { body: upright_body(lo, hi, slot), border: :box, ascii: @ascii,
+              color: @color_on, title: @opts[:title], xlabel: @opts[:xlabel],
+              ylabel: @opts[:ylabel], left: upright_ticks(lo, hi),
+              under: upright_names(slot) }
+        end
+
+        def upright_limits
+            values = @boxes.flat_map { |_, sample, _| sample }
+            Axis.limits(values, @opts[:ylim])
+        end
+
+        def upright_height = @opts.fetch(:height, Chart::DEFAULT_HEIGHT)
+
+        # Three columns and a gap, wider when a name needs it.
+        def upright_slot
+            names = @boxes.map { |name, *| Width.of(name) }
+            [names.max.to_i + 1, 4].max
+        end
+
+        def upright_body(lo, hi, slot)
+            rows = Array.new(upright_height) { [] }
+            @boxes.each do |_, sample, color|
+                glyphs = upright_column(sample, lo, hi)
+                pad = (slot - 3) / 2
+                rows.each_with_index do |row, r|
+                    row.concat(upright_cells(glyphs[r], pad, slot, color))
+                end
+            end
+            rows
+        end
+
+        def upright_cells(glyphs, pad, slot, color)
+            text = (" " * pad) + glyphs + (" " * (slot - pad - 3))
+            text.chars.map do |ch|
+                ch == " " ? Cell.blank : Cell.new(char: ch, color: color)
+            end
+        end
+
+        # One three-character string per row, top first.
+        def upright_column(sample, lo, hi)
+            at = Stats.percentiles(sample, [100, 75, 50, 25, 0])
+                      .map { upright_row(it, lo, hi) }
+            column = Array.new(upright_height, "   ")
+            upright_marks(at).each do |(from, to), part|
+                (from..to).each { column[it] = upright_glyphs[part] }
+            end
+            column
+        end
+
+        # Row spans in paint order: whiskers, caps, box sides, the box
+        # edges, the median last.
+        def upright_marks(at)
+            max, q3, med, q1, min = at
+            [[[max, q3], :whisker], [[q1, min], :whisker],
+             [[max, max], :cap_top], [[min, min], :cap_bottom],
+             [[q3, q1], :side], [[q3, q3], :q3], [[q1, q1], :q1],
+             [[med, med], :median]]
+        end
+
+        def upright_glyphs = @ascii ? UPRIGHT_ASCII : UPRIGHT
+
+        def upright_row(value, lo, hi)
+            share = (hi - value).fdiv(hi - lo)
+            (share * (upright_height - 1)).round.clamp(0, upright_height - 1)
+        end
+
+        def upright_ticks(lo, hi)
+            last = upright_height - 1
+            { 0 => Axis.tick(hi), (last / 2) => Axis.tick((lo + hi) / 2.0),
+              last => Axis.tick(lo) }
+        end
+
+        def upright_names(slot)
+            @boxes.map { |name, *| Width.center(name, slot) }.join.rstrip
+        end
+    end
+
+    class Box
+        include UprightBoxes
+    end
+end