Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
tree: 699243db2d
Fetching contributors…

Cannot retrieve contributors at this time

127 lines (87 sloc) 5.177 kB

Graphene

Graphene is a library for transforming collections of Ruby objects into subtotals, percentages, tables and graphs. It's most useful feature is probably the Gruff helpers. True, some types of Gruff charts are pretty simple to begin with, but others can require tedious boilerplate code to calculate percentages, well-spaced labels, and more. Graphene hides all of that, accepting an array of objects and transforming them into a graph.

Read the full documentation at jordanhollinger.com/docs/graphene/.

Nobody likes you, Ruby 1.8. Now go away.

Installation

$ [sudo] gem install graphene
# Or just add "graphene" to your Gemfile

Gruff is required only by Graphene's graphing component. Because of this, and because Gruff's dependencies can be difficult to install, you will need to install Gruff manually. If you do not/cannot, Graphene's other components will continue to function.

# On Debian/Ubuntu
$ sudo apt-get install librmagick-ruby libmagickcore-dev libmagickwand-dev 

$ [sudo] gem install rmagick gruff
# Or just add "rmagick" and "gruff" to your Gemfile

See nubyonrails.com/pages/gruff/ for more on Gruff.

Percentages

# An array of objects which respond to methods like :browser, :platform, :date
logs = SomeLogParser.parse('/var/log/nginx/access.log.*')

percentages = Graphene.percentages(logs, :browser)

puts percentages.to_a
=> [["Firefox", 40.0], ["Chrome", 35.0], ["Internet Explorer", 25.0]]

percentages.each do |browser, percent|
  puts "#{percent}% of hits were from from #{browser}"
end

# You can also calculate by multiple criteria, and may use lambdas instead of symbols
percentages = Graphene.percentages(logs, ->(l) { l.browser.downcase }, :platform)

puts percentages.to_a
=> [["chrome", "OS X", 40], ["internet explorer", "Windows", 25], ["firefox", "Windows", 25], ["firefox", "GNU/Linux", 8], ["chrome", "GNU/Linux", 2]]

See Graphene.percentages for more info.

Subtotals

Same as percentages above, except that subtotals are returned instead. See Graphene.subtotals for more info.

Adding a dimension

“Marty, you're not thinking fourth-dimensionally!” This is only three dimensions, but whatever, Doc.

puts Graphene.percentages(logs, :browser).over(:date)
=> {#<Date: 2012-07-22> => [["Firefox", 45], ["Chrome", 40], ["Internet Explorer", 15]],
    #<Date: 2012-07-23> => [],
    #<Date: 2012-07-24> => [["Firefox", 41], ["Chrome", 40], ["Internet Explorer", 19]],
    #<Date: 2012-07-25> => [["Chrome", 50], ["Firefox", 40], ["Internet Explorer", 10]]}

Notice that in the results above, there were no log entries on 2012-07-23. The only reason that date showed up at all is because dates are iterable. If your X axis objects are not iterable and you're afraid that empty ones will be skipped over, you can provide them yourself:

# Ryan didn't make any sales, so he won't show up unless we include his name
puts Graphene.subtotals(sales, :reams).over(:name, ['Jim', 'Dwight', 'Ryan'])

# Ruby doesn't know how to iterate months, but you do
puts Graphene.percentages(logs, :browser).over(->(log) { [log.date.month, log.date.year] }) do |month, year|
  month < 12 ? [month + 1, year] : [1, year + 1]
end

Tablizer

Integration with the tablizer gem provides quick ASCII tables.

puts percentages.tablize
=> +-----------------+------------+----------+
   |     Browser     |  Platform  |Percentage|
   +-----------------+------------+----------+
   |Firefox          |Windows     |50.0      |
   |Internet Explorer|Windows     |20.0      |
   |Safari           |OS X        |20.0      |
   |Firefox          |GNU/Linux   |10.0      |
   +-----------------+------------+----------+

Graphs

Provides helpers for generating Gruff graphs. Requires the “gruff” Ruby gem.

# A pie chart of Firefox version shares
ff = logs.select { |e| e.browser == 'Firefox' }
Graphene.percentages(ff, :browser).pie_chart('/path/to/graph.png', 'FF Version Share')

# A line graph of daily browser numbers over time, tricked out with lots of options
Graphene.subtotals(logs, :browser).over(:date).line_graph('/path/to/graph.png') do |chart, labeler|
  chart.title = 'Browser Share'
  chart.font = '/path/to/awesome/font.ttf'
  chart.theme = {
    :colors => %w(orange purple green white red),
    :marker_color => 'blue',
    :background_colors => %w(black grey)
  }

  # Only show every 7th label, and make dates pretty
  labeler.call(7) do |date|
    date.strftime('%b %e')
  end
end

See Graphene::OneDGraphs and Graphene::TwoDGraphs for more types and examples.

See www.ruby-doc.org/gems/docs/f/fhs-gruff-0.3.6.2/README_txt.html for more on Gruff. Specifically, www.ruby-doc.org/gems/docs/f/fhs-gruff-0.3.6.2/Gruff/Base.html will let you know many things that can be customized in the optional block.

TODO

Graphene::OverX and the graph helpers needs the ability to fill in empty points

License

Copyright 2012 Jordan Hollinger

Licensed under the Apache License

Jump to Line
Something went wrong with that request. Please try again.