inkplot 0.1.0 → 0.3.1

data/lib/inkplot/core.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "date"
+
 module Inkplot
   module Data
     module_function
@@ -60,6 +62,64 @@ module Inkplot
     end
   end
 
+  module Histogram
+    module_function
+
+    def points(values, bins)
+      values = Array(values).filter_map { |value| Data.number(value) }
+      raise ArgumentError, "histogram needs at least one finite numeric value" if values.empty?
+
+      edges = edges(values, bins)
+      counts = Array.new(edges.length - 1, 0)
+      values.each do |value|
+        upper = edges.bsearch_index { |edge| edge > value }
+        index = value == edges.last ? counts.length - 1 : upper && (upper - 1)
+        counts[index] += 1 if index&.between?(0, counts.length - 1)
+      end
+      counts.each_index.map { |index| { x: (edges[index] + edges[index + 1]) / 2.0, x0: edges[index], x1: edges[index + 1], y: counts[index] } }
+    end
+
+    def edges(values, bins)
+      return validate_edges(bins) if bins.is_a?(Array)
+
+      low, high = values.minmax
+      if low == high
+        low -= 0.5
+        high += 0.5
+      end
+      count = if bins == :auto
+                sturges = (Math.log2(values.length) + 1).ceil
+                width = 2 * (quantile(values, 0.75) - quantile(values, 0.25)) / (values.length**(1.0 / 3))
+                fd_count = ((high - low) / width).ceil if width.positive? && width.finite?
+                fd_count && fd_count <= values.length ? fd_count : sturges
+              elsif bins.is_a?(Integer) && bins.positive?
+                bins
+              else
+                raise ArgumentError, "bins must be :auto, a positive Integer, or an increasing edge Array"
+              end
+      count = count.clamp(1, values.length) if bins == :auto
+      width = (high - low) / count
+      Array.new(count + 1) { |index| index == count ? high : low + (index * width) }
+    end
+    private_class_method :edges
+
+    def validate_edges(values)
+      edges = values.map { |value| Data.number(value) }
+      raise ArgumentError, "histogram bin edges must be finite and strictly increasing" unless edges.length >= 2 && edges.none?(&:nil?) && edges.each_cons(2).all? { |left, right| left < right }
+
+      edges
+    end
+    private_class_method :validate_edges
+
+    def quantile(values, probability)
+      sorted = values.sort
+      position = (sorted.length - 1) * probability
+      low = position.floor
+      sorted[low] + ((sorted[position.ceil] - sorted[low]) * (position - low))
+    end
+    private_class_method :quantile
+  end
+
   module Ticks
     module_function
 
@@ -104,6 +164,81 @@ module Inkplot
       end
     end
 
