Class Sparklines
In: lib/sparklines.rb
Parent: Object

A library for generating small unmarked graphs (sparklines).

Can be used to write an image to a file or make a web service with Rails or other Ruby CGI apps.

Idea and much of the outline for the source lifted directly from Joe Gregorio's Python Sparklines web service script.

Requires the RMagick image library.

Authors

Dan Nugent Original port from Python Sparklines library.

Geoffrey Grosenbachnubyonrails.topfunky.com — Conversion to module and further maintenance.

General Usage and Defaults

To use in a script:

        require 'rubygems'
        require 'sparklines'
        Sparklines.plot([1,25,33,46,89,90,85,77,42],
                        :type => 'discrete',
                        :height => 20)

An image blob will be returned which you can print, write to STDOUT, etc.

For use with Ruby on Rails, see the sparklines plugin:

  http://nubyonrails.com/pages/sparklines

In your view, call it like this:

  <%= sparkline_tag [1,2,3,4,5,6] %>

Or specify details:

  <%= sparkline_tag [1,2,3,4,5,6],
                    :type => 'discrete',
                    :height => 10,
                    :upper => 80,
                    :above_color => 'green',
                    :below_color => 'blue' %>

Graph types:

 area
 discrete
 pie
 smooth
 bar
 bullet
 whisker

General Defaults:

 :type              => 'smooth'
 :height            => 14px
 :upper             => 50
 :above_color       => 'red'
 :below_color       => 'grey'
 :background_color  => 'white'
 :line_color        => 'lightgrey'

License

Licensed under the MIT license.

Methods

area   bar   bullet   discrete   new   pie   plot   plot_error   plot_to_file   plot_to_image   smooth   whisker  

Constants

VERSION = '0.5.1'

Public Class methods

Does the actual plotting of the graph. Calls the appropriate subclass based on the :type argument. Defaults to ‘smooth’.

Returns a blob.

Writes a graph to disk with the specified filename, or "sparklines.png".

Plots a sparkline and returns a Magic::Image object.

Public Instance methods

Creates a continuous area sparkline. Relevant options.

  :step - An integer that determines the distance between each point on the sparkline.  Defaults to 2.

  :height - An integer that determines what the height of the sparkline will be.  Defaults to 14

  :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.

  :has_min - Determines whether a dot will be drawn at the lowest value or not.  Defaults to false.

  :has_max - Determines whether a dot will be drawn at the highest value or not.  Defaults to false.

  :has_last - Determines whether a dot will be drawn at the last value or not.  Defaults to false.

  :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.

  :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.

  :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.

  :above_color - A string or color code representing the color to draw values above or equal the upper value.  Defaults to red.

  :below_color - A string or color code representing the color to draw values below the upper value. Defaults to gray.

A bar graph.

Also takes :target option (a line will be drawn) and :upper (values under will be drawn in :below_color, above in :above_color).

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.

Creates a discretized sparkline

  :height - An integer that determines what the height of the sparkline will be.  Defaults to 14

  :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.

  :above_color - A string or color code representing the color to draw values above or equal the upper value.  Defaults to red.

  :below_color - A string or color code representing the color to draw values below the upper value. Defaults to gray.

Creates a pie-chart sparkline

  :diameter - An integer that determines what the size of the sparkline will be.  Defaults to 20

  :share_color - A string or color code representing the color to draw the share of the pie represented by percent.  Defaults to red.

  :remain_color - A string or color code representing the color to draw the pie not taken by the share color. Defaults to lightgrey.

Draw the error Sparkline.

Creates a smooth line graph sparkline.

  :step - An integer that determines the distance between each point on the sparkline.  Defaults to 2.

  :height - An integer that determines what the height of the sparkline will be.  Defaults to 14

  :has_min - Determines whether a dot will be drawn at the lowest value or not.  Defaults to false.

  :has_max - Determines whether a dot will be drawn at the highest value or not.  Defaults to false.

  :has_last - Determines whether a dot will be drawn at the last value or not.  Defaults to false.

  :has_std_dev - Determines whether there will be a standard deviation bar behind the smooth graph or not. Defaults to false.

  :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.

  :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.

  :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.

  :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.

Creates a whisker sparkline to track on/off type data. There are five states: on, off, no value, exceptional on, exceptional off. On values create an up whisker and off values create a down whisker. Exceptional values may be colored differently than regular values to indicate, for example, a shut out. No value produces an empty row to indicate a tie.

  • results - an array of integer values between -2 and 2. -2 is exceptional down, -1 is regular down, 0 is no value, 1 is up, and 2 is exceptional up.
  • options - a hash that takes parameters

    :height - height of the sparkline

    :whisker_color - the color of regular whiskers; defaults to black

    :exception_color - the color of exceptional whiskers; defaults to red

    :step - Spacing for whiskers. Includes the whisker itself. Default 2.

[Validate]