]> projects.mako.cc - selectricity-live/blob - vendor/plugins/sparklines/lib/sparklines.rb
fixed up the results page in a number of ways
[selectricity-live] / vendor / plugins / sparklines / lib / sparklines.rb
1
2 require 'rubygems'
3 require 'RMagick'
4
5 =begin rdoc
6
7 A library for generating small unmarked graphs (sparklines).
8
9 Can be used to write an image to a file or make a web service with Rails or other Ruby CGI apps.
10
11 Idea and much of the outline for the source lifted directly from {Joe Gregorio's Python Sparklines web service script}[http://bitworking.org/projects/sparklines].
12
13 Requires the RMagick image library.
14
15 ==Authors
16
17 {Dan Nugent}[mailto:nugend@gmail.com] Original port from Python Sparklines library.
18
19 {Geoffrey Grosenbach}[mailto:boss@topfunky.com] -- http://nubyonrails.topfunky.com 
20 -- Conversion to module and further maintenance.
21
22 ==General Usage and Defaults
23
24 To use in a script:
25
26         require 'rubygems'
27         require 'sparklines'
28         Sparklines.plot([1,25,33,46,89,90,85,77,42], 
29                         :type => 'discrete', 
30                         :height => 20)
31
32 An image blob will be returned which you can print, write to STDOUT, etc.
33
34 For use with Ruby on Rails, see the sparklines plugin:
35
36   http://nubyonrails.com/pages/sparklines
37
38 In your view, call it like this:
39
40   <%= sparkline_tag [1,2,3,4,5,6] %>
41
42 Or specify details:
43
44   <%= sparkline_tag [1,2,3,4,5,6], 
45                     :type => 'discrete', 
46                     :height => 10, 
47                     :upper => 80, 
48                     :above_color => 'green', 
49                     :below_color => 'blue' %>
50
51 Graph types:
52
53  area
54  discrete
55  pie
56  smooth
57  bar
58  whisker
59
60 General Defaults:
61
62  :type              => 'smooth'
63  :height            => 14px
64  :upper             => 50
65  :above_color       => 'red'
66  :below_color       => 'grey'
67  :background_color  => 'white'
68  :line_color        => 'lightgrey'
69
70 ==License
71
72 Licensed under the MIT license.
73
74 =end
75 class Sparklines
76
77   VERSION = '0.4.1'
78
79   @@label_margin = 5.0
80   @@pointsize = 10.0
81
82   class << self
83
84     # Does the actual plotting of the graph. 
85     # Calls the appropriate subclass based on the :type argument. 
86     # Defaults to 'smooth'
87     def plot(data=[], options={})
88       defaults = {
89         :type => 'smooth',
90         :height => 14,
91         :upper => 50,
92         :diameter => 20,
93         :step => 2,
94         :line_color => 'lightgrey',
95
96         :above_color => 'red',
97         :below_color => 'grey',
98         :background_color => 'white',
99         :share_color => 'red',
100         :remain_color => 'lightgrey',
101         :min_color => 'blue',
102         :max_color => 'green',  
103         :last_color => 'red',                
104
105         :has_min => false,
106         :has_max => false,
107         :has_last => false,
108
109         :label => nil
110       }
111
112       # HACK for HashWithIndifferentAccess
113       options_sym = Hash.new
114       options.keys.each do |key|
115         options_sym[key.to_sym] = options[key]
116       end
117
118       options_sym  = defaults.merge(options_sym)
119         
120       # Call the appropriate method for actual plotting.
121       sparkline = self.new(data, options_sym)
122       if %w(area bar pie smooth discrete whisker).include? options_sym[:type]
123         sparkline.send options_sym[:type]
124       else
125         sparkline.plot_error options_sym
126       end
127     end
128
129     # Writes a graph to disk with the specified filename, or "sparklines.png"
130     def plot_to_file(filename="sparklines.png", data=[], options={})
131       File.open( filename, 'wb' ) do |png|
132         png << self.plot( data, options)
133       end
134     end
135
136   end # class methods
137
138   def initialize(data=[], options={})
139     @data = Array(data)
140     @options = options
141     normalize_data
142   end
143
144   ##
145   # Creates a continuous area sparkline. Relevant options.
146   #
147   # :step - An integer that determines the distance between each point on the sparkline.  Defaults to 2.
148   #
149   # :height - An integer that determines what the height of the sparkline will be.  Defaults to 14
150   #
151   # :upper - An integer that determines the threshold for colorization purposes.  Any value less than upper will be colored using below_color, anything above and equal to upper will use above_color.  Defaults to 50.
152   #
153   # :has_min - Determines whether a dot will be drawn at the lowest value or not.  Defaults to false.
154   #
155   # :has_max - Determines whether a dot will be drawn at the highest value or not.  Defaults to false.
156   #
157   # :has_last - Determines whether a dot will be drawn at the last value or not.  Defaults to false.
158   #
159   # :min_color - A string or color code representing the color that the dot drawn at the smallest value will be displayed as.  Defaults to blue.
160   #
161   # :max_color - A string or color code representing the color that the dot drawn at the largest value will be displayed as.  Defaults to green.
162   #
163   # :last_color - A string or color code representing the color that the dot drawn at the last value will be displayed as.  Defaults to red.
164   #
165   # :above_color - A string or color code representing the color to draw values above or equal the upper value.  Defaults to red.
166   #
167   # :below_color - A string or color code representing the color to draw values below the upper value. Defaults to gray.
168
169   def area
170
171     step = @options[:step].to_i
172     height = @options[:height].to_i
173     background_color = @options[:background_color]
174     
175     create_canvas((@norm_data.size - 1) * step + 4, height, background_color)
176
177     upper = @options[:upper].to_i
178
179     has_min = @options[:has_min]
180     has_max = @options[:has_max]
181     has_last = @options[:has_last]
182
183     min_color = @options[:min_color]
184     max_color = @options[:max_color]
185     last_color = @options[:last_color]
186     below_color = @options[:below_color]
187     above_color = @options[:above_color]
188
189
190     coords = [[0,(height - 3 - upper/(101.0/(height-4)))]]
191     i=0
192     @norm_data.each do |r|
193         coords.push [(2 + i), (height - 3 - r/(101.0/(height-4)))]
194         i += step
195     end
196     coords.push [(@norm_data.size - 1) * step + 4, (height - 3 - upper/(101.0/(height-4)))]
197
198     # TODO Refactor! Should take a block and do both.
199     #
200     # Block off the bottom half of the image and draw the sparkline
201     @draw.fill(above_color)
202     @draw.define_clip_path('top') do
203       @draw.rectangle(0,0,(@norm_data.size - 1) * step + 4,(height - 3 - upper/(101.0/(height-4))))
204     end
205     @draw.clip_path('top')
206     @draw.polygon *coords.flatten
207
208     # Block off the top half of the image and draw the sparkline
209     @draw.fill(below_color)
210     @draw.define_clip_path('bottom') do
211       @draw.rectangle(0,(height - 3 - upper/(101.0/(height-4))),(@norm_data.size - 1) * step + 4,height)
212     end
213     @draw.clip_path('bottom')
214     @draw.polygon *coords.flatten
215
216     # The sparkline looks kinda nasty if either the above_color or below_color gets the center line
217     @draw.fill('black')
218     @draw.line(0,(height - 3 - upper/(101.0/(height-4))),(@norm_data.size - 1) * step + 4,(height - 3 - upper/(101.0/(height-4))))
219
220     # After the parts have been masked, we need to let the whole canvas be drawable again
221     # so a max dot can be displayed
222     @draw.define_clip_path('all') do
223       @draw.rectangle(0,0,@canvas.columns,@canvas.rows)
224     end
225     @draw.clip_path('all')
226         
227     drawbox(coords[@norm_data.index(@norm_data.min)+1], 1, min_color) if has_min == true
228     drawbox(coords[@norm_data.index(@norm_data.max)+1], 1, max_color) if has_max == true
229     
230     drawbox(coords[-2], 1, last_color) if has_last == true
231
232     @draw.draw(@canvas)
233     @canvas.to_blob
234   end
235
236   ##
237   # A bar graph.
238
239   def bar
240     step = @options[:step].to_i
241     height = @options[:height].to_f
242     background_color = @options[:background_color]
243
244     create_canvas(@norm_data.length * step + 2, height, background_color)
245     
246     upper = @options[:upper].to_i
247     below_color = @options[:below_color]
248     above_color = @options[:above_color]
249
250     i = 1
251     @norm_data.each_with_index do |r, index|
252       color = (r >= upper) ? above_color : below_color
253       @draw.stroke('transparent')
254       @draw.fill(color)
255       @draw.rectangle( i, @canvas.rows, 
256             i + step - 2, @canvas.rows - ( (r / @maximum_value) * @canvas.rows) )
257       i += step
258     end
259
260     @draw.draw(@canvas)
261     @canvas.to_blob
262   end
263
264
265   ##
266   # Creates a discretized sparkline
267   #
268   # :height - An integer that determines what the height of the sparkline will be.  Defaults to 14
269   #
270   # :upper - An integer that determines the threshold for colorization purposes.  Any value less than upper will be colored using below_color, anything above and equal to upper will use above_color.  Defaults to 50.
271   #
272   # :above_color - A string or color code representing the color to draw values above or equal the upper value.  Defaults to red.
273   #
274   # :below_color - A string or color code representing the color to draw values below the upper value. Defaults to gray.
275
276   def discrete
277
278     height = @options[:height].to_i
279     upper = @options[:upper].to_i
280     background_color = @options[:background_color]
281     step = @options[:step].to_i
282         
283     create_canvas(@norm_data.size * step - 1, height, background_color)
284     
285     below_color = @options[:below_color]
286     above_color = @options[:above_color]
287
288     i = 0
289     @norm_data.each do |r|
290         color = (r >= upper) ? above_color : below_color
291         @draw.stroke(color)
292         @draw.line(i, (@canvas.rows - r/(101.0/(height-4))-4).to_i,
293                   i, (@canvas.rows - r/(101.0/(height-4))).to_i)
294         i += step
295     end
296
297     @draw.draw(@canvas)
298     @canvas.to_blob
299   end
300
301
302   ##
303   # Creates a pie-chart sparkline
304   #
305   # :diameter - An integer that determines what the size of the sparkline will be.  Defaults to 20
306   #
307   # :share_color - A string or color code representing the color to draw the share of the pie represented by percent.  Defaults to red.
308   #
309   # :remain_color - A string or color code representing the color to draw the pie not taken by the share color. Defaults to lightgrey.
310
311   def pie
312     diameter = @options[:diameter].to_i
313     background_color = @options[:background_color]
314
315     create_canvas(diameter, diameter, background_color)
316     
317     share_color = @options[:share_color]
318     remain_color = @options[:remain_color]
319     percent = @norm_data[0]
320     
321     # Adjust the radius so there's some edge left in the pie
322     r = diameter/2.0 - 2
323     @draw.fill(remain_color)
324     @draw.ellipse(r + 2, r + 2, r , r , 0, 360)
325     @draw.fill(share_color)
326
327     # Special exceptions
328     if percent == 0
329         # For 0% return blank
330         @draw.draw(@canvas)
331         return @canvas.to_blob
332     elsif percent == 100
333         # For 100% just draw a full circle
334         @draw.ellipse(r + 2, r + 2, r , r , 0, 360)
335         @draw.draw(@canvas)
336         return @canvas.to_blob
337     end
338
339     # Okay, this part is as confusing as hell, so pay attention:
340     # This line determines the horizontal portion of the point on the circle where the X-Axis
341     # should end.  It's caculated by taking the center of the on-image circle and adding that
342     # to the radius multiplied by the formula for determinig the point on a unit circle that a
343     # angle corresponds to.  3.6 * percent gives us that angle, but it's in degrees, so we need to
344     # convert, hence the muliplication by Pi over 180
345     arc_end_x = r + 2 + (r * Math.cos((3.6 * percent)*(Math::PI/180)))
346
347     # The same goes for here, except it's the vertical point instead of the horizontal one
348     arc_end_y = r + 2 + (r * Math.sin((3.6 * percent)*(Math::PI/180)))
349
350     # Because the SVG path format is seriously screwy, we need to set the large-arc-flag to 1
351     # if the angle of an arc is greater than 180 degrees.  I have no idea why this is, but it is.
352     percent > 50? large_arc_flag = 1: large_arc_flag = 0
353
354     # This is also confusing
355     # M tells us to move to an absolute point on the image.  We're moving to the center of the pie
356     # h tells us to move to a relative point.  We're moving to the right edge of the circle.
357     # A tells us to start an absolute elliptical arc.  The first two values are the radii of the ellipse
358     # the third value is the x-axis-rotation (how to rotate the ellipse if we wanted to [could have some fun
359     # with randomizing that maybe), the fourth value is our large-arc-flag, the fifth is the sweep-flag,
360     # (again, confusing), the sixth and seventh values are the end point of the arc which we calculated previously
361     # More info on the SVG path string format at: http://www.w3.org/TR/SVG/paths.html
362     path = "M#{r + 2},#{r + 2} h#{r} A#{r},#{r} 0 #{large_arc_flag},1 #{arc_end_x},#{arc_end_y} z"
363     @draw.path(path)
364
365     @draw.draw(@canvas)
366     @canvas.to_blob
367   end
368
369
370   ##
371   # Creates a smooth sparkline.
372   #
373   # :step - An integer that determines the distance between each point on the sparkline.  Defaults to 2.
374   #
375   # :height - An integer that determines what the height of the sparkline will be.  Defaults to 14
376   #
377   # :has_min - Determines whether a dot will be drawn at the lowest value or not.  Defaults to false.
378   #
379   # :has_max - Determines whether a dot will be drawn at the highest value or not.  Defaults to false.
380   #
381   # :has_last - Determines whether a dot will be drawn at the last value or not.  Defaults to false.
382   #
383   # :min_color - A string or color code representing the color that the dot drawn at the smallest value will be displayed as.  Defaults to blue.
384   #
385   # :max_color - A string or color code representing the color that the dot drawn at the largest value will be displayed as.  Defaults to green.
386   #
387   # :last_color - A string or color code representing the color that the dot drawn at the last value will be displayed as.  Defaults to red.
388
389   def smooth
390
391     step = @options[:step].to_i
392     height = @options[:height].to_i
393     background_color = @options[:background_color]
394
395     create_canvas((@norm_data.size - 1) * step + 4, height, background_color)
396     
397     min_color = @options[:min_color]
398     max_color = @options[:max_color]
399     last_color = @options[:last_color]
400     has_min = @options[:has_min]
401     has_max = @options[:has_max]
402     has_last = @options[:has_last]
403     line_color = @options[:line_color]
404
405     @draw.stroke(line_color)
406     coords = []
407     i=0
408     @norm_data.each do |r|
409       coords.push [ 2 + i, (height - 3 - r/(101.0/(height-4))) ]
410       i += step
411     end
412     
413     open_ended_polyline(coords)
414
415     drawbox(coords[@norm_data.index(@norm_data.min)], 2, min_color) if has_min == true
416
417     drawbox(coords[@norm_data.index(@norm_data.max)], 2, max_color) if has_max == true
418
419     drawbox(coords[-1], 2, last_color) if has_last == true
420
421     @draw.draw(@canvas)
422     @canvas.to_blob
423   end
424
425
426   ##
427   # Creates a whisker sparkline to track on/off type data. There are five states: 
428   # on, off, no value, exceptional on, exceptional off. On values create an up 
429   # whisker and off values create a down whisker. Exceptional values may be 
430   # colored differently than regular values to indicate, for example, a shut out.
431   # No value produces an empty row to indicate a tie.
432   # 
433   # * results - an array of integer values between -2 and 2. -2 is exceptional 
434   #   down, 1 is regular down, 0 is no value, 1 is up, and 2 is exceptional up.
435   # * options - a hash that takes parameters
436   #
437   # :height - height of the sparkline
438   #
439   # :whisker_color - the color of regular whiskers; defaults to black
440   #
441   # :exception_color - the color of exceptional whiskers; defaults to red
442   
443   def whisker
444
445     # step = @options[:step].to_i
446     height = @options[:height].to_i
447     background_color = @options[:background_color]
448
449     create_canvas((@data.size - 1) * 2, height, background_color)
450     
451     whisker_color = @options[:whisker_color] || 'black'
452     exception_color = @options[:exception_color] || 'red'
453
454     i = 0
455     @data.each do |r|
456       color = whisker_color
457
458       if ( (r == 2 || r == -2) && exception_color )
459         color = exception_color
460       end
461
462       y_mid_point = (r >= 1) ? (@canvas.rows/2.0 - 1).ceil : (@canvas.rows/2.0).floor
463
464       y_end_point = y_mid_point
465       if ( r > 0) 
466         y_end_point = 0
467       end
468
469       if ( r < 0 )
470         y_end_point = @canvas.rows
471       end
472
473       @draw.stroke( color )
474       @draw.line( i, y_mid_point, i, y_end_point )
475       i += 2
476     end
477
478     @draw.draw(@canvas)
479     @canvas.to_blob 
480   end
481
482   ##
483   # Draw the error Sparkline.
484
485   def plot_error(options={})
486     create_canvas(40, 15, 'white')
487
488     @draw.fill('red')
489     @draw.line(0,0,40,15)
490     @draw.line(0,15,40,0)
491
492     @draw.draw(@canvas)
493     @canvas.to_blob
494   end
495
496 private
497
498   def normalize_data
499     @maximum_value = @data.max
500     if @options[:type].to_s == 'pie'
501       @norm_data = @data
502     else
503       @norm_data = @data.map { |value| value = (value.to_f / @maximum_value) * 100.0 }
504     end
505   end
506
507   ##
508   # * :arr - an array of points (represented as two element arrays)
509   
510   def open_ended_polyline(arr)
511     0.upto(arr.length - 2) { |i|
512       @draw.line(arr[i][0], arr[i][1], arr[i+1][0], arr[i+1][1])
513     }
514   end
515
516   ##
517   # Create an image to draw on and a drawable to do the drawing with.
518   #
519   # TODO Refactor into smaller methods
520
521   def create_canvas(w, h, bkg_col)
522     @draw = Magick::Draw.new
523     @draw.pointsize = @@pointsize # TODO Use height
524     @canvas = Magick::Image.new(w , h) { self.background_color = bkg_col }
525
526     # Make room for label and last value
527     unless @options[:label].nil?
528       @options[:has_last] = true
529       @label_width = calculate_width(@options[:label])
530       @data_last_width = calculate_width(@data.last)
531       # HACK The 7.0 is a severe hack. Must figure out correct spacing
532       @label_and_data_last_width = @label_width + @data_last_width + @@label_margin * 7.0
533       w += @label_and_data_last_width
534     end
535
536     @canvas = Magick::Image.new(w , h) { self.background_color = bkg_col }
537     @canvas.format = "PNG"
538
539     # Draw label and last value
540     unless @options[:label].nil?
541       if ENV.has_key?('MAGICK_FONT_PATH')
542         vera_font_path = File.expand_path('Vera.ttf', ENV['MAGICK_FONT_PATH'])
543         @font = File.exists?(vera_font_path) ? vera_font_path : nil
544       else
545         @font = nil
546       end
547
548       @draw.fill = 'black'
549       @draw.font = @font if @font
550       @draw.gravity = Magick::WestGravity
551       @draw.annotate( @canvas, 
552                       @label_width, 1.0,
553                       w - @label_and_data_last_width + @@label_margin, h - calculate_caps_height/2.0,
554                       @options[:label])
555
556       @draw.fill = 'red'
557       @draw.annotate( @canvas, 
558                       @data_last_width, 1.0,
559                       w - @data_last_width - @@label_margin * 2.0, h - calculate_caps_height/2.0,
560                       @data.last.to_s)
561     end
562   end
563
564   ##
565   # Utility to draw a coloured box
566   # Centred on pt, offset off in each direction, fill color is col
567
568   def drawbox(pt, offset, color)
569     @draw.stroke 'transparent'
570     @draw.fill(color)
571     @draw.rectangle(pt[0]-offset, pt[1]-offset, pt[0]+offset, pt[1]+offset)
572   end
573
574   def calculate_width(text)
575     @draw.get_type_metrics(@canvas, text.to_s).width
576   end
577
578   def calculate_caps_height
579     @draw.get_type_metrics(@canvas, 'X').height
580   end
581
582 end

Benjamin Mako Hill || Want to submit a patch?