tessella 0.3.0

data/lib/tessella/kinds/candlestick.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+module Tessella
+    # The x labels under a candlestick chart: the first and last x, as
+    # dates when x holds times (xdate: or the span's format, as on a date
+    # axis). Kept apart so Candlestick stays under budget.
+    module CandleLabels
+        private
+
+        def x_label(value)
+            return Axis.label(value) unless DateAxis.time?(value)
+
+            Time.at(DateAxis.seconds(value)).utc.strftime(x_format)
+        end
+
+        def x_format
+            return @opts[:xdate] if @opts[:xdate].is_a?(String)
+
+            seconds = @x.map { DateAxis.seconds(it) }
+            span = seconds.max - seconds.min
+            DateAxis::SPANS.find { |least, _| span >= least }.last
+        end
+    end
+
+    # Candlesticks (DESIGN.md, "Chart and kinds"): an open/high/low/
+    # close series spread over width: (40 by default), each candle as
+    # wide as its share of the width allows, a blank column between
+    # candles -- a column each and no gap when they do not fit. The
+    # wick │ runs from low to high in the candle's middle column; the
+    # body from open to close fills the candle: █ for an up candle
+    # (close at or above open), ▒ for a down one, ─ when open and close
+    # share a row; under color: true up is green and down red. The
+    # value axis is on the left, the first and last x under the frame.
+    class Candlestick < Chart
+        include CandleLabels
+
+        OPTIONS = (Chart::OPTIONS - %i[canvas xscale xlim] +
+                   %i[xdate]).freeze
+        PRICES = %i[open high low close].freeze
+        GLYPHS = { up: "█", down: "▒", flat: "─", wick: "│" }.freeze
+        ASCII_GLYPHS = { up: "#", down: "=", flat: "-", wick: "|" }.freeze
+
+        # x (1..n when nil), and the four prices as Arrays.
+        def add(x = nil, **prices)
+            values = price_values(prices)
+            check_candles!(values)
+            @x = Array(x || (1..values[0].size))
+            Check.same_size!(@x, values[0], %w[x prices])
+            @candles = values.transpose
+            self
+        end
+
+        private
+
+        def default_border = :box
+
+        def price_values(prices)
+            missing = PRICES - prices.keys
+            raise ArgumentError, "missing #{missing.join(", ")}" if
+                missing.any?
+
+            PRICES.map { Check.finite!(Array(prices[it]), it.to_s) }
+        end
+
+        def check_candles!(values)
+            same_length!(values)
+            bad = values.transpose.index do |o, h, l, c|
+                l > [o, c].min || h < [o, c].max
+            end
+            return unless bad
+
+            raise ValueError, "candle #{bad + 1}: low and high must hold " \
+                              "open and close"
+        end
+
+        def same_length!(values)
+            sizes = values.map(&:size).uniq
+            return if sizes.size == 1 && sizes.first.positive?
+
+            raise ArgumentError, "open, high, low and close must be Arrays " \
+                                 "of one length"
+        end
+
+        def glyphs = @ascii ? ASCII_GLYPHS : GLYPHS
+
+        def limits = Axis.limits(@candles.flatten, @opts[:ylim])
+
+        def row_of(value, lo, hi)
+            share = (hi - value).fdiv(hi - lo)
+            (share * (height - 1)).round.clamp(0, height - 1)
+        end
+
+        def gap = (2 * @candles.size) - 1 <= width ? 1 : 0
+
+        # Columns a candle: its share of the width, less the gap.
+        def candle_width
+            [((width + gap) / @candles.size) - gap, 1].max
+        end
+
+        def body
+            lo, hi = limits
+            rows = Array.new(height) { [] }
+            @candles.each_with_index do |candle, i|
+                rows.each { it << Cell.blank } if i.positive? && gap == 1
+                column = candle_column(candle, lo, hi)
+                rows.each_with_index { |row, r| row.concat(widen(column[r])) }
+            end
+            rows
+        end
+
+        # A cell across the candle's width: a body fills it, a wick
+        # stays one column, in the middle.
+        def widen(cell)
+            cw = candle_width
+            return Array.new(cw) { cell } unless cell.char == glyphs[:wick]
+
+            Array.new(cw) { it == (cw - 1) / 2 ? cell : Cell.blank }
+        end
+
+        def candle_column(candle, lo, hi)
+            open, high, low, close = candle
+            up = close >= open
+            top, bottom = [open, close].map { row_of(it, lo, hi) }.minmax
+            color = up ? :green : :red
+            (0...height).map do |r|
+                candle_cell(r, [row_of(high, lo, hi), row_of(low, lo, hi)],
+                            [top, bottom], [up, color])
+            end
+        end
+
+        def candle_cell(row, wick, body, kind)
+            up, color = kind
+            if row.between?(*body)
+                return Cell.new(char: body_glyph(body, up), color: color)
+            end
+            return Cell.blank unless row.between?(*wick)
+
+            Cell.new(char: glyphs[:wick], color: color)
+        end
+
+        def body_glyph(body, up)
+            return glyphs[:flat] if body[0] == body[1]
+
+            glyphs[up ? :up : :down]
+        end
+
+        def frame = Frame.new(**candle_options)
+
+        def candle_options
+            lo, hi = limits
+            { body: body, border: @border, ascii: @ascii, color: @color_on,
+              title: @opts[:title], xlabel: @opts[:xlabel],
+              ylabel: @opts[:ylabel],
+              left: { 0 => Axis.tick(hi), (height - 1) => Axis.tick(lo) },
+              bottom: [x_label(@x.first), x_label(@x.last)] }
+        end
+    end
+
+    # (x = nil, open:, high:, low:, close:, **opts): a new Candlestick.
+    def self.candlestick(x = nil, **opts)
+        prices = opts.slice(*Candlestick::PRICES)
+        Candlestick.new(**opts.except(*Candlestick::PRICES)).add(x, **prices)
+    end
+end

