sparklines 0.4.8 → 0.5.0

data/CHANGELOG

@@ -1,3 +1,11 @@
+== 0.5.0
+
+* Documentation for bullet graph.
+* More bullet options for good_color, satisfactory_color, and bad_color.
+* Smooth options for target line value and target_color.
+* Sparklinks.plot_to_image returns a Magick::Image object for further manipulation.
+* Step option for wider whisker.
+
 == 0.4.8
 
 * Added bullet graph. See http://en.wikipedia.org/wiki/Bullet_graph or Stephen Few's book _Information Dashboard Design_.

data/Manifest.txt

@@ -1,7 +1,7 @@
 CHANGELOG
 MIT-LICENSE
 Manifest.txt
-README
+README.txt
 Rakefile
 lib/sparklines.rb
 lib/sparklines_helper.rb
@@ -27,6 +27,7 @@ test/expected/bar_string.png.png
 test/expected/bar_tall.png
 test/expected/bar_wide.png
 test/expected/bullet_basic.png
+test/expected/bullet_colorful.png
 test/expected/bullet_full_featured.png
 test/expected/bullet_tall.png
 test/expected/bullet_wide.png
@@ -52,10 +53,12 @@ test/expected/smooth.png
 test/expected/smooth_colored.png
 test/expected/smooth_similar_nonzero_values.png
 test/expected/smooth_underneath_color.png
+test/expected/smooth_with_target.png
 test/expected/standard_deviation.png
 test/expected/standard_deviation_short.png
 test/expected/standard_deviation_tall.png
 test/expected/whisker.png
 test/expected/whisker_junk.png
 test/expected/whisker_non_exceptional.png
+test/expected/whisker_with_step.png
 test/test_all.rb

data/{README → README.txt}

@@ -18,5 +18,3 @@ http://nubyonrails.com/pages/sparklines
 
 Daniel Nugent
 nugend@gmail.com
-
-

data/lib/sparklines.rb

@@ -55,6 +55,7 @@ Graph types:
  pie
  smooth
  bar
+ bullet
  whisker
 
 General Defaults:
@@ -74,17 +75,17 @@ Licensed under the MIT license.
 =end
 class Sparklines
 
-  VERSION = '0.4.8'
+  VERSION = '0.5.0'
 
   @@label_margin = 5.0
   @@pointsize = 10.0
 
   class << self
 
