gerbilcharts

DESCRIPTION:

SVG based Ruby charting library.

FEATURES/PROBLEMS:

  • All common chart types supported (Line, Stacked Area, Pie, Bar, Area)

  • If used in a Rails app, SVG is fully generated server side

  • Javascript is used within the SVG document for interactivity only

  • Completely change look and feel via a SVG CSS

  • Show tooltips, handle clicks on chart objects

  • Ajax enabled. gerbil.js allows each chart to autoupdate itself with new SVG elements.

Known issues :

  • Requires a browser that can handle SVG such as Firefox/Opera.

  • IE + Adobe SVG Viewer works but has some problems w/ Ajax

Note on stylesheets

GerbilCharts uses stylesheets to customize appearances of almost all visual elements (colors, fonts, line strokes, fills). You can use the supplied stylesheet (eg, brushmetal.css) or derive your own from it. GerbilCharts searches for stylesheets in the working directory and the public directory of the gerbilcharts gem.

SYNOPSIS:

Simple timeseries example

Assumes all models (data series) have values at discrete time points.

require 'rubygems'
gem 'gerbilcharts'
require 'gerbilcharts'

# test  sales figures of 3 sales people
# use a simple timeseries model 
mychart = GerbilCharts::Charts::LineChart.new( :width => 350, :height => 200, :style => 'brushmetal.css',
                                               :circle_data_points => true )

modelgroup = GerbilCharts::Models::SimpleTimeSeriesModelGroup.new(
                 :title => "Sales figures",
                 :timeseries  =>  (1..6).collect { |month| Time.local(2008,month) },
                 :models =>       [ ["Bruce", 1,  10, 18, 28, 80,  122],
                                    ["Rex"  , 112,22, 45, 70, 218, 309],
                                    ["Buzo" , 0,  23, 25, 40, 18,  59]
                                  ]
               )
mychart.modelgroup=modelgroup
mychart.render('/tmp/monthly_sales.svg')

To view the chart:

  • firefox /tmp/monthly_sales.svg

Rails example

The most common use of gerbilcharts will be in a Rails application. Here is a guide to quickly get you on board. You can skip the first three steps if you already have a rails app up and running.

First install gerbilcharts sudo gem install gerbilcharts

Generate a test app called gtest rails generate gtest

Create a controller cd gtest ruby script/generate controller tgerbil

Copy the following code into app/controllers/tgerbil_controller.rb

require ‘gerbilcharts’

class GerbtController < ApplicationController

# render inline to browser without using a temp file def tgerb

# test sales figures of 3 sales people # use a simple timeseries model # output to string finally mychart = GerbilCharts::Charts::LineChart.new( :width => 350, :height => 200, :style => ‘brushmetal.css’, :circle_data_points => true )

mychart.modelgroup = GerbilCharts::Models::SimpleTimeSeriesModelGroup.new( :title => “Sales figures”, :timeseries => (1..6).collect { |month| Time.local(2008,month) }, :models => [ [“Bruce”, 1, 10, 18, 28, 80, 122], [“Rex” , 112,22, 45, 70, 218, 309], [“Buzo” , 0, 23, 25, 40, 18, 59] ] )

send_data mychart.render_string, :disposition => ‘inline’, :type => ‘image/svg+xml’

end

end

Start the web server ruby script/server

Point to website and test out the chart at localhost:3000/tgerbil/tgerb

Bucketizer example

This is a typical use of gerbilcharts. A number of timeseries data sources of various resolutions are bucketized uniformly and shown on a variety of charts. In this example, data points at varying intervals of approx 5 mins are collated into 15 min buckets using the BucketizedTimeSeriesGraphModel. This sample also shows the seperation of the data from the view. In the sample below, we switch the view from an ImpulseChart to a StackedAreaChart without touching the model.

require ‘rubygems’ gem ‘gerbilcharts’ require ‘gerbilcharts’