+    def time(minimum, maximum, offset: 0)
+      unit, amount = time_interval(maximum - minimum)
+      ticks = if %i[month year].include?(unit)
+                calendar_ticks(minimum, maximum, offset, unit, amount)
+              else
+                time_ticks(minimum, maximum, offset, unit, amount)
+              end
+      ticks.empty? ? [zoned_time(minimum, offset), zoned_time(maximum, offset)].uniq : ticks
+    end
+
+    def time_interval(span)
+      intervals = [
+        [:second, 1, 1], [:second, 5, 5], [:second, 15, 15], [:second, 30, 30],
+        [:minute, 1, 60], [:minute, 5, 300], [:minute, 15, 900], [:minute, 30, 1800],
+        [:hour, 1, 3600], [:hour, 3, 10_800], [:hour, 6, 21_600], [:hour, 12, 43_200],
+        [:day, 1, 86_400], [:day, 2, 172_800], [:week, 1, 604_800], [:week, 2, 1_209_600],
+        [:month, 1, 2_629_746], [:month, 2, 5_259_492], [:month, 3, 7_889_238], [:month, 6, 15_778_476],
+        [:year, 1, 31_556_952], [:year, 2, 63_113_904], [:year, 5, 157_784_760], [:year, 10, 315_569_520]
+      ]
+      unit, amount, = intervals.min_by { |_, _, seconds| Math.log(seconds / [span / 5.0, 1].max).abs }
+      [unit, amount]
+    end
+
+    def time_ticks(minimum, maximum, offset, unit, amount)
+      seconds = { second: 1, minute: 60, hour: 3600, day: 86_400, week: 604_800 }.fetch(unit) * amount
+      anchor = unit == :week ? 345_600 : 0 # 1970-01-05, a Monday.
+      zone_offset = offset || Time.at(minimum).localtime.utc_offset
+      first = (((minimum + zone_offset - anchor) / seconds).ceil * seconds) + anchor - zone_offset
+      values = []
+      value = first
+      while value <= maximum && values.length < 1000
+        values << zoned_time(value, offset)
+        value += seconds
+      end
+      values
+    end
+    private_class_method :time_ticks
+
+    def calendar_ticks(minimum, maximum, offset, unit, amount)
+      first = zoned_time(minimum, offset)
+      last = zoned_time(maximum, offset)
+      if unit == :month
+        month_index = (first.year * 12) + first.month - 1
+        month_index = (month_index.to_f / amount).ceil * amount
+        values = []
+        while month_index <= (last.year * 12) + last.month - 1 && values.length < 1000
+          year, month = month_index.divmod(12)
+          values << time_at(year, month + 1, 1, offset)
+          month_index += amount
+        end
+      else
+        year = ((first.year.to_f / amount).ceil * amount).to_i
+        values = []
+        while year <= last.year && values.length < 1000
+          values << time_at(year, 1, 1, offset)
+          year += amount
+        end
+      end
+      values
+    end
+    private_class_method :calendar_ticks
+
+    def zoned_time(timestamp, offset)
+      time = Time.at(timestamp)
+      offset.nil? ? time.localtime : time.getlocal(offset)
+    end
+    private_class_method :zoned_time
+
+    def time_at(year, month, day, offset)
+      return Time.local(year, month, day) if offset.nil?
+
+      Time.new(year, month, day, 0, 0, 0, offset)
+    end
+    private_class_method :time_at
+
     def number_label(value)
       value.to_i == value ? value.to_i.to_s : format("%.8f", value).sub(/0+\z/, "").sub(/\.\z/, "")
     end
@@ -223,6 +358,130 @@ module Inkplot
       def bandwidth = (@range[1] - @range[0]) / [@domain.length, 1].max
       def format(value) = value.to_s
     end
