squid 0.0.0 → 1.0.0.beta1

data/examples/squid/line_width.rb

@@ -0,0 +1,9 @@
+# By default, <code>chart</code> uses a line width of 3 for line charts.
+#
+# You can use the <code>:line_width</code> option to customize this value.
+#
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::ManualBuilder::Example.generate(filename) do
+  data = {views: {2013 => 182, 2014 => 46, 2015 => 802000000000000000000}}
+  chart data, type: :line, line_width: 10
+end

data/examples/squid/lines.rb

@@ -0,0 +1,11 @@
+# By default, <code>chart</code> plots a column for each series.
+#
+# You can use the <code>:type</code> option to plot a line chart instead.
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::ManualBuilder::Example.generate(filename) do
+  data = {views: {2013 => 182, 2014 => -46, 2015 => 88},
+        uniques: {2013 => 104, 2014 => 27, 2015 => 14}}
+  chart data, type: :line, labels: true
+end
+
+

data/examples/squid/point.rb

@@ -0,0 +1,9 @@
+# By default, <code>chart</code> plots a column chart.
+#
+# You can use the <code>:type</code> option to plot a point chart instead.
+#
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::ManualBuilder::Example.generate(filename) do
+  data = {views: {Safari: 45.20001, Firefox: 63.3999, Chrome: 21.4}}
+  chart data, type: :point
+end

data/examples/squid/points.rb

@@ -0,0 +1,9 @@
+# By default, <code>chart</code> plots a column for each series.
+#
+# You can use the <code>:type</code> option to plot a point chart instead.
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::ManualBuilder::Example.generate(filename) do
+  data = {views: {2013 => 182, 2014 => 46, 2015 => 88},
+        uniques: {2013 => -104, 2014 => 27, 2015 => 14}}
+  chart data, type: :point, labels: true
+end

data/examples/squid/squid.rb