# Helper class to generate time series data for test purposes class TimeSeriesDataGenerator attr_reader :tuples_array # allows you to generate controlled random data # tm_from, tm_to = start,end time (a Time object) # avg_resolution_secs = generate a sample approx this many seconds. Varies randomly /-25% # max,min = max and min value def initialize(tm_from, tm_to, avg_resolution_secs, min_val, max_val) @tuples_array=[] tm_tmp = tm_from while tm_tmp < tm_to @tuples_array << [ tm_tmp, min_val (max_val - min_val)*rand ] tm_tmp = tm_tmp + avg_resolution_secs *( 1 + (rand-0.5)/4) end end # iterator def each_tuple @tuples_array.each do |t,v| yield t,v end end end

# create an impulse chart 450x200 using the supplied brushmetal theme mychart = GerbilCharts::Charts::ImpulseChart.new( :width => 450, :height => 200, :style => ‘brushmetal.css’) # generate traffic sample 1 (eth0) at approx 5 min intervals and feed into a bucketizer model of 15 min tend = Time.now tbegin = tend - 3600*24 model1 = GerbilCharts::Models::BucketizedTimeSeriesGraphModel.new( “eth0”, 900 ) TimeSeriesDataGenerator.new(tbegin,tend,300,200000, 6000000).each_tuple do |t,v| model1.add(t,v) end # generate traffic sample 2(wan1) at approx 5 min intervals and feed into a bucketizer model of 15 min model2 = GerbilCharts::Models::BucketizedTimeSeriesGraphModel.new( “wan1”, 900 ) TimeSeriesDataGenerator.new(tbegin,tend,300,500000, 2000000).each_tuple do |t,v| model2.add(t,v) end # add these models to a modelgroup and render it modelgroup = GerbilCharts::Models::GraphModelGroup.new( “External Traffic”) modelgroup.add model1 modelgroup.add model2 mychart.modelgroup=modelgroup mychart.render(‘/tmp/daily_traffic.svg’)

# attach the same model to a stacked area chart and show it # this demonstrates how the views can be changed dynamically

mysachart = GerbilCharts::Charts::StackedAreaChart.new( :width => 450, :height => 200, :style => ‘brushmetal.css’) mysachart.modelgroup=modelgroup mysachart.render(‘/tmp/daily_traffic_stacked_area.svg’)

To view the charts:

  • firefox /tmp/daily_traffic.svg

  • firefox /tmp/daily_traffic_stacked_area.svg

Bucketizer rails example

Use the bucketizer if you want to present timeseries data at a lower resolution that that of the incoming stream. The sample code is shown below. Copy paste this code into a controller to test the bucketizer

require ‘gerbilcharts’

class GerbtController < ApplicationController

# use the bucketized model only if we want the output to have a lower resolution # than the incoming data def tbucket

# create a model group, this houses the individual models modelgroup = GerbilCharts::Models::GraphModelGroup.new(“Price trends”)

# bucketized models, we create one and add it to the group bucket1 = GerbilCharts::Models::BucketizedTimeSeriesGraphModel.new(“Selling Price”,60) tbeg = Time.local( 1978, “jun”, 5, 9, 10, 0, 0) # generate some random values at random resolution between 5 and 30 seconds # the timestamps of incoming data start from jun 5 9:10 AM :w 100.times do |c| tbeg = tbeg + 5 + rand*30 bucket1.add tbeg, rand*1000 end

# add all models to the group , we will chart the group modelgroup.add(bucket1)

# create a area chart mychart = GerbilCharts::Charts::AreaChart.new( :width => 350, :height => 200, :style => ‘brushmetal.css’)

# connect the model group to the chart mychart.setmodelgroup(modelgroup)

send_data mychart.render_string, :disposition => ‘inline’, :type => ‘image/svg+xml’

end

end

Tooltips example

GerbilCharts can be interactive just like Flash charts. This is accomplished by a combination of SVG and Javascript. The Javascript is packaged in the file gerbil.js (requires prototype.js)

Todo: A sample please (extract from Web Trisul)

Time selector example

You can even select time intervals from the SVG using gerbil.js.

Todo: A sample please (extract from Web Trisul)

REQUIREMENTS:

  • builder gem

INSTALL:

  • sudo gem install gerbilcharts

LICENSE:

(The MIT License)

Copyright © 2008-10 Vivek Rajagopalan (vivek at unleashnetworks )

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the ‘Software’), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED ‘AS IS’, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.