+
+    class Time
+      attr_reader :domain, :ticks
+      attr_accessor :range
+
+      def initialize(values, options = {})
+        values = values.compact
+        raise ArgumentError, "time axis needs Time or Date values" unless values.all? { |value| value.is_a?(::Time) || value.is_a?(Date) }
+
+        times = values.grep(::Time)
+        zone_names = times.map(&:zone).uniq
+        offsets = values.filter_map { |value| time_offset(value) }.uniq
+        @local_time = !times.empty? && values.none?(DateTime) && times.all? { |value| local_time?(value) }
+        raise ArgumentError, "time axis values must use the same time zone" if !@local_time && (offsets.length > 1 || zone_names.length > 1)
+
+        @offset = @local_time ? nil : offsets.first || 0
+        numbers = values.map { |value| timestamp(value) }
+        low, high = numbers.minmax
+        raise ArgumentError, "time axis needs at least one date or time value" unless low
+
+        if options[:min]
+          validate_bound(options[:min], "minimum")
+
+          low = timestamp(options[:min])
+          raise ArgumentError, "time axis minimum must be a Time or Date" unless low
+        end
+        if options[:max]
+          validate_bound(options[:max], "maximum")
+
+          high = timestamp(options[:max])
+          raise ArgumentError, "time axis maximum must be a Time or Date" unless high
+        end
+        if low == high
+          raise ArgumentError, "time axis minimum must be less than maximum" if options[:min] && options[:max]
+
+          if options[:min]
+            high += 3600
+          elsif options[:max]
+            low -= 3600
+          else
+            low -= 1800
+            high += 1800
+          end
+        end
+        raise ArgumentError, "time axis minimum must be less than maximum" unless low < high
+
+        @domain = [low, high]
+        @tick_unit, = Ticks.time_interval(high - low)
+        @ticks = Ticks.time(low, high, offset: @offset)
+      end
+
+      def map(value)
+        number = timestamp(value)
+        return nil unless number
+
+        @range[0] + ((number - @domain[0]) * (@range[1] - @range[0]) / (@domain[1] - @domain[0]))
+      rescue ArgumentError, TypeError
+        nil
+      end
+
+      def format(value)
+        time = if value.is_a?(::Time)
+                 @local_time ? value.localtime : value.getlocal(@offset)
+               else
+                 as_time(value)
+               end
+        format_string = case @tick_unit
+                        when :second then "%H:%M:%S"
+                        when :minute, :hour then "%H:%M"
+                        when :day, :week then "%Y-%m-%d"
+                        when :month then "%Y-%m"
+                        when :year then "%Y"
+                        end
+        time.strftime(format_string)
+      end
+
+      private
+
+      def time_offset(value)
+        return value.utc_offset if value.is_a?(::Time)
+        return (value.offset * 86_400).to_i if value.is_a?(DateTime)
+
+        nil
+      end
+
+      def local_time?(value)
+        ::Time.at(value.to_r).localtime.zone == value.zone
+      end
+
+      def validate_bound(value, name)
+        raise ArgumentError, "time axis #{name} must be a Time or Date" unless value.is_a?(::Time) || value.is_a?(Date)
+
+        if @local_time
+          valid = value.is_a?(::Time) ? local_time?(value) : value.is_a?(Date) && !value.is_a?(DateTime)
+          raise ArgumentError, "time axis values must use the same time zone" unless valid
+        else
+          bound_offset = time_offset(value)
+          raise ArgumentError, "time axis values must use the same time zone" if bound_offset && bound_offset != @offset
+        end
+      end
+
+      def timestamp(value)
+        return value.to_f if value.is_a?(::Time)
+        return value.to_time.to_f if value.is_a?(DateTime)
+        return date_time(value).to_f if value.is_a?(Date)
+
+        nil
+      end
+
+      def as_time(value)
+        return ::Time.at(value.to_time.to_f).localtime if @local_time && value.is_a?(DateTime)
+        return ::Time.at(value.to_time.to_f).getlocal(@offset) if value.is_a?(DateTime)
+        return date_time(value) if value.is_a?(Date)
+
+        local_zone = ::Time.at(timestamp(value))
+        @local_time ? local_zone.localtime : local_zone.getlocal(@offset)
+      end
+
+      def date_time(value)
+        return ::Time.local(value.year, value.month, value.day) if @local_time
+
+        ::Time.new(value.year, value.month, value.day, 0, 0, 0, @offset)
+      end
+    end
   end
 
   module TextMetrics
@@ -243,7 +502,10 @@ module Inkplot
 
     def font_for(size = 12)
       require "glyphic"
-      return Glyphic.load(Inkplot.config.font, size: size) if Inkplot.config.font
+      if Inkplot.config.font
+        @fonts ||= {}
+        return @fonts[[Inkplot.config.font, size]] ||= Glyphic.load(Inkplot.config.font, size: size)
+      end
 
       Glyphic.default
     rescue LoadError => e
@@ -319,8 +581,8 @@ module Inkplot
 
     def legend(position: :top_right) = @legend_options = { position: position.to_sym }
 
