tessella 0.3.0

data/lib/tessella/kinds/heatmap.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module Tessella
+    # A heatmap (DESIGN.md, "Chart and kinds"): a matrix of values as a
+    # grid of cells, each cell_width: columns wide (2 by default, near
+    # square in a terminal), shaded by value -- along a ramp (" ░▒▓█",
+    # ASCII " .:-=+*#%@") without colour, or as █ coloured along a
+    # colormap under color: true (a viridis-like blend by default;
+    # colormap: takes gradient stops as Color does). Rows are named by
+    # ylabels: on the left, columns by xlabels: under the frame when
+    # they fit, and a key right of the frame gives the range. min: and
+    # max: fix the range, so maps drawn apart share one scale. The
+    # matrix sets the size, so width: and height: are refused.
+    class Heatmap < Chart
+        OPTIONS = (Chart::OPTIONS - %i[width height xlim ylim canvas xscale] +
+                   %i[xlabels ylabels cell_width colormap min max]).freeze
+        RAMP = " ░▒▓█"
+        ASCII_RAMP = " .:-=+*#%@"
+        VIRIDIS = %w[#440154 #3b528b #21918c #5ec962 #fde725].freeze
+
+        def add(matrix)
+            rows = Array(matrix).map { Check.finite!(Array(it), "value") }
+            if rows.empty? || rows.map(&:size).uniq.size != 1 || rows[0].empty?
+                raise ArgumentError, "a heatmap needs rows of one length"
+            end
+            @matrix = rows
+            check_colormap!
+            self
+        end
+
+        private
+
+        def default_border = :box
+
+        def cell_width
+            Check.positive_integer!(@opts.fetch(:cell_width, 2), "cell_width")
+        end
+
+        def ramp = @ascii ? ASCII_RAMP : RAMP
+        def colormap = @opts.fetch(:colormap, VIRIDIS)
+
+        def check_colormap!
+            Color::Gradient.check!(colormap) if @opts.key?(:colormap)
+        end
+
+        def range
+            values = @matrix.flatten
+            lo = @opts.fetch(:min, values.min)
+            hi = @opts.fetch(:max, values.max)
+            Check.finite!([lo, hi], "min/max")
+            raise ArgumentError, "min #{lo} is above max #{hi}" if lo > hi
+
+            [lo, hi]
+        end
+
+        # 0..1 for v within the range; the middle when it is flat.
+        def share(v, lo, hi)
+            hi == lo ? 0.5 : (v.clamp(lo, hi) - lo).fdiv(hi - lo)
+        end
+
+        def heat_cell(v, lo, hi)
+            s = share(v, lo, hi)
+            if @color_on
+                color = Color::Gradient.at(colormap, (s * 255).round, 256)
+                return Cell.new(char: @ascii ? "#" : "█", color: color)
+            end
+            Cell.new(char: ramp[(s * (ramp.length - 1)).round], color: nil)
+        end
+
+        def body
+            lo, hi = range
+            @matrix.map do |row|
+                row.flat_map do |v|
+                    Array.new(cell_width) { heat_cell(v, lo, hi) }
+                end
+            end
+        end
+
+        def frame
+            Frame.new(**heat_options)
+        end
+
+        def heat_options
+            { body: body, border: @border, ascii: @ascii, color: @color_on,
+              title: @opts[:title], xlabel: @opts[:xlabel],
+              ylabel: @opts[:ylabel], left: row_names, right: key,
+              **column_names }
+        end
+
+        def row_names
+            Array(@opts[:ylabels]).each_with_index.to_h { |n, i| [i, n.to_s] }
+        end
+
+        # The key: the top of the range beside the first row, the bottom
+        # beside the last, each after its own shade.
+        # A one-row map shows the range as lo..hi instead.
+        def key
+            lo, hi = range
+            last = @matrix.size - 1
+            return { 0 => "#{Axis.label(lo)}..#{Axis.label(hi)}" } if
+                last.zero?
+
+            { 0 => "#{key_glyph(hi, lo, hi)} #{Axis.label(hi)}",
+              last => "#{key_glyph(lo, lo, hi)} #{Axis.label(lo)}" }
+        end
+
+        # The key's shade; words under colour, as the key itself is not
+        # coloured.
+        def key_glyph(v, lo, hi)
+            return v == hi ? "max" : "min" if @color_on
+
+            heat_cell(v, lo, hi).char
+        end
+
+        def column_names
+            names = Array(@opts[:xlabels]).map(&:to_s)
+            return {} if names.empty?
+            return { bottom: [names.first, names.last] } unless
+                names.all? { Width.of(it) < cell_width }
+
+            { under: names.map { Width.center(it, cell_width) }.join.rstrip }
+        end
+    end
+
+    # (matrix, xlabels: nil, ylabels: nil, cell_width: 2, colormap: nil,
+    # min: nil, max: nil, **opts): a new Heatmap.
+    def self.heatmap(matrix, **)
+        Heatmap.new(**).add(matrix)
+    end
+end

data/lib/tessella/kinds/line.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+module Tessella
+    # A connected path through (x, y) points (DESIGN.md, "Chart and
+    # kinds"): the x = 0 / y = 0 axis lines draw when in range, as
+    # unicode_plot's lineplot does. area: true fills under the path
+    # instead, from the canvas floor up, btop-style; under color: true
+    # its cells take gradient:'s colours by height, bottom band first.
+    class Line < Chart
+        include Sideways
+        include DateAxis
+        include ErrorBars
+        include Threshold
+
+        OPTIONS = (Chart::OPTIONS +
+                   %i[area gradient orientation yscale xdate threshold
+                      above below]).freeze
+        GRADIENT = %i[green yellow red].freeze
+
+        def initialize(**opts)
+            super
+            check_area!(opts)
+        end
+
+        private
+
+        # An area is measured from zero: the value axis takes in 0
+        # unless its limits are given.
+        def zero_floor? = @opts[:area]
+        def fills? = @opts[:area]
+
+        def draw_series(canvas, series)
+            return canvas.lines(series.x, series.y, color: series.color) unless
+                @opts[:area]
+
+            canvas.area(series.x, series.y, color: area_color(series),
+                                            across: @sideways)
+        end
+
+        # The gradient as a cell row -> colour map (row 0 the top), or
+        # the series' own colour when gradient: false.
+        def area_color(series)
+            stops = @opts.fetch(:gradient, GRADIENT)
+            return series.color unless stops
+
+            return ->(col) { Color::Gradient.at(stops, col, width) } if
+                @sideways
+
+            rows = height
+            ->(row) { Color::Gradient.at(stops, rows - 1 - row, rows) }
+        end
+
+        def check_area!(opts)
+            stops = opts[:gradient]
+            return if stops.nil? || stops == false
+
+            raise ArgumentError, "gradient: needs area: true" unless opts[:area]
+
+            Color::Gradient.check!(stops)
+        end
+    end
+
+    # Unconnected points (DESIGN.md): the same axis lines as Line, with
+    # no path drawn between points.
+    class Scatter < Chart
+        include Sideways
+        include DateAxis
+        include ErrorBars
+        include Threshold
+
+        OPTIONS = (Chart::OPTIONS + %i[orientation yscale xdate threshold
+                                       above below]).freeze
+
+        private
+
+        def draw_series(canvas, series)
+            canvas.points(series.x, series.y, color: series.color)
+        end
+    end
+
+    # A step path through (x, y): style :post holds the previous y
+    # until the new x, then steps to the new y; :pre steps to the new y
+    # first, at the previous x -- as unicode_plot's stairs does.
+    class Stairs < Line
+        STYLES = %i[post pre].freeze
+
+        def initialize(style: :post, **)
+            raise ArgumentError, "unknown style: #{style.inspect}" unless
+                STYLES.include?(style)
+
+            @style = style
+            super(**)
+        end
+
+        # A marked series marks the points given, not the step corners.
+        def add(*args, name: nil, color: nil, mark: nil)
+            return super if mark
+
+            x, y = args.length == 1 ? [nil, *args] : args
+            xs = Array(x || (1..y.length))
+            sx, sy = step_coords(xs, Array(y))
+            super(sx, sy, name: name, color: color)
+        end
+
+        private
+
+        def step_coords(x, y)
+            @style == :post ? post_steps(x, y) : pre_steps(x, y)
+        end
+
+        def post_steps(x, y)
+            xs = [x.first]
+            ys = [y.first]
+            (1...x.size).each do |i|
+                xs << x[i] << x[i]
+                ys << y[i - 1] << y[i]
+            end
+            [xs, ys]
+        end
+
+        def pre_steps(x, y)
+            xs = [x.first]
+            ys = [y.first]
+            (1...x.size).each do |i|
+                xs << x[i - 1] << x[i]
+                ys << y[i] << y[i]
+            end
+            [xs, ys]
+        end
+    end
+
+    # Hit-count shading over (x, y) points (DESIGN.md): always the
+    # :density canvas -- matching unicode_plot's own densityplot
+    # default, no axis lines.
+    class Density < Scatter
+        private
+
+        def canvas_type = :density
+        def draw_grid? = false
+    end
+
+    # (x = nil, y, yerr: nil, **opts): a new Line chart with one series.
+    def self.line(*, name: nil, mark: nil, yerr: nil, **)
+        add_series(Line.new(**), *, name: name, mark: mark, yerr: yerr)
+    end
+
+    # (x = nil, y, yerr: nil, **opts): a new Scatter chart with one
+    # series.
+    def self.scatter(*, name: nil, mark: nil, yerr: nil, **)
+        add_series(Scatter.new(**), *, name: name, mark: mark, yerr: yerr)
+    end
+
+    # (x = nil, y, style: :post, **opts): a new Stairs chart, style:
+    # :pre or :post.
+    def self.stairs(*, style: :post, name: nil, mark: nil, **)
+        add_series(Stairs.new(style: style, **), *, name: name,
+                                                    mark: mark)
+    end
+
+    # (x = nil, y, **opts): a new Density chart with one series.
+    def self.density(*, name: nil, mark: nil, **)
+        add_series(Density.new(**), *, name: name, mark: mark)
+    end
+
+    # name: and mark: apply to the first series, as add's do to the
+    # others
+    def self.add_series(chart, *, name: nil, mark: nil, yerr: nil)
+        extra = yerr ? { yerr: yerr } : {}
+        chart.add(*, name: name, mark: mark, **extra)
+        chart
+    end
+    private_class_method :add_series
+end

data/lib/tessella/kinds/multibar.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Tessella
+    # Bars of several series (DESIGN.md, "Chart and kinds"): Bar#add
+    # given an Array per label -- one value a series -- draws them
+    # grouped, a bar per series under each label with a blank row
+    # between labels, or stacked: true, the series end to end in one bar
+    # labelled with its total. Series are told apart by fill glyph
+    # (Legend::FILLS, █ ▓ ▒ ░ ... ASCII # = + @ ..., so at most 12) and,
+    # under color: true, by colour; the legend sits right of the frame,
+    # or wrapped under it, named by series: (1..n otherwise). Values
+    # must be 0 or more; the braille, block and half layouts refuse
+    # several series. Kept apart so Bar stays under budget.
+    module MultiBars
+        include MultiBarFine
+
+        FILLS = Legend::FILLS
+        ASCII_FILLS = Legend::ASCII_FILLS
+
+        private
+
+        def multi? = !@groups.nil?
+
+        def add_multi(labels, rows)
+            raise ArgumentError, "xscale: takes one series" if @opts[:xscale]
+
+            Check.same_size!(labels, rows, %w[labels groups])
+            @groups ||= []
+            rows.each_with_index do |values, i|
+                vals = Check.finite!(Array(values), "value")
+                check_series_size!(vals)
+                Legend.fills!(vals.size, "series")
+                @groups << [labels[i], vals]
+            end
+            self
+        end
+
+        def check_series_size!(vals)
+            n = @groups.first&.last&.size || vals.size
+            return if vals.size == n && n.positive?
+
+            raise ArgumentError, "every label needs #{n} values, one a " \
+                                 "series: got #{vals.size}"
+        end
+
+        def series_count = @groups.first.last.size
+
+        def series_fill(i) = (@ascii ? ASCII_FILLS : FILLS)[i]
+
+        # Eighths (▏..▉, ▁..▇) are solid: they end only a █ series, so a
+        # ▓ or ▒ bar is never closed by what looks like another series.
+        def eighths_for?(fill) = @eighths && fill == FILLS.first
+        def series_color(i) = Color::NAMES[i % Color::NAMES.size]
+
+        def series_names
+            names = Array(@opts[:series]).map(&:to_s)
+            return names if names.size == series_count
+
+            (1..series_count).map(&:to_s)
+        end
+
+        def legend_entries
+            series_names.each_with_index.map do |name, i|
+                "#{series_fill(i)} #{name}"
+            end
+        end
+
+        # The legend beside the frame, an entry a row, or under it,
+        # wrapped to the frame's width, when there are more series
+        # than rows.
+        def legend_options(rows)
+            entries = legend_entries
+            if entries.size <= rows
+                return { right: entries.each_with_index.to_h { |e, i| [i, e] } }
+            end
+
+            { under: Legend.wrap(entries, width) }
+        end
+
+        def multi_values!
+            values = @groups.flat_map(&:last)
+            return if values.all? { it >= 0 }
+
+            raise ArgumentError, "bars of several series need values of " \
+                                 "0 or more"
+        end
+
+        def multi_frame_options
+            multi_values!
+            unless @blocks == :eighths
+                raise ArgumentError, "blocks: #{@blocks} draws one series"
+            end
+            return multi_column_options if @orientation == :vertical
+
+            multi_row_options
+        end
+    end
+end

data/lib/tessella/kinds/multibar_columns.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module Tessella
+    # Columns of several series (MultiBars): side by side in each
+    # label's slot, or stacked into one column; the value axis runs
+    # from 0 to the largest value, or total.
+    module MultiBarColumns
+        private
+
+        def multi_column_options
+            body, slot, top = multi_columns
+            { body: body, border: :box, ascii: @ascii, color: @color_on,
+              title: @opts[:title],
+              ylabel: @opts[:ylabel] || column_value_label,
+              left: { (body.size - 1) => "0", 0 => Axis.label(top) },
+              **column_captions(body.size, slot) }
+        end
+
+        # The names under the columns and the legend: beside the frame,
+        # or, when it has more entries than rows and the names already
+        # hold the line under it, on the lines after the x label.
+        def column_captions(rows, slot)
+            names = group_names(slot)
+            legend = legend_options(rows)
+            xlabel = @opts[:xlabel]
+            if legend[:under] && names[:under]
+                xlabel = [xlabel, legend.delete(:under)].compact.join("\n")
+            end
+            { xlabel: xlabel, **legend, **names }
+        end
+
+        def multi_columns
+            @opts[:stacked] ? stacked_columns : grouped_columns
+        end
+
+        # [gap, column width]: a blank column between groups when the
+        # width allows, the rest shared between all the columns.
+        def group_geometry
+            g = @groups.size
+            n = series_count
+            gap = (g * n) + g - 1 <= width ? 1 : 0
+            [gap, [(width - ((g - 1) * gap)) / (g * n), 1].max]
+        end
+
+        def grouped_columns
+            gap, cw = group_geometry
+            max = @groups.flat_map(&:last).max
+            rows = Array.new(column_height) { [] }
+            @groups.each_with_index do |(_, vals), gi|
+                blank_columns(rows, gi.zero? ? 0 : gap)
+                vals.each_with_index do |v, i|
+                    grouped_column(rows, v, i, [max, cw])
+                end
+            end
+            [rows, (series_count * cw) + gap, max]
+        end
+
+        def grouped_column(rows, value, index, scale)
+            max, cw = scale
+            fill = series_fill(index)
+            units = column_units(share(value, max.to_f), value, fill)
+            append_column(rows, units, cw, series_color(index), fill)
+        end
+
+        # Eighths of a cell for a █ series, whole cells for the others.
+        def column_units(fraction, value, fill)
+            units = rise_units(fraction, value)
+            eighths_for?(fill) ? units : ((units + 4) / 8) * 8
+        end
+
+        def stacked_columns
+            gap, cw = rise_geometry(@groups.size)
+            max = @groups.map { it.last.sum }.max
+            rows = Array.new(column_height) { [] }
+            @groups.each_with_index do |(_, vals), gi|
+                blank_columns(rows, gi.zero? ? 0 : gap)
+                stacked_column(rows, vals, max.to_f, cw)
+            end
+            [rows, cw + gap, max]
+        end
+
+        def stacked_column(rows, vals, max, cw)
+            heights = stack_heights(vals, max)
+            rows.each_with_index do |row, r|
+                level = (column_height - 1 - r) * 8
+                glyph = stack_cell(heights, level, vals.size)
+                row.concat(Array.new(cw) { glyph })
+            end
+        end
+
+        # [total, the cumulative top of each series], in eighths.
+        def stack_heights(vals, max)
+            ends = stack_ends(vals, max)
+            return [ends.last, ends] if fine?
+
+            top = series_fill(vals.size - 1)
+            [column_units(share(vals.sum, max), vals.sum, top), ends]
+        end
+
+        def stack_ends(vals, max)
+            vals.each_index.map do |i|
+                rise_units(share(vals[0..i].sum, max), vals[0..i].sum)
+            end
+        end
+
+        # Whole cells take the series at their middle; the top cell's
+        # eighths take the last series' colour.
+        def stack_cell(heights, level, count)
+            total, ends = heights
+            return Cell.blank unless total > level
+            return fine_cell(ends, level, ColumnBars::RISE) if fine?
+
+            if total < level + 8
+                return Cell.new(char: ColumnBars::RISE[total - level],
+                                color: series_color(count - 1))
+            end
+
+            s = ends.index { level + 4 < it } || (count - 1)
+            Cell.new(char: series_fill(s), color: series_color(s))
+        end
+
+        def group_names(slot)
+            names = @groups.map { it.first.to_s }
+            return { bottom: [names.first, names.last] } unless
+                names.all? { Width.of(it) <= slot }
+
+            { under: names.map { Width.center(it, slot) }.join.rstrip }
+        end
+    end
+end

data/lib/tessella/kinds/multibar_fine.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Tessella
+    # Stacked bars under color: true, to the eighth: where one series
+    # ends inside a cell and the next goes on, the cell is an eighths
+    # glyph (▏..▉ across, ▁..▇ up) inked in the first series' colour on
+    # the next one's background, so the boundary falls between whole
+    # cells no more. Without colour the two halves of such a cell could
+    # not be told apart, so the boundary stays on a whole cell there.
+    module MultiBarFine
+        private
+
+        def fine? = @color_on && @eighths
+
+        # A horizontal stacked row: cells to the total's last eighth.
+        def fine_row(vals, scale)
+            max, area, ew = scale
+            ends = fine_ends(vals, max, area)
+            full, rem = ends.last.divmod(8)
+            cells = (0...(full + (rem.zero? ? 0 : 1))).map do |col|
+                fine_cell(ends, col * 8, Bar::EIGHTHS)
+            end
+            finish_row(cells, [full, rem.zero? ? nil : true, area],
+                       vals.sum, ew)
+        end
+
+        # Each series' cumulative end, in eighths of a cell.
+        def fine_ends(vals, max, area)
+            vals.each_index.map do |i|
+                (share(vals[0..i].sum, max) * area * 8).round
+            end
+        end
+
+        # The cell from eighth lo: the series covering lo, whole when it
+        # covers the cell, else split with the series after it.
+        def fine_cell(ends, low, glyphs)
+            a = ends.index { it > low }
+            return cell(series_fill(a), series_color(a)) if ends[a] >= low + 8
+
+            b = ends.index { it > ends[a] }
+            colors = b ? [series_color(a), series_color(b)] : series_color(a)
+            cell(glyphs[ends[a] - low], colors)
+        end
+    end
+end

data/lib/tessella/kinds/multibar_rows.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Tessella
+    # Horizontal bars of several series (MultiBars): grouped rows, a
+    # blank row between labels, or stacked rows labelled with totals.
+    module MultiBarRows
+        private
+
+        def multi_row_options
+            ew = effective_width(multi_labels.map(&:length).max)
+            area = [ew - 2 - multi_labels.map(&:length).max, 1].max
+            rows, left = multi_rows(area, ew)
+            { body: rows, border: @border, ascii: @ascii, color: @color_on,
+              title: @opts[:title], xlabel: xlabel, ylabel: @opts[:ylabel],
+              left: left, **legend_options(rows.size) }
+        end
+
+        def multi_rows(area, ew)
+            @opts[:stacked] ? stacked_rows(area, ew) : grouped_rows(area, ew)
+        end
+
+        # The value labels a bar ends with: each value, or each total.
+        def multi_labels
+            return @groups.map { Axis.label(it.last.sum) } if @opts[:stacked]
+
+            @groups.flat_map { |_, vals| vals.map { Axis.label(it) } }
+        end
+
+        def grouped_rows(area, ew)
+            scale = [@groups.flat_map(&:last).max.to_f, area, ew]
+            rows = []
+            left = {}
+            @groups.each_with_index do |(label, vals), g|
+                rows << pad_cells([], ew) if g.positive?
+                left[rows.size] = label.to_s
+                vals.each_with_index { |v, i| rows << series_row(v, i, scale) }
+            end
+            [rows, left]
+        end
+
+        def series_row(value, index, scale)
+            max, area, ew = scale
+            full, partial = series_glyphs(share(value, max), area, index)
+            color = series_color(index)
+            cells = Array.new(full) { cell(series_fill(index), color) }
+            cells << cell(partial, color) if partial
+            finish_row(cells, [full, partial, area], value, ew)
+        end
+
+        # The track after the bar, a blank, the value, padding.
+        def finish_row(cells, bar, value, ew)
+            cells += middle_cells(*bar)
+            pad_cells(cells + [Cell.blank] + label_cells(value), ew)
+        end
+
+        def series_glyphs(fraction, area, index)
+            return bar_glyphs(fraction, area) if
+                eighths_for?(series_fill(index))
+
+            [(fraction * area).round, nil]
+        end
+
+        def stacked_rows(area, ew)
+            scale = [@groups.map { it.last.sum }.max.to_f, area, ew]
+            rows = @groups.map do |_, vals|
+                fine? ? fine_row(vals, scale) : stacked_row(vals, scale)
+            end
+            [rows, @groups.each_with_index.to_h { |(l, _), i| [i, l.to_s] }]
+        end
+
+        # Each series runs to the cell its cumulative share reaches; the
+        # total's eighths end the bar in the last series' colour.
+        def stacked_row(vals, scale)
+            max, area, ew = scale
+            last = vals.size - 1
+            full, partial = series_glyphs(share(vals.sum, max), area, last)
+            ends = cumulative_ends(vals, max, area, full)
+            cells = (0...full).map { segment_cell(ends, it) }
+            cells << cell(partial, series_color(last)) if partial
+            finish_row(cells, [full, partial, area], vals.sum, ew)
+        end
+
+        def cumulative_ends(vals, max, area, full)
+            sums = vals.each_index.map { vals[0..it].sum }
+            sums.map { (share(it, max) * area).round.clamp(0, full) }
+        end
+
+        def segment_cell(ends, col)
+            s = ends.index { col < it } || (ends.size - 1)
+            cell(series_fill(s), series_color(s))
+        end
+    end
+end