-    # Does the actual plotting of the graph.
-    # Calls the appropriate subclass based on the :type argument.
-    # Defaults to 'smooth'
-    def plot(data=[], options={})
+    ##
+    # Plots a sparkline and returns a Magic::Image object.
+
+    def plot_to_image(data=[], options={})
       defaults = {
         :type => 'smooth',
         :height => 14,
@@ -128,7 +129,20 @@ class Sparklines
       end
     end
 
-    # Writes a graph to disk with the specified filename, or "sparklines.png"
+    ##
+    # Does the actual plotting of the graph.
+    # Calls the appropriate subclass based on the :type argument.
+    # Defaults to 'smooth'.
+    #
+    # Returns a blob.
+
+    def plot(data=[], options={})
+      plot_to_image(data, options).to_blob
+    end
+    
+    ##
+    # Writes a graph to disk with the specified filename, or "sparklines.png".
+    
     def plot_to_file(filename="sparklines.png", data=[], options={})
       File.open( filename, 'wb' ) do |png|
         png << self.plot( data, options)
@@ -232,7 +246,7 @@ class Sparklines
     drawbox(coords[-2], 1, last_color) if has_last == true
 
     @draw.draw(@canvas)
-    @canvas.to_blob
+    @canvas
   end
 
   ##
@@ -260,7 +274,7 @@ class Sparklines
     end
 
     @draw.draw(@canvas)
-    @canvas.to_blob
+    @canvas
   end
 
 
@@ -302,7 +316,7 @@ class Sparklines
     end
 
     @draw.draw(@canvas)
-    @canvas.to_blob
+    @canvas
   end
 
 
@@ -335,12 +349,12 @@ class Sparklines
     if percent == 0
       # For 0% return blank
       @draw.draw(@canvas)
-      return @canvas.to_blob
+      return @canvas
     elsif percent == 100
       # For 100% just draw a full circle
       @draw.ellipse(r + 2, r + 2, r , r , 0, 360)
       @draw.draw(@canvas)
-      return @canvas.to_blob
+      return @canvas
     end
 
     # Okay, this part is as confusing as hell, so pay attention:
@@ -370,11 +384,11 @@ class Sparklines
     @draw.path(path)
 
     @draw.draw(@canvas)
-    @canvas.to_blob
+    @canvas
   end
 
   ##
-  # Creates a smooth sparkline.
+  # Creates a smooth line graph sparkline.
   #
   #   :step - An integer that determines the distance between each point on the sparkline.  Defaults to 2.
   #
@@ -397,6 +411,11 @@ class Sparklines
   #   :std_dev_color - A string or color code representing the color that the standard deviation bar behind the smooth graph will be displayed as. Defaults to #efefef
   #
   #   :underneath_color - A string or color code representing the color that will be used to fill in the area underneath the line. Optional.
+  #
+  #   :target - A 1px horizontal line will be drawn at this value. Useful for showing an average.
+  #
+  #   :target_color - Color of the target line. Defaults to white.
+  
   def smooth
 
     step = @options[:step].to_f
@@ -416,6 +435,9 @@ class Sparklines
     has_std_dev = @options[:has_std_dev]
     std_dev_color = @options[:std_dev_color]
 
+    target = @options.has_key?(:target) ? @options[:target].to_f : nil
+    target_color = @options[:target_color] || 'white'
+
     drawstddevbox(width,height,std_dev_color) if has_std_dev == true
 
     @draw.stroke(line_color)
@@ -432,12 +454,19 @@ class Sparklines
       open_ended_polyline(coords)
     end
 
+    unless target.nil?
+      normalized_target_value = ((target.to_f - @minimum_value)/(@maximum_value - @minimum_value)) * 100.0
+      adjusted_target_value = (height - 3 - normalized_target_value/(101.0/(height-4))).to_i
+      @draw.stroke(target_color)
+      open_ended_polyline([[-5, adjusted_target_value], [width + 5, adjusted_target_value]])
+    end
+
     drawbox(coords[@norm_data.index(@norm_data.min)], 2, min_color) if has_min == true
     drawbox(coords[@norm_data.index(@norm_data.max)], 2, max_color) if has_max == true
     drawbox(coords[-1], 2, last_color) if has_last == true
 
     @draw.draw(@canvas)
-    @canvas.to_blob
+    @canvas
   end
 
   ##
@@ -459,11 +488,11 @@ class Sparklines
 
   def whisker
 
-    # step = @options[:step].to_f
+    step = @options[:step].to_i
     height = @options[:height].to_f
     background_color = @options[:background_color]
 
-    create_canvas(@data.size * 2 - 1, height, background_color)
+    create_canvas(@data.size * step - 1, height, background_color)
 
     whisker_color = @options[:whisker_color] || 'black'
     exception_color = @options[:exception_color] || 'red'
@@ -491,27 +520,55 @@ class Sparklines
 
       @draw.stroke( color )
       @draw.line( i, y_mid_point, i, y_end_point )
-      i += 2
+      i += step
     end
 
     @draw.draw(@canvas)
-    @canvas.to_blob
+    @canvas
   end
 
+  ##
+  # A bullet graph, a la Stephen Few in "Information Dashboard Design."
+  #
+  # * data - A single value for the thermometer part of the bullet.
+  #   Represents the current value.
+  # * options - a hash
+  #
+  #   :good - Numeric. Maximum value that will be shown on the graph. Required.
+  #
+  #   :height - Numeric. Defaults to 15. Should be a multiple of three.
+  #
+  #   :width - This graph expands to any specified width. Defaults to 100.
+  #   
+  #   :bad - Numeric. A darker shade background will be drawn up to this point.
+  #
+  #   :satisfactory - Numeric. A medium background will be drawn up to this point.
+  #
+  #   :target - Numeric value. A thin vertical bar will be drawn.
+  #
+  #   :good_color - Color for the rightmost section of the bullet.
+  #
+  #   :satisfactory_color - Color for the middle background of the bullet.
+  #
+  #   :bad_color - Color for the lowest, leftmost section.
+
   def bullet
     height = @options[:height].to_f
-    @graph_width  = @options.has_key?(:width) ? @options[:width].to_f : 100.0
-    background_color = '#eeeeee' # @options[:background_color]
+    @graph_width       = @options.has_key?(:width) ? @options[:width].to_f : 100.0
+    good_color         = @options.has_key?(:good_color) ? @options[:good_color] : '#eeeeee'
+    satisfactory_color = @options.has_key?(:satisfactory_color) ? @options[:satisfactory_color] : '#bbbbbb'
+    bad_color          = @options.has_key?(:bad_color) ? @options[:bad_color] : '#999999'
+    bullet_color       = @options.has_key?(:bullet_color) ? @options[:bullet_color] : 'black'
     @thickness = height/3.0
 
-    create_canvas(@graph_width, height, background_color)
+    create_canvas(@graph_width, height, good_color)
 
     @value = @norm_data
     @good_value = @options[:good].to_f
-    
+
     @graph_height = @options[:height]
 
-    qualitative_range_colors = ['#bbbbbb', '#999999']
+    qualitative_range_colors = [satisfactory_color, bad_color]
     [:satisfactory, :bad].each_with_index do |indicator, index|
       next unless @options.has_key?(indicator)
       @draw = @draw.fill(qualitative_range_colors[index])
@@ -520,7 +577,7 @@ class Sparklines
     end
 
     if @options.has_key?(:target)
-      @draw = @draw.fill 'black'
+      @draw = @draw.fill(bullet_color)
       target_x = @graph_width * (@options[:target].to_f / @good_value)
       half_thickness = (@thickness / 2.0).to_i
       bar_width = 1.0
@@ -528,11 +585,11 @@ class Sparklines
     end
 
     # Value
-    @draw = @draw.fill 'black'
+    @draw = @draw.fill(bullet_color)
     @draw = @draw.rectangle(0, @thickness.to_i, @graph_width * (@data.first.to_f / @good_value), (@thickness * 2.0).to_i)
 
     @draw.draw(@canvas)
-    @canvas.to_blob
+    @canvas
   end
 
   ##
@@ -546,7 +603,7 @@ class Sparklines
     @draw.line(0,15,40,0)
 
     @draw.draw(@canvas)
-    @canvas.to_blob
+    @canvas
   end
 
   private

data/test/test_all.rb

@@ -38,6 +38,20 @@ class SparklinesTest < Test::Unit::TestCase
     })
   end
 