-    def line(x, y = nil, label: nil, color: nil, dash: false, gaps: :break, **)
-      add(:line, Data.points(x, y), label:, color:, dash:, gaps:, **)
+    def line(x, y = nil, label: nil, color: nil, dash: false, gaps: :break, cap: :butt, join: :miter, **)
+      add(:line, Data.points(x, y), label:, color:, dash:, gaps:, cap:, join:, **)
     end
 
     def scatter(x, y = nil, label: nil, color: nil, size: nil, **)
@@ -340,6 +602,10 @@ module Inkplot
       add(:bar, points, label:, color:, horizontal:, stacked:, **)
     end
 
+    def histogram(values, bins: :auto, label: nil, color: nil)
+      add(:histogram, Histogram.points(values, bins), label:, color:)
+    end
+
     def hline(value, label: nil, color: nil, dash: true)
       number = Data.number(value)
       raise ArgumentError, "horizontal rule value must be finite and numeric" unless number
@@ -351,11 +617,29 @@ module Inkplot
       @notes << { type: :vline, value:, label:, color: Theme.validate_color(color), dash: }
     end
 
+    def annotate(x, y, text, color: nil, anchor: :start)
+      raise ArgumentError, "annotation text must not be empty" if text.to_s.empty?
+      raise ArgumentError, "annotation anchor must be :start, :middle, or :end" unless %i[start middle end].include?(anchor.to_sym)
+
+      @notes << { type: :text, x:, y:, text: text.to_s, color: Theme.validate_color(color), anchor: anchor.to_sym }
+    end
+
     def add(type, points, label: nil, color: nil, **options)
-      raise ArgumentError, "unsupported chart mark: #{type}" unless %i[line scatter bar area step].include?(type.to_sym)
+      type = type.to_sym
+      raise ArgumentError, "unsupported chart mark: #{type}" unless %i[line scatter bar area step histogram].include?(type)
       raise ArgumentError, "gaps must be :break or :connect" if options[:gaps] && !%i[break connect].include?(options[:gaps])
 
-      @series << Series.new(type: type.to_sym, points:, label: label&.to_s, color: Theme.validate_color(color), options:)
+      if type == :line
+        options[:cap] = (options[:cap] || :butt).to_sym
+        options[:join] = (options[:join] || :miter).to_sym
+        raise ArgumentError, "line cap must be :butt or :round" unless %i[butt round].include?(options[:cap])
+        raise ArgumentError, "line join must be :miter, :round, or :bevel" unless %i[miter round bevel].include?(options[:join])
+
+        options[:width] = Data.number(options[:width] || 2)
+        raise ArgumentError, "line width must be finite and positive" unless options[:width]&.positive?
+      end
+
+      @series << Series.new(type:, points:, label: label&.to_s, color: Theme.validate_color(color), options:)
       self
     end
   end
@@ -374,10 +658,25 @@ module Inkplot
       Renderers::SVG.render(SceneBuilder.call(self, width: width, height: height))
     end
 
-    def save(path, width: self.width, height: self.height)
+    def to_image(width: self.width, height: self.height, scale: 1)
+      Renderers::PNG.render(SceneBuilder.call(self, width: width, height: height), scale:)
+    end
+
+    def to_png(width: self.width, height: self.height, scale: 1)
+      Renderers::PNG.encode(to_image(width:, height:, scale:))
+    end
+
+    def _repr_svg_ = to_svg
+
+    def to_inlay
+      { svg: to_svg, png: -> { to_png } }
+    end
+
+    def save(path, width: self.width, height: self.height, scale: 1)
       case File.extname(String(path)).downcase
       when ".svg" then File.write(path, to_svg(width:, height:))
-      else raise ArgumentError, "output path must end in .svg"
+      when ".png" then File.binwrite(path, to_png(width:, height:, scale:))
+      else raise ArgumentError, "output path must end in .svg or .png"
       end
       path
     end
@@ -401,7 +700,7 @@ module Inkplot
 
       warn "Inkplot cycles its eight-color palette after eight series." if series.length > Theme::PALETTE.length
       colors = Theme.colors(builder.theme)