@@ -0,0 +1,48 @@
+Prawn::ManualBuilder::Example.generate 'squid.pdf' do
+  package 'squid' do |p|
+    p.name = 'Squid'
+
+    p.intro do
+      prose('
+        Prawn is a great library to generate PDF files from Ruby, but lacks high-level components to generate graphs.
+        Squid integrates Prawn by providing methods to plot charts in PDF files with few lines of code.
+        This manual shows:
+      ')
+
+      list(
+        'How to create graphs',
+      )
+    end
+
+    p.section 'Basics' do |s|
+      s.example 'basic'
+      s.example 'legend'
+    end
+    
+    p.section 'Chart types' do |s|
+      s.example 'point'
+      s.example 'line'
+    end
+    
+    p.section 'Styling' do |s|
+      s.example 'height'
+      s.example 'baseline'
+      s.example 'ticks'
+      s.example 'every'
+      s.example 'gridlines'
+      s.example 'format'
+      s.example 'border'
+      s.example 'labels'
+      s.example 'line_width'
+      s.example 'legend_offset'
+    end
+    
+    p.section 'Multiple series' do |s|
+      s.example 'columns'
+      s.example 'lines'
+      s.example 'points'
+      s.example 'stacks'
+      s.example 'two_axis'
+    end
+  end
+end

data/examples/squid/stacks.rb

@@ -0,0 +1,10 @@
+# By default, <code>chart</code> plots multiple columns next to each other.
+#
+# You can use the <code>:type</code> option to plot stacked columns instead.
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::ManualBuilder::Example.generate(filename) do
+  data = {views: {2013 => 196, 2014 => 66, 2015 => -282},
+           hits: {2013 => 100, 2014 => -12, 2015 => 82},
+        uniques: {2013 => -114, 2014 => 47, 2015 => -14}}
+  chart data, type: :stack, labels: true
+end

data/examples/squid/ticks.rb

@@ -0,0 +1,9 @@
+# By default, <code>chart</code> plots ticks above the categories.
+#
+# You can use the <code>:ticks</code> option to disable this behavior.
+#
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::ManualBuilder::Example.generate(filename) do
+  data = {views: {2013 => 182, 2014 => 46, 2015 => 802000000000000000000}}
+  chart data, ticks: false
+end

data/examples/squid/two_axis.rb

@@ -0,0 +1,10 @@
+# By default, ..
+#
+# You can use ..
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::ManualBuilder::Example.generate(filename) do
+
+  data = {views: {2013 => 182, 2014 => 46, 2015 => 88},
+       earnings: {2013 => 104_323, 2014 => 27_234, 2015 => 14_123}}
+  chart data, type: :two_axis, border: true
+end

data/lib/squid/axis.rb

@@ -0,0 +1,61 @@
+require 'squid/format'
+require 'active_support/core_ext/enumerable' # for Array#sum
+
+module Squid
+  # @private
+  class Axis
+    include Format
+    attr_reader :data
+
+    def initialize(data, steps:, stack:, format:, &block)
+      @data, @steps, @stack, @format = data, steps, stack, format
+      @width_proc = block if block_given?
+    end
+
+    def minmax
+      @minmax ||= [min, max].compact.map do |number|
+        approximate number
+      end
+    end
+
+    def labels
+      min, max = minmax
+      values = if @data.empty? || @steps.zero?
+        []
+      else
+        max.step(by: (min - max)/@steps.to_f, to: min)
+      end
+      @labels ||= values.map{|value| format_for value, @format}
+    end
+
+    def width
+      @width ||= labels.map{|label| label_width label}.max || 0
+    end
+
+  private
+
+    def label_width(label)
+      @width_proc.call label if @width_proc
+    end
+
+    def min
+      [values.first.min, 0].min if @data.any?
+    end
+
+    def max
+      [values.last.max, @steps].max if @data.any?
+    end
+
+    def values
+      @values ||= if @stack
+        @data.transpose.map{|a| a.compact.partition{|n| n < 0}.map(&:sum)}.transpose
+      else
+        [@data.flatten.compact]
+      end
+    end
+
+    def approximate(number)
+      number_to_rounded(number, significant: true, precision: 2).to_f
+    end
+  end
+end

data/lib/squid/axis_label.rb

@@ -0,0 +1,15 @@
+module Squid
+  class AxisLabel
+    def self.for(axis, height:, align:)
+      height.step(0, -height/(axis.labels.size-1).to_f).map.with_index do |y, i|
+        new y: y, label: axis.labels[i], align: align, width: axis.width
+      end
+    end
+
+    attr_reader :label, :y, :align, :width
+
+    def initialize(label:, y:, align:, width:)
+      @label, @y, @align, @width = label, y, align, width
+    end
+  end
+end

data/lib/squid/config.rb

@@ -0,0 +1,46 @@
+require 'squid/configuration'
+
+module Squid
+  # Provides methods to read and write global configuration settings.
+  #
+  # A typical usage is to set the default dimensions and colors for charts.
+  #
+  # @example Set the default height for Squid graphs:
+  #   Squid.configure do |config|
+  #     config.height = 150
+  #   end
+  #
+  # Note that Squid.configure has precedence over values through with
+  # environment variables (see {Squid::Configuration}).
+  #
+  module Config
+    # Yields the global configuration to the given block.
+    #
+    # @example
+    #   Squid.configure do |config|
+    #     config.height = 150
+    #   end
+    #
+    # @yield [Squid::Configuration] The global configuration.
+    def configure
+      yield configuration if block_given?
+    end
+
+    # Returns the global {Squid::Configuration} object.
+    #
+    # While this method _can_ be used to read and write configuration settings,
+    # it is easier to use {Squid::Config#configure} Squid.configure}.
+    #
+    # @example
+    #     Squid.configuration.height = 150
+    #
+    # @return [Squid::Configuration] The global configuration.
+    def configuration
+      @configuration ||= Squid::Configuration.new
+    end
+  end
+
+  # @note Config is the only module auto-loaded in the Squid module,
+  #       in order to have a syntax as easy as Squid.configure
+  extend Config
+end

data/lib/squid/configuration.rb

@@ -0,0 +1,80 @@
+require 'ostruct'
+
+module Squid
+  # Provides an object to store global configuration settings.
+  #
+  # This class is typically not used directly, but by calling
+  # {Squid::Config#configure Squid.configure}, which creates and updates a
+  # single instance of {Squid::Configuration}.
+  #
+  # @example Set the default height for Squid graphs:
+  #   Squid.configure do |config|
+  #     config.height = 150
+  #     config.steps = 4
+  #   end
+  #
+  # @see Squid::Config for more examples.
+  #
+  # An alternative way to set global configuration settings is by storing
+  # them in the following environment variables:
+  #
+  # * +SQUID_HEIGHT+ to store the default graph height
+  #
+  # In case both methods are used together,
+  # {Squid::Config#configure Squid.configure} takes precedence.
+  #
+  # @example Set the default graph height:
+  #   ENV['SQUID_HEIGHT'] =  '150'
+  #   ENV['SQUID_GRIDLINES'] =  '4'
+  #
+  class Configuration < OpenStruct
+    COLORS = '2e578c 5d9648 e7a13d bc2d30 6f3d79 7d807f'
+
+    def self.boolean
+      -> (value) { %w(1 t T true TRUE).include? value }
+    end
+    
+    def self.integer
+      -> (value) { value.to_i }
+    end
+
+    def self.symbol
+      -> (value) { value.to_sym }
+    end
+
+    def self.float
+      -> (value) { value.to_f }
+    end
+    
+    def self.array
+      -> (value) { value.split }
+    end
+
+    ATTRIBUTES = {
+      baseline:     {default: 'true',      as: boolean},
+      border:       {default: 'false',     as: boolean},
+      chart:        {default: 'true',      as: boolean},
+      colors:       {default: COLORS,      as: array},
+      every:        {default: '1',         as: integer},
+      format:       {default: 'integer',   as: symbol},
+      height:       {default: '250',       as: float},
+      labels:       {default: 'false',     as: boolean},
+      legend:       {default: 'true',      as: boolean},
+      line_widths:  {default: '3',         as: integer},
+      steps:        {default: '4',         as: integer},
+      ticks:        {default: 'true',      as: boolean},
+      type:         {default: 'column',    as: symbol},
+    }
+
+    attr_accessor *ATTRIBUTES.keys
+
+    # Initialize the global configuration settings.
+    def initialize
+      ATTRIBUTES.each do |key, options|
+        var = "squid_#{key}".upcase
+        value = ENV.fetch var, options[:default]
+        public_send "#{key}=", options[:as].call(value)
+      end
+    end
+  end
+end

data/lib/squid/format.rb

@@ -0,0 +1,22 @@
+require 'active_support'
+require 'active_support/number_helper' # for number_to_rounded
+
+module Squid
+  module Format
+    include ActiveSupport::NumberHelper
+
+    def format_for(value, format)
+      case format
+        when :percentage then number_to_percentage value, precision: 1
+        when :currency then number_to_currency value
+        when :seconds then number_to_minutes_and_seconds value
+        when :float then number_to_delimited value
+        else number_to_delimited value.to_i
+      end.to_s
+    end
+
+    def number_to_minutes_and_seconds(value)
+      "#{value.round / 60}:#{(value.round % 60).to_s.rjust 2, '0'}"
+    end
+  end
+end

data/lib/squid/graph.rb

@@ -0,0 +1,113 @@
+require 'active_support'
+require 'active_support/core_ext/string/inflections' # for titleize
+
+require 'squid/axis'
+require 'squid/axis_label'
+require 'squid/gridline'
+require 'squid/plotter'
+require 'squid/point'
+require 'squid/settings'
+
+module Squid
+  # @private
+  class Graph
+    extend Settings
+    has_settings :baseline, :border, :chart, :colors, :every, :format, :height
+    has_settings :legend, :line_widths, :steps, :ticks, :type, :labels
+
+    def initialize(document, data = {}, settings = {})
+      @data, @settings = data, settings
+      @plot = Plotter.new document, bottom: bottom
+      @plot.paddings = {left: left.width, right: right.width} if @data.any?
+    end
+
+    def draw
+      @plot.box(h: height, border: border) { draw_graph if @data.any? }
+    end
+
+  private
+
+    def draw_graph
+      draw_legend if legend
+      draw_gridlines
+      draw_axis_labels
+      draw_charts if chart
+      draw_categories if baseline
+    end
+
+    def draw_legend
+      labels = @data.keys.reverse.map{|key| key.to_s.titleize}
+      offset = legend.is_a?(Hash) ? legend.fetch(:offset, 0) : 0
+      @plot.legend labels, offset: offset, colors: colors, height: legend_height
+    end
+
+    def draw_gridlines
+      options = {height: grid_height, count: steps, skip_baseline: baseline}
+      Gridline.for(options).each do |line|
+        @plot.horizontal_line line.y, line_width: 0.5, transparency: 0.25
+      end
+    end
+
+    def draw_axis_labels
+      @plot.axis_labels AxisLabel.for(left, align: :right, height: grid_height)
+      @plot.axis_labels AxisLabel.for(right, align: :left, height: grid_height)
+    end
+
+    def draw_categories
+      labels = @data.values.first.keys.map{|key| key.to_s}
+      @plot.categories labels, every: every, ticks: ticks
+      @plot.horizontal_line 0.0
+    end
+
+    def draw_charts
+      draw_chart right, type: :column, colors: colors[1..-1]
+      draw_chart left, colors: colors
+    end
+
+    def draw_chart(axis, options = {})
+      args = {minmax: axis.minmax, height: grid_height, stack: stack?, labels: labels, format: format}
+      points = Point.for axis.data, args
+      case options.delete(:type) {type}
+        when :point then @plot.points points, options
+        when :line, :two_axis then @plot.lines points, options.merge(line_widths: line_widths)
+        when :column then @plot.columns points, options
+        when :stack then @plot.stacks points, options
+      end
+    end
+
+    def left
+      @left ||= axis first: 0, last: (two_axis? ? 1 : @data.size)
+    end
+
+    def right
+      @right ||= axis first: 1, last: (two_axis? ? 1 : 0)
+    end
+
+    def axis(first:, last:)
+      series = @data.values[first, last].map(&:values)
+      Axis.new series, steps: steps, stack: stack?, format: format do |label|
+        @plot.width_of label
+      end
+    end
+
+    def bottom
+      baseline ? 20 : 0
+    end
+
+    def legend_height
+      15
+    end
+
+    def grid_height
+      height - bottom - legend_height * (legend ? 2 : 1)
+    end
+
+    def stack?
+      type == :stack
+    end
+
+    def two_axis?
+      type == :two_axis
+    end
+  end
+end

data/lib/squid/gridline.rb

@@ -0,0 +1,16 @@
+module Squid
+  class Gridline
+    def self.for(count:, skip_baseline:, height:)
+      return [] if count.zero?
+      height.step(0, -height/count.to_f).map do |y|
+        new y: y unless skip_baseline && y.zero?
+      end.compact
+    end
+
+    attr_reader :y
+
+    def initialize(y:)
+      @y = y
+    end
+  end
+end

data/lib/squid/plotter.rb

@@ -0,0 +1,187 @@
+require 'active_support'
+require 'active_support/core_ext/array/wrap' # for Array#wrap
+
+module Squid
+  # A Plotter wraps a Prawn::Document object in order to provide new methods
+  # like `gridline` or `ticks` used by Squid::Graph to plot graph elements.
+  class Plotter
+    attr_accessor :paddings
+    # @param [Prawn::Document] a PDF document to wrap in a Plotter instance.
+    def initialize(pdf, bottom:)
+      @pdf = pdf
+      @bottom = bottom
+    end
+
+    # Draws a bounding box of the given height, rendering the block inside it.
+    def box(x: 0, y: @pdf.cursor, w: @pdf.bounds.width, h:, border: false)
+      @pdf.bounding_box [x, y], width: w, height: h do
+        @pdf.stroke_bounds if border
+        yield
+      end
+    end
+
+    # Draws the graph legend with the given labels.
+    # @param [Array<LegendItem>] The labels to write as part of the legend.
+    def legend(labels, height:, offset: 0, colors: [])
+      left = @pdf.bounds.width/2
+      box(x: left, y: @pdf.bounds.top, w: left, h: height) do
+        x = @pdf.bounds.right - offset
+        options = {size: 7, height: @pdf.bounds.height, valign: :center}
+        labels.each.with_index do |label, i|
+          color = Array.wrap(colors[labels.size - 1 - i]).first
+          x = legend_item label, x, color, options
+        end
+      end
+    end
+
+    # Draws a horizontal line.
+    def horizontal_line(y, options = {})
+      with options do
+        at = y + @bottom
+        @pdf.stroke_horizontal_line left, @pdf.bounds.right - right, at: at
+      end
+    end
+
+    def width_of(label)
+      @pdf.width_of(label, size: 8).ceil
+    end
+
+    def axis_labels(labels)
+      labels.each do |label|
+        x = (label.align == :right) ? 0 : @pdf.bounds.right - label.width
+        y = label.y + @bottom + text_options[:height] / 2
+        options = text_options.merge width: label.width, at: [x, y]
+        @pdf.text_box label.label, options.merge(align: label.align)
+      end
+    end
+
+    def categories(labels, every:, ticks:)
+      labels.each.with_index do |label, index|
+        w = width / labels.count.to_f
+        x = left + w * (index)
+        padding = 2
+        options = category_options.merge(width: every*w-2*padding, at: [x+padding-w*(every/2.0-0.5), @bottom])
+        @pdf.text_box label, options if (index % every).zero?
+        @pdf.stroke_vertical_line @bottom, @bottom - 2, at: x + w/2 if ticks
+      end
+    end
+
+    def points(series, colors: [])
+      items(series, colors: colors) do |point, w, i, padding|
+        x, y = (point.index + 0.5)*w + left, point.y + @bottom
+        @pdf.fill_circle [x, y], 5
+      end
+    end
+
+    def lines(series, colors: [], line_widths: [])
+      x, y = nil, nil
+      items(series, colors: colors) do |point, w, i, padding|
+        prev_x, prev_y = x, y
+        x, y = (point.index + 0.5)*w + left, point.y + @bottom
+        line_width = Array.wrap(line_widths).fetch(i, 1)
+        with line_width: line_width, cap_style: :round do
+          @pdf.line [prev_x, prev_y], [x,y] unless point.index.zero? || prev_y.nil? || prev_x > x
+        end
+      end
+    end
+
+    def stacks(series, colors: [])
+      items(series, colors: colors, fill: true) do |point, w, i, padding|
+        x, y = point.index*w + padding + left, point.y + @bottom
+        @pdf.fill_rectangle [x, y], w - 2*padding, point.height
+      end
+    end
+
+    def columns(series, colors: [])
+      items(series, colors: colors, fill: true, count: series.size) do |point, w, i, padding|
+        item_w = (w - 2 * padding)/ series.size
+        x, y = point.index*w + padding + left + i*item_w, point.y + @bottom
+        @pdf.fill_rectangle [x, y], item_w, point.height
+      end
+    end
+
+  private
+
+    def left
+      @paddings[:left].zero? ? 0 : @paddings[:left] + 5
+    end
+
+    def right
+      @paddings[:right].zero? ? 0 : @paddings[:right] + 5
+    end
+
+    def width
+      @pdf.bounds.width - left - right
+    end
+
+    def category_options
+      text_options.merge align: :center, leading: -3, disable_wrap_by_char: true
+    end
+
+    def text_options
+      options = {}
+      options[:height] = 20
+      options[:size] = 8
+      options[:valign] = :center
+      options[:overflow] = :shrink_to_fit
+      options
+    end
+
+    def items(series, colors: [], fill: false, count: 1, &block)
+      series.reverse_each.with_index do |points, reverse_index|
+        index = series.size - reverse_index - 1
+        w = width / points.size.to_f
+        series_colors = Array.wrap(colors[index]).cycle
+        points.select(&:y).each do |point|
+          item point, series_colors.next, w, fill, index, count, &block
+        end
+      end
+    end
+
+    def item(point, color, w, fill, index, count)
+      padding = w / 8
+
+      with transparency: 0.95, fill_color: color, stroke_color: color do
+        yield point, w, index, padding
+      end
+
+      with fill_color: (point.negative && fill ? 'ffffff' : color) do
+        options = [{size: 10, styles: [:bold], text: point.label}]
+        position = {align: :center, valign: :bottom, height: 20}
+        position[:width] = (w - 2*padding) / count
+        x = left + point.index*w + padding
+        x += index * position[:width] if count > 1
+        position[:at] = [x, point.y + @bottom + 24]
+        @pdf.formatted_text_box options, position
+      end if point.label
+    end
+
+    # Draws a single item of the legend, which includes the label and the
+    # symbol with the matching color. Labels are written from right to left.
+    # @param
+    def legend_item(label, x, color, options)
+      size, symbol_padding, entry_padding = 5, 3, 12
+      x -= @pdf.width_of(label, size: 7).ceil
+      @pdf.text_box label, options.merge(at: [x, @pdf.bounds.height])
+      x -= (symbol_padding + size)
+      with fill_color: color do
+        @pdf.fill_rectangle [x, @pdf.bounds.height - size], size, size
+      end
+      x - entry_padding
+    end
+
+
+
+    # Convenience method to wrap a block by setting and unsetting a Prawn
+    # property such as line_width.
+    def with(new_values = {})
+      transparency = new_values.delete(:transparency) { 1.0 }
+      old_values = Hash[new_values.map{|k,_| [k,@pdf.public_send(k)]}]
+      new_values.each{|k, new_value| @pdf.public_send "#{k}=", new_value }
+      @pdf.transparent(transparency) do
+        @pdf.stroke { yield }
+      end
+      old_values.each{|k, old_value| @pdf.public_send "#{k}=", old_value }
+    end
+  end
+end