+  test "colorful bullet" do
+    Sparklines.plot_to_file("#{@output_dir}/bullet_colorful.png", 85, {
+      :type => "bullet",
+      :target => 90,
+      :bad => 60,
+      :satisfactory => 80,
+      :good => 100,
+      :height => 15,
+      :bad_color => '#c3e3bf',
+      :satisfactory_color => '#96cf90',
+      :good_color => "#6ab162"
+    })
+  end
+
   test "tall bullet" do
     Sparklines.plot_to_file("#{@output_dir}/bullet_tall.png", 85, {
       :type => "bullet",
@@ -61,6 +75,23 @@ class SparklinesTest < Test::Unit::TestCase
     })
   end
 
+  test "smooth with target" do
+    quick_graph("smooth_with_target", {
+      :type => "smooth",
+      :target => 50,
+      :target_color => '#999999',
+      :line_color => "#6699cc",
+      :underneath_color => "#ebf3f6"
+    })
+  end
+
+  test "whisker with step" do
+    quick_graph("whisker_with_step", {
+      :type => "whisker",
+      :step => 5
+    })
+  end
+
   def test_each_graph
     %w{pie area discrete smooth bar}.each do |type|
       quick_graph("#{type}", :type => type)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: sparklines
 version: !ruby/object:Gem::Version 
-  version: 0.4.8
+  version: 0.5.0
 platform: ""
 authors: 
 - Geoffrey Grosenbach
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2008-01-18 00:00:00 -08:00
+date: 2008-01-20 00:00:00 -08:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -29,11 +29,12 @@ extensions: []
 
 extra_rdoc_files: 
 - Manifest.txt
+- README.txt
 files: 
 - CHANGELOG
 - MIT-LICENSE
 - Manifest.txt
-- README
+- README.txt
 - Rakefile
 - lib/sparklines.rb
 - lib/sparklines_helper.rb
@@ -59,6 +60,7 @@ files:
 - test/expected/bar_tall.png
 - test/expected/bar_wide.png
 - test/expected/bullet_basic.png
+- test/expected/bullet_colorful.png
 - test/expected/bullet_full_featured.png
 - test/expected/bullet_tall.png
 - test/expected/bullet_wide.png
@@ -84,12 +86,14 @@ files:
 - test/expected/smooth_colored.png
 - test/expected/smooth_similar_nonzero_values.png
 - test/expected/smooth_underneath_color.png
+- test/expected/smooth_with_target.png
 - test/expected/standard_deviation.png
 - test/expected/standard_deviation_short.png
 - test/expected/standard_deviation_tall.png
 - test/expected/whisker.png
 - test/expected/whisker_junk.png
 - test/expected/whisker_non_exceptional.png
+- test/expected/whisker_with_step.png
 - test/test_all.rb
 has_rdoc: true
 homepage: http://nubyonrails.com/pages/sparklines