-      x_values = series.flat_map { |item| item.points.flat_map { |point| [point[:x], point[:x2]].compact } }
+      x_values = series.flat_map { |item| item.points.flat_map { |point| [point[:x], point[:x0], point[:x1], point[:x2]].compact } }
       y_values = series.flat_map { |item| item.points.map { |point| point[:y] } }
       if series.any? { |item| item.options[:stacked] }
         totals = stacked_totals(series)
@@ -428,6 +727,14 @@ module Inkplot
       legend_items.uniq!(&:first)
       legend_width = [legend_items.map { |label, _| TextMetrics.width(label, 11) }.max.to_f.ceil + 30, 120].max
       right = builder.legend_options[:position].to_s.end_with?("right") && legend_items.length > 1 ? legend_width + 18 : 18
+      plot_width = width - right - left
+      tick_gap = plot_width.to_f / [x_ticks.length - 1, 1].max
+      longest_tick = x_ticks.map { |tick| TextMetrics.width(x_scale.format(tick), 10) }.max.to_f
+      tick_stride = [(longest_tick / [tick_gap, 1].max).ceil, 1].max
+      shown_ticks = x_ticks.each_index.select { |index| (index % tick_stride).zero? || index == x_ticks.length - 1 }
+      shown_gap = plot_width.to_f / [shown_ticks.length - 1, 1].max
+      rotate_ticks = height >= 180 && shown_ticks.any? { |index| TextMetrics.width(x_scale.format(x_ticks[index]), 10) > shown_gap * 0.75 }
+      bottom += 42 if rotate_ticks
       x_scale.range = [left, width - right]
       y_scale.range = [height - bottom, top]
       clip = [left, top, width - right, height - bottom]
@@ -441,13 +748,16 @@ module Inkplot
         elements << { type: :line, class: "grid-line", points: [[left, y], [width - right, y]], stroke: colors[:grid], width: 1 }
         elements << { type: :text, x: left - 8, y: y + 4, text: y_scale.format(tick), fill: colors[:axis], anchor: :end, size: 11 }
       end
-      x_ticks.each_with_index do |tick, _index|
+      x_ticks.each_with_index do |tick, index|
+        next unless shown_ticks.include?(index)
+
         x = x_scale.map(tick)
         next unless x
 
         label = x_scale.format(tick)
         elements << { type: :line, class: "grid-line", points: [[x, top], [x, height - bottom]], stroke: colors[:grid], width: 1 } if x_scale.is_a?(Scales::Band)
-        elements << { type: :text, x:, y: height - bottom + 18, text: label, fill: colors[:axis], anchor: :middle, size: 10 }
+        elements << { type: :text, x:, y: height - bottom + 18, text: label, fill: colors[:axis], anchor: rotate_ticks ? :end : :middle, size: 10,
+                      rotate: rotate_ticks ? -45 : nil }
       end
       elements << { type: :line, class: "axis-line", points: [[left, top], [left, height - bottom], [width - right, height - bottom]], stroke: colors[:axis], width: 1 }
       elements << { type: :text, x: width / 2.0, y: 22, text: builder.title_text, fill: colors[:foreground], anchor: :middle, size: 15 } if builder.title_text
@@ -464,6 +774,19 @@ module Inkplot
       series.each_with_index do |item, index|
         color = item.color || Theme.series_color(index, builder.theme)
         points = item.points
+        if item.type == :histogram
+          points.each do |point|
+            x0 = x_scale.map(point[:x0])
+            x1 = x_scale.map(point[:x1])
+            y0 = y_scale.map(0)
+            y1 = y_scale.map(point[:y])
+            next unless x0 && x1 && y0 && y1
+
+            marks << { type: :rect, class: "histogram-mark", series_index: index, x: x0, y: [y0, y1].min, width: x1 - x0,
+                       height: (y0 - y1).abs, fill: color }
+          end
+          next
+        end
         if item.type == :bar
           current_bar_index = bar_index
           bar_index += 1