data/lib/tessella/kinds/columns.rb

@@ -0,0 +1,259 @@
+# frozen_string_literal: true
+
+module Tessella
+    # The bar layouts besides unicode_plot's (DESIGN.md, "Chart and
+    # kinds"): orientation: :vertical draws columns, and blocks:
+    # :braille, :block, :sextant or :octant packs several bars into
+    # one character -- braille and octant four bars per text row (two
+    # columns per character when vertical), sextant three, block two.
+    # Values must be zero or more. Kept apart from Bar so Bar's own
+    # class body stays under budget.
+    module BarLayouts
+        BLOCKS = %i[eighths braille block quadrant half sextant octant].freeze
+        ORIENTATIONS = %i[horizontal vertical].freeze
+
+        private
+
+        # unicode_plot's own layout: horizontal bars of eighths.
+        def classic? = @orientation == :horizontal && @blocks == :eighths
+
+        def check_layout!(opts)
+            @orientation = pick!(opts, :orientation, ORIENTATIONS)
+            @blocks = pick!(opts, :blocks, BLOCKS)
+            upright_track!(opts)
+            return if @blocks == :eighths
+
+            if @ascii
+                raise ArgumentError, "blocks: #{@blocks} conflicts with " \
+                                     "ascii: true"
+            end
+            glyph_options!(opts)
+        end
+
+        # Columns draw no track: one given is refused, not ignored.
+        def upright_track!(opts)
+            return unless @orientation == :vertical && opts.key?(:track)
+
+            raise ArgumentError, "track: only with horizontal bars"
+        end
+
+        def pick!(opts, key, allowed)
+            value = opts.fetch(key, allowed.first)
+            return value if allowed.include?(value)
+
+            raise ArgumentError, "unknown #{key}: #{value.inspect}"
+        end
+
+        def glyph_options!(opts)
+            given = %i[fill eighths track] & opts.keys
+            return if given.empty?
+
+            raise ArgumentError, "#{given.join(", ")} only with blocks: " \
+                                 ":eighths, not :#{@blocks}"
+        end
+
+        # Each bar's value through xscale, refused below zero.
+        def layout_values
+            values = @bars.map { |_, value, _| @xscale.call(value) }
+            return values if values.all? { it >= 0 }
+
+            raise ArgumentError, "a #{@orientation} #{@blocks} bar chart " \
+                                 "needs values of 0 or more"
+        end
+
+        def layout_frame_options
+            raise ArgumentError, "no bars to draw" if @bars.empty?
+
+            values = layout_values
+            max = values.max.to_f
+            common = { ascii: @ascii, color: @color_on, title: @opts[:title] }
+            return common.merge(column_options(values, max)) if
+                @orientation == :vertical
+
+            common.merge(dot_row_options(values, max))
+        end
+
+        # The value axis's top: the largest bar's value, as given.
+        def top_label
+            transformed = @bars.map { |_, value, _| @xscale.call(value) }
+            Axis.label(@bars[transformed.index(transformed.max)][1])
+        end
+
+        def share(value, max) = max.positive? ? value / max : 0.0
+
+        # At least one step for a value above zero, so a small bar
+        # never draws as an empty one.
+        def pixels(value, max, span) = steps(share(value, max) * span, value)
+
+        def steps(exact, value)
+            value.positive? ? [exact.round, 1].max : exact.round
+        end
+    end
+
+    # orientation: :vertical -- columns rising from a floor, value
+    # axis on the left (0 to the largest value), names under the
+    # columns when each fits its slot, else the first and the last.
+    module ColumnBars
+        RISE = " ▁▂▃▄▅▆▇".chars.freeze
+
+        private
+
+        def column_options(values, max)
+            body, slot = column_body(values, max)
+            { body: body, border: :box, xlabel: @opts[:xlabel],
+              ylabel: @opts[:ylabel] || column_value_label,
+              left: { (body.size - 1) => "0", 0 => top_label },
+              **column_names(slot) }
+        end
+
+        def column_body(values, max)
+            return rise_columns(values, max) if @blocks == :eighths
+
+            dot_columns(values, max)
+        end
+
+        def column_height = @opts.fetch(:height, Chart::DEFAULT_HEIGHT)
+
+        # One text column per bar, eighths of a cell: " ▁▂▃▄▅▆▇█".
+        def rise_columns(values, max)
+            gap, bw = rise_geometry(values.size)
+            rows = Array.new(column_height) { [] }
+            values.each_with_index do |v, i|
+                blank_columns(rows, i.zero? ? 0 : gap)
+                append_column(rows, rise_units(share(v, max), v), bw,
+                              color_of(i))
+            end
+            [rows, bw + gap]
+        end
+
+        def blank_columns(rows, count)
+            rows.each { it.concat(Array.new(count) { Cell.blank }) }
+        end
+
+        def color_of(index) = @bars[index][2]
+
+        # [gap, column width]: a blank column between bars when they
+        # fit with one, and the width shared out between them.
+        def rise_geometry(n)
+            gap = (2 * n) - 1 <= width ? 1 : 0
+            [gap, [((width + gap) / n) - gap, 1].max]
+        end
+
+        def rise_units(fraction, value)
+            return steps(fraction * column_height, value) * 8 unless @eighths
+
+            steps(fraction * column_height * 8, value)
+        end
+
+        def append_column(rows, units, bw, color, fill = @fill)
+            rows.each_with_index do |row, r|
+                level = (column_height - 1 - r) * 8
+                row.concat(Array.new(bw) do
+                    rise_cell(units - level, color, fill)
+                end)
+            end
+        end
+
+        def rise_cell(eighths, color, fill = @fill)
+            return Cell.new(char: fill, color: color) if eighths >= 8
+            return Cell.blank unless eighths.positive?
+
+            Cell.new(char: RISE[eighths], color: color)
+        end
+
+        # One pixel column per bar on a braille or block canvas, so a
+        # character holds two columns; wider when the width allows,
+        # with a one-pixel gap between bars then.
+        def dot_columns(values, max)
+            canvas = dot_canvas(column_chars(values.size), column_height)
+            per = [canvas.pixel_width / values.size, 1].max
+            values.each_with_index do |v, i|
+                dot_column(canvas, i * per, per,
+                           [pixels(v, max, canvas.pixel_height), color_of(i)])
+            end
+            [canvas.rows, slot_chars(per)]
+        end
+
+        # A bar per pixels wide at px, one pixel left as its gap.
+        def dot_column(canvas, px, per, bar)
+            height, color = bar
+            (per > 1 ? per - 1 : 1).times do |k|
+                canvas.column_bar(px + k, height, color: color)
+            end
+        end
+
+        def column_chars(n) = [width, (n + across - 1) / across].max
+
+        # Bars side by side in one character: 2, or 1 with halves.
+        def across = @blocks == :half ? 1 : 2
+
+        # A name's room under a dot column, when bars fill whole cells.
+        def slot_chars(per) = (per % across).zero? ? per / across : nil
+
+        def dot_canvas(cols, rows)
+            Canvas.build(canvas_name, width: cols, height: rows,
+                                      xlim: [0, 1], ylim: [0, 1])
+        end
+
+        # Half blocks run along the bar: "▄" up a column, "▌" across.
+        def canvas_name
+            return :half_wide if @blocks == :half && @orientation == :horizontal
+
+            @blocks
+        end
+
+        # Names under the columns when each fits its slot (a column's
+        # width and its gap), else the first and the last at the ends.
+        def column_names(slot)
+            names = column_labels
+            if slot && names.all? { Width.of(it) <= slot }
+                { under: names.map { Width.center(it, slot) }.join.rstrip }
+            else
+                { bottom: [names.first, names.last] }
+            end
+        end
+
+        def column_labels = @bars.map { |label, *| label.to_s }
+        def column_value_label = nil
+    end
+
+    # blocks: other than eighths, horizontal: one pixel row per bar, so
+    # a text row holds four bars (braille, octant), three (sextant) or
+    # two (block), each row
+    # named by the bars it holds; the value axis runs under the frame
+    # from 0 to the largest value.
+    module DotRowBars
+        private
+
+        def dot_row_options(values, max)
+            canvas = dot_canvas(width, dot_row_count(values.size))
+            values.each_with_index do |v, i|
+                canvas.row_bar(i, pixels(v, max, canvas.pixel_width),
+                               color: color_of(i))
+            end
+            { body: canvas.rows, border: :box, xlabel: xlabel,
+              ylabel: @opts[:ylabel], left: dot_row_labels(canvas),
+              bottom: ["0", top_label] }
+        end
+
+        def dot_row_count(n) = (n + per_row - 1) / per_row
+
+        # Bars a text row holds: the canvas's pixel rows per character.
+        def per_row
+            { braille: 4, octant: 4, sextant: 3, half: 1 }.fetch(@blocks, 2)
+        end
+
+        def dot_row_labels(canvas)
+            (0...canvas.height).to_h do |r|
+                first = r * per_row
+                last = [first + per_row, @bars.size].min - 1
+                [r, group_label(first, last)]
+            end
+        end
+
+        def group_label(first, last)
+            names = column_labels
+            first == last ? names[first] : "#{names[first]}..#{names[last]}"
+        end
+    end
+end