@@ -523,7 +846,8 @@ module Inkplot
                 [[px, py]]
               end
             end
-            marks << { type: :line, class: "mark-line", series_index: index, points: coordinates, stroke: color, width: item.options[:width] || 2, dash: item.options[:dash] }
+            marks << { type: :line, class: "mark-line", series_index: index, points: coordinates, stroke: color, width: item.options[:width] || 2,
+                       dash: item.options[:dash], cap: item.options[:cap], join: item.options[:join] }
           end
         when :area
           drawable_segments(drawable, false).each do |segment|
@@ -550,10 +874,20 @@ module Inkplot
         case note[:type]
         when :hline
           y = y_scale.map(note[:value])
-          marks << { type: :line, class: "rule-line", points: [[left, y], [width - right, y]], stroke: color, width: 1.5, dash: note[:dash], label: note[:label] } if y
+          if y
+            marks << { type: :line, class: "rule-line", points: [[left, y], [width - right, y]], stroke: color, width: 1.5, dash: note[:dash] }
+            marks << { type: :text, x: width - right - 4, y: y - 4, text: note[:label], fill: color, anchor: :end, size: 11 } if note[:label]
+          end
         when :vline
           x = x_scale.map(note[:value])
-          marks << { type: :line, class: "rule-line", points: [[x, top], [x, height - bottom]], stroke: color, width: 1.5, dash: note[:dash] } if x
+          if x
+            marks << { type: :line, class: "rule-line", points: [[x, top], [x, height - bottom]], stroke: color, width: 1.5, dash: note[:dash] }
+            marks << { type: :text, x: x + 4, y: top + 12, text: note[:label], fill: color, anchor: :start, size: 11 } if note[:label]
+          end
+        when :text
+          x = x_scale.map(note[:x])
+          y = y_scale.map(note[:y])
+          marks << { type: :text, x:, y:, text: note[:text], fill: color, anchor: note[:anchor], size: 11 } if x && y
         end
       end
 
@@ -572,7 +906,12 @@ module Inkplot
       explicit = options[:scale] || options[:type]
       horizontal_bar = series.any? { |item| item.type == :bar && item.options[:horizontal] }
       bar_band = series.any? { |item| item.type == :bar && ((item.options[:horizontal] && axis == :y) || (!item.options[:horizontal] && axis == :x)) }
-      if explicit == :band || (explicit.nil? && (bar_band || values.any? { |value| !Data.number(value) }))
+      histogram_axis = axis == :x && series.any? { |item| item.type == :histogram }
+      if histogram_axis && explicit == :band
+        raise ArgumentError, "histogram x axis must use a numeric scale"
+      elsif explicit == :time || explicit == "time" || (explicit.nil? && values.any? { |value| value.is_a?(::Time) || value.is_a?(Date) })
+        Scales::Time.new(values, options)
+      elsif explicit == :band || (explicit.nil? && !histogram_axis && (bar_band || values.any? { |value| !Data.number(value) }))
         Scales::Band.new(values, options)
       elsif explicit == :log
         warn "Inkplot ignores zero and negative values on a log axis." if values.any? { |value| (number = Data.number(value)) && !number.positive? }
@@ -581,7 +920,7 @@ module Inkplot
         raise ArgumentError, "unknown #{axis}-axis scale: #{explicit}" if explicit && explicit != :linear
 
         include_zero = series.any? do |item|
-          (axis == :y && %i[bar area].include?(item.type) && !item.options[:horizontal]) ||
+          (axis == :y && %i[bar area histogram].include?(item.type) && !item.options[:horizontal]) ||
             (horizontal_bar && axis == :x && item.options[:horizontal])
         end
         Scales::Linear.new(values, options, include_zero: include_zero)