data/lib/tessella/kinds/date_axis.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Tessella
+    # A date axis for the plotted kinds (DESIGN.md, "Chart and kinds"):
+    # x values that are times -- a Time, or anything with to_time (a
+    # Date, a DateTime) -- are plotted as seconds and labelled as dates,
+    # in UTC so the output does not depend on the machine. xdate: names
+    # the strftime format; by default it follows the span: a day or more
+    # "%Y-%m-%d", an hour or more "%m-%d %H:%M", less "%H:%M:%S". xlim:
+    # may be times too; without it the axis spans the data exactly, as
+    # a rounded number of seconds means nothing. A Date counts from
+    # midnight UTC. A date axis takes no xscale:. Sideways (an
+    # orientation: :horizontal chart) the dates label the vertical axis.
+    module DateAxis
+        DAY = 86_400
+
+        # One time, or one repeated, spans a day either side: a zero
+        # span has no scale.
+        SPANS = [[86_400, "%Y-%m-%d"], [3600, "%m-%d %H:%M"],
+                 [0, "%H:%M:%S"]].freeze
+
+        # A Time, or a Date/DateTime (whose to_time the date library adds).
+        def self.time?(value)
+            value.is_a?(Time) || value.respond_to?(:to_time)
+        end
+
+        def self.seconds(value)
+            return value unless time?(value)
+            return value.to_f if value.is_a?(Time)
+            return value.to_time.to_f if value.respond_to?(:hour)
+
+            Time.utc(value.year, value.month, value.day).to_f
+        end
+
+        def initialize(**opts)
+            limit = opts[:xlim]
+            if limit&.any? { DateAxis.time?(it) }
+                opts = opts.merge(xlim: limit.map { DateAxis.seconds(it) })
+                @xdate = true
+            end
+            super
+        end
+
+        def add(*args, **)
+            return super unless args.length == 2 && dated?(args[0])
+
+            date_axis!
+            super(args[0].map { DateAxis.seconds(it) }, args[1], **)
+        end
+
+        private
+
+        def dated?(xs) = xs&.any? { DateAxis.time?(it) }
+
+        # The date axis spans the data exactly unless xlim: is given.
+        def xlim = date_limits(:x, !@sideways) || super
+        def ylim = date_limits(:y, @sideways) || super
+
+        def date_limits(axis, dated)
+            return nil unless dated && date_axis? && !@opts[:xlim]
+
+            lo, hi = @series.flat_map(&axis).minmax
+            lo == hi ? [lo - DAY, hi + DAY] : [lo, hi]
+        end
+
+        def date_axis? = @xdate || @opts[:xdate]
+
+        def date_axis!
+            raise ArgumentError, "a date axis takes no xscale:" if
+                @opts[:xscale]
+
+            @xdate = true
+        end
+
+        def frame_options(canvas, xl, yl)
+            options = super
+            return options unless date_axis?
+
+            return options.merge(left: date_left(yl)) if @sideways
+
+            options.merge(bottom: [date_label(xl.first, xl),
+                                   date_label(xl.last, xl)])
+        end
+
+        def date_left(yl)
+            { 0 => date_label(yl.last, yl),
+              (height - 1) => date_label(yl.first, yl) }
+        end
+
+        def date_label(seconds, limits)
+            Time.at(seconds).utc.strftime(date_format(limits))
+        end
+
+        def date_format(limits)
+            format = @opts[:xdate]
+            return format if format.is_a?(String)
+
+            span = (limits.last - limits.first).abs
+            SPANS.find { |least, _| span >= least }.last
+        end
+    end
+end

data/lib/tessella/kinds/error_bars.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Tessella
+    # Error bars for the plotted kinds (DESIGN.md, "Chart and kinds"):
+    # add's yerr: is an error a point -- the bar runs y - e .. y + e --
+    # or [lows, highs] for asymmetric ones. Bounds are taken in data
+    # units, then through yscale:. Each point gets a segment along the
+    # value axis (across, sideways), drawn after the series or its
+    # marks, and the axis limits take the bars in.
+    module ErrorBars
+        def add(*args, yerr: nil, **)
+            super(*args, **)
+            return self unless yerr
+
+            ys = Array(args.last)
+            (@errors ||= {})[@series.size - 1] = error_bounds(ys, yerr)
+            self
+        end
+
+        private
+
+        # [lows, highs] in plotted units.
+        def error_bounds(ys, yerr)
+            lo, hi = yerr.first.is_a?(Array) ? yerr : [yerr, yerr]
+            [lo, hi].each { error_size!(it, ys) }
+            lows = ys.zip(lo).map { |y, e| @yscale.call(y - e) }
+            highs = ys.zip(hi).map { |y, e| @yscale.call(y + e) }
+            [Check.finite!(lows, "y - yerr"), Check.finite!(highs, "y + yerr")]
+        end
+
+        def error_size!(errors, ys)
+            Check.finite!(Array(errors), "yerr")
+            Check.same_size!(Array(errors), ys, %w[yerr y])
+            return if errors.all? { !it.negative? }
+
+            raise ArgumentError, "yerr must be 0 or more"
+        end
+
+        def draw_or_mark(canvas, series)
+            super
+            bounds = @errors&.[](series_index(series))
+            draw_errors(canvas, series, bounds) if bounds
+        end
+
+        # The series by its data, not its identity: threshold: draws a
+        # recoloured copy (Series#with keeps the same x and y Arrays).
+        def series_index(series)
+            @series.index { it.x.equal?(series.x) && it.y.equal?(series.y) }
+        end
+
+        def draw_errors(canvas, series, bounds)
+            positions = @sideways ? series.y : series.x
+            positions.each_with_index do |pos, i|
+                lo = bounds[0][i]
+                hi = bounds[1][i]
+                if @sideways
+                    canvas.line(lo, pos, hi, pos, color: series.color)
+                else
+                    canvas.line(pos, lo, pos, hi, color: series.color)
+                end
+            end
+        end
+
+        def axis_values(axis)
+            values = super
+            return values unless @errors && axis == (@sideways ? :x : :y)
+
+            values + @errors.values.flatten
+        end
+    end
+end