graphene 0.0.1

data/LICENSE

@@ -0,0 +1,13 @@
+   Copyright 2012 Jordan Hollinger
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

data/README.rdoc

@@ -0,0 +1,101 @@
+= 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 http://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 http://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, count|
+      puts "There were #{count} hits 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.
+
+== 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 http://gruff.rubyforge.org/classes/Gruff/Base.html for more Gruff options.
+
+== 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

data/lib/graphene/graphene.rb

@@ -0,0 +1,55 @@
+module Graphene
+  # Class for Graphene Exceptions
+  class GrapheneException < StandardError; end
+
+  # For the given resources, returns the share of the count that each attr(s) has.
+  # 
+  # "resources" is an array of objects which responds to the "args" method(s).
+  # 
+  # "args" is one or more method symbols or proc/lambda which each object in "resources" responds to. 
+  # Subtotals will be calculated from the returned values.
+  # 
+  # Returns an instance of Graphene::Subtotals, which implements Enumerable. Each member is
+  # an array of [attribute(s), count]
+  # 
+  # Example, Browser Family share:
+  # 
+  #  Graphene.subtotals(logins, :browser_family).to_a
+  #  => [['Firefox', 5040], ['Chrome', 1960], ['Internet Explorer', 1500], ['Safari', 1000], ['Unknown', 500]]
+  # 
+  # Example, Browser/OS share, asking for symbols back:
+  # 
+  #  Graphene.subtotals(server_log_entries, :browser_sym, :os_sym).to_a
+  #  => [[:firefox, :windows_7, 50.4, 5040], [:chrome, :osx, 19.6, 1960], [:msie, :windows_xp, 15, 1500], [:safari, :osx, 10, 1000], [:other, :other, 5, 100]]
+  #
+  def self.subtotals(resources, *args)
+    Subtotals.new(resources, *args)
+  end
+
+  # For the given "resources", returns the % share of the group that each attr(s) has.
+  # 
+  # "resources" is an array of objects which responds to the "args" method(s).
+  # 
+  # "args" is one or more method symbols or proc/lambda which each object in "resources" responds to. 
+  # Percentages will be calculated from the returned values.
+  # 
+  # "args" may have, as it's last member, :threshold => n, where n is the number of the lowest
+  # percentage you want returned.
+  # 
+  # Returns an instance of Graphene::Percentages, which implements Enumerable. Each member is
+  # an array of [attribute(s), percentage]
+  # 
+  # Example, Browser Family share:
+  # 
+  #  Graphene.percentages(logins, :browser_family).to_a
+  #  => [['Firefox', 50.4], ['Chrome', 19.6], ['Internet Explorer', 15], ['Safari', 10], ['Unknown', 5]]
+  # 
+  # Example, Browser/OS share, asking for symbols back:
+  # 
+  #  Graphene.percentages(server_log_entries, :browser_sym, :os_sym).to_a
+  #  => [[:firefox, :windows_7, 50.4], [:chrome, :osx, 19.6], [:msie, :windows_xp, 15], [:safari, :osx, 10], [:other, :other, 5]]
+  #
+  def self.percentages(resources, *args)
+    Percentages.new(resources, *args)
+  end
+end

data/lib/graphene/gruff.rb

@@ -0,0 +1,360 @@
+module Graphene
+  # Executes the given block if Gruff is available. Raises a GrapheneException if not.
+  def self.gruff
+    if defined? Gruff
+      yield if block_given?
+    else
+      raise GrapheneException, "Gruff integration is disabled because Gruff could not be loaded; install the \"gruff\" gem"
+    end
+  end
+
+  # Extends calculators with one-dimensional graphs, like pie charts.
+  module OneDGraphs
+    # Returns a Gruff::Pie object with the stats set.
+    #
+    # Optionally you may pass a file path and graph title. If you pass a file path, the graph will
+    # be written to file automatically. Otherwise, you would call "write('/path/to/graph.png')" on the
+    # returned graph object.
+    #
+    # If you pass a block, it will be called, giving you access to the Gruff::Pie object before it is
+    # written to file (that is, if you also passed a file path).
+    # 
+    # Example 1:
+    # 
+    #  Graphene.percentages(logs, :browser).pie_chart('/path/to/browser-share.png', 'Browser Share')
+    #
+    # Example 2:
+    #
+    #  Graphene.percentages(logs, :browser).pie_chart('/path/to/browser-share.png') do |pie|
+    #    pie.title = 'Browser Share'
+    #    pie.font = '/path/to/font.ttf'
+    #    pie.theme = pie.theme_37signals
+    #  end
+    # 
+    # Example 3:
+    # 
+    #  blog = Graphene.percentages(logs, :browser).pie_chart.to_blob
+    #
+    def pie_chart(path=nil, title=nil, &block)
+      Graphene.gruff do
+        chart(Gruff::Pie.new, path, title, &block)
+      end
+    end
+    alias_method :pie_graph, :pie_chart
+
+    # Returns a Gruff::Bar object with the stats set.
+    #
+    # Optionally you may pass a file path and chart title. If you pass a file path, the chart will
+    # be written to file automatically. Otherwise, you would call "write('/path/to/graph.png')" on the
+    # returned chart object.
+    #
+    # If you pass a block, it will be called, giving you access to the Gruff::Bar object before it is
+    # written to file (that is, if you also passed a file path).
+    # 
+    # Example 1:
+    # 
+    #  Graphene.percentages(logs, :browser).bar_chart('/path/to/browser-share.png', 'Browser Share')
+    #
+    # Example 2:
+    #
+    #  Graphene.percentages(logs, :browser).bar_chart('/path/to/browser-share.png') do |chart|
+    #    chart.title = 'Browser Share'
+    #    chart.font = '/path/to/font.ttf'
+    #    chart.theme = chart.theme_37signals
+    #  end
+    # 
+    # Example 3:
+    # 
+    #  blog = Graphene.subtotals(logs, :browser).bar_chart.to_blob
+    #
+    def bar_chart(path=nil, title=nil, &block)
+      Graphene.gruff do
+        chart(Gruff::Bar.new, path, title, false, &block)
+      end
+    end
+    alias_method :bar_graph, :bar_chart
+
+    # Returns a Gruff::StackedBar object with the stats set.
+    #
+    # Optionally you may pass a file path and chart title. If you pass a file path, the chart will
+    # be written to file automatically. Otherwise, you would call "write('/path/to/graph.png')" on the
+    # returned chart object.
+    #
+    # If you pass a block, it will be called, giving you access to the Gruff::StackedBar object before it is
+    # written to file (that is, if you also passed a file path).
+    # 
+    # Example 1:
+    # 
+    #  Graphene.percentages(logs, :browser).stacked_bar_chart('/path/to/browser-share.png', 'Browser Share')
+    #
+    # Example 2:
+    #
+    #  Graphene.percentages(logs, :browser).stacked_bar_chart('/path/to/browser-share.png') do |chart|
+    #    chart.title = 'Browser Share'
+    #    chart.font = '/path/to/font.ttf'
+    #    chart.theme = chart.theme_37signals
+    #  end
+    # 
+    # Example 3:
+    # 
+    #  blog = Graphene.subtotals(logs, :browser).stacked_bar_chart.to_blob
+    #
+    def stacked_bar_chart(path=nil, title=nil, &block)
+      Graphene.gruff do
+        chart(Gruff::StackedBar.new, path, title, true, &block)
+      end
+    end
+    alias_method :stacked_bar_graph, :stacked_bar_chart
+
+    # Returns a Gruff::SideBar object with the stats set.
+    #
+    # Optionally you may pass a file path and chart title. If you pass a file path, the chart will
+    # be written to file automatically. Otherwise, you would call "write('/path/to/graph.png')" on the
+    # returned chart object.
+    #
+    # If you pass a block, it will be called, giving you access to the Gruff::SideBar object before it is
+    # written to file (that is, if you also passed a file path).
+    # 
+    # Example 1:
+    # 
+    #  Graphene.percentages(logs, :browser).side_bar_chart('/path/to/browser-share.png', 'Browser Share')
+    #
+    # Example 2:
+    #
+    #  Graphene.percentages(logs, :browser).side_bar_chart('/path/to/browser-share.png') do |chart|
+    #    chart.title = 'Browser Share'
+    #    chart.font = '/path/to/font.ttf'
+    #    chart.theme = chart.theme_37signals
+    #  end
+    # 
+    # Example 3:
+    # 
+    #  blog = Graphene.subtotals(logs, :browser).side_bar_chart.to_blob
+    #
+    def side_bar_chart(path=nil, title=nil, &block)
+      Graphene.gruff do
+        chart(Gruff::SideBar.new, path, title, true, &block)
+      end
+    end
+    alias_method :side_bar_graph, :side_bar_chart
+
+    # Returns a Gruff::StackedSideBar object with the stats set.
+    #
+    # Optionally you may pass a file path and chart title. If you pass a file path, the chart will
+    # be written to file automatically. Otherwise, you would call "write('/path/to/graph.png')" on the
+    # returned chart object.
+    #
+    # If you pass a block, it will be called, giving you access to the Gruff::StackedSideBar object before it is
+    # written to file (that is, if you also passed a file path).
+    # 
+    # Example 1:
+    # 
+    #  Graphene.percentages(logs, :browser).side_stacked_bar_chart('/path/to/browser-share.png', 'Browser Share')
+    #
+    # Example 2:
+    #
+    #  Graphene.percentages(logs, :browser).side_stacked_bar_chart('/path/to/browser-share.png') do |chart|
+    #    chart.title = 'Browser Share'
+    #    chart.font = '/path/to/font.ttf'
+    #    chart.theme = chart.theme_37signals
+    #  end
+    # 
+    # Example 3:
+    # 
+    #  blog = Graphene.subtotals(logs, :browser).side_stacked_bar_chart.to_blob
+    #
+    def side_stacked_bar_chart(path=nil, title=nil, &block)
+      Graphene.gruff do
+        chart(Gruff::SideStackedBar.new, path, title, true, &block)
+      end
+    end
+    alias_method :side_stacked_bar_graph, :side_stacked_bar_chart
+
+    # Returns a Gruff::Spider object with the stats set.
+    #
+    # Optionally you may pass a file path and chart title. If you pass a file path, the chart will
+    # be written to file automatically. Otherwise, you would call "write('/path/to/graph.png')" on the
+    # returned chart object.
+    #
+    # If you pass a block, it will be called, giving you access to the Gruff::Spider object before it is
+    # written to file (that is, if you also passed a file path).
+    # 
+    # Example 1:
+    # 
+    #  Graphene.percentages(logs, :browser).spider_chart('/path/to/browser-share.png', 'Browser Share')
+    #
+    # Example 2:
+    #
+    #  Graphene.percentages(logs, :browser).spider_chart('/path/to/browser-share.png') do |chart|
+    #    chart.title = 'Browser Share'
+    #    chart.font = '/path/to/font.ttf'
+    #    chart.theme = chart.theme_37signals
+    #  end
+    # 
+    # Example 3:
+    # 
+    #  blog = Graphene.subtotals(logs, :browser).spider_chart.to_blob
+    #
+    def spider_chart(path=nil, title=nil, &block)
+      Graphene.gruff do
+        chart(Gruff::Spider.new(max_result), path, title, false, &block)
+      end
+    end
+    alias_method :spider_graph, :spider_chart
+
+    private
+
+    # Builds a chart
+    def chart(chart, path=nil, title=nil, hack=false, &block)
+      chart.title = title unless title.nil?
+      block.call(chart) if block
+
+      each do |result|
+        name = result[0..attributes.size-1].join(' / ')
+        n = result[attributes.size]
+        chart.data name, n
+      end
+      # XXX Required by SideBar and SideStackedBar. Probably a bug.
+      chart.labels = {0 => ' '} if hack
+
+      chart.write(path) unless path.nil?
+      chart
+    end
+  end
+
+  # Extends calculators with two-dimensional graphs, like line graphs.
+  module TwoDGraphs
+    # Returns a Gruff::Line object with the stats set.
+    #
+    # Optionally you may pass a file path and graph title. If you pass a file path, the graph will
+    # be written to file automatically. Otherwise, you would call "write('/path/to/graph.png')" on the
+    # returned graph object.
+    #
+    # If you pass a block, it will be called, giving you access to the Gruff::Line object before it is
+    # written to file (that is, if you also passed a file path). It will also give you access to a Proc
+    # for labeling the X axis.
+    #
+    # Example 1:
+    # 
+    #  Graphene.percentages(logs, :browser).over(:date).line_graph('/path/to/browser-share.png', 'Browser Share')
+    #
+    # Example 2:
+    #
+    #  Graphene.subtotals(logs, :browser).over(:date).line_graph('/path/to/browser-share.png') do |chart, labeler|
+    #    chart.title = 'Browser Share'
+    #    chart.font = '/path/to/font.ttf'
+    #    chart.theme = pie.theme_37signals
+    #  end
+    #
+    # Example 3:
+    #
+    #  Graphene.subtotals(logs, :browser).over(:date).line_graph('/path/to/browser-share.png') do |chart, labeler|
+    #    chart.title = 'Browser Share'
+    #
+    #    # Both the 10 and the block are optional.
+    #    #  - "10" means that only every 10'th label will be printed. Otherwise, each would be.
+    #    #  - The block is passed each label (the return value of the "over attribute") and may return a formatted version.
+    #    labeler.call(10) do |date|
+    #      date.strftime('%m/%d/%Y')
+    #    end
+    #  end
+    #
+    # Example 4:
+    #
+    #  Graphene.percentages(logs, :platform, :browser).over(->(l) { l.date.strftime('%m/%Y') }).line_graph('/path/to/os-browser-share.png', 'OS / Browser Share by Month')
+    #
+    def line_graph(path=nil, title=nil, &block)
+      Graphene.gruff do
+        graph(Gruff::Line.new, path, title, &block)
+      end
+    end
+    alias_method :line_chart, :line_graph
+
+    # Returns a Gruff::Net object with the stats set.
+    #
+    # Optionally you may pass a file path and graph title. If you pass a file path, the graph will
+    # be written to file automatically. Otherwise, you would call "write('/path/to/graph.png')" on the
+    # returned graph object.
+    #
+    # If you pass a block, it will be called, giving you access to the Gruff::Net object before it is
+    # written to file (that is, if you also passed a file path). It will also give you access to a Proc
+    # for labeling the X axis.
+    #
+    # Example 1:
+    # 
+    #  Graphene.percentages(logs, :browser).over(:date).net_graph('/path/to/browser-share.png', 'Browser Share')
+    #
+    # Example 2:
+    #
+    #  Graphene.subtotals(logs, :browser).over(:date).net_graph('/path/to/browser-share.png') do |chart, labeler|
+    #    chart.title = 'Browser Share'
+    #    chart.font = '/path/to/font.ttf'
+    #    chart.theme = pie.theme_37signals
+    #  end
+    #
+    # Example 3:
+    #
+    #  Graphene.subtotals(logs, :browser).over(:date).net_graph('/path/to/browser-share.png') do |chart, labeler|
+    #    chart.title = 'Browser Share'
+    #
+    #    # Both the 10 and the block are optional.
+    #    #  - "10" means that only every 10'th label will be printed. Otherwise, each would be.
+    #    #  - The block is passed each label (the return value of the "over attribute") and may return a formatted version.
+    #    labeler.call(10) do |date|
+    #      date.strftime('%m/%d/%Y')
+    #    end
+    #  end
+    #
+    # Example 4:
+    #
+    #  Graphene.percentages(logs, :platform, :browser).over(->(l) { l.date.strftime('%m/%Y') }).net_graph('/path/to/os-browser-share.png', 'OS / Browser Share by Month')
+    #
+    def net_graph(path=nil, title=nil, &block)
+      Graphene.gruff do
+        graph(Gruff::Net.new, path, title, &block)
+      end
+    end
+    alias_method :net_chart, :net_graph
+
+    private
+
+    # Builds a graph
+    def graph(graph, path=nil, title=nil, &block)
+      graph.title = title unless title.nil?
+
+      # Create an empty array for each group (e.g. {["Firefox"] => [], ["Safari"] => []}), even if it's empty.
+      data = inject({}) do |dat, (label, rows)|
+        for row in rows
+          attrs = row[0..-2]
+          dat[attrs] ||= []
+        end
+        dat
+      end
+
+      # Group the data on the x axis
+      to_a.each do |x_attr, rows|
+        groups = rows.group_by { |row| row[0..-2] }
+        for attrs, dat in data
+          dat << (groups[attrs] ? groups[attrs].last.last : 0)
+        end
+      end
+
+      # Build the labeling proc
+      label_every_n, labeler = 1, :to_s.to_proc
+      get_labeler = proc do |n=1, &block|
+        label_every_n = n
+        labeler = block if block
+      end
+      yield(graph, get_labeler) if block_given?
+      # Build labels and add them to graph
+      labels = @results.keys
+      graph.labels = Hash[*labels.select { |x| labels.index(x) % label_every_n == 0 }.map { |x| [*labels.index(x), labeler[x]] }.flatten]
+
+      # Add data to the graph
+      data.each { |attrs, dat| graph.data(attrs.join(' / '), dat) }
+
+      graph.write(path) unless path.nil?
+      graph
+    end
+  end
+end

data/lib/graphene/lazy_enumerable.rb

@@ -0,0 +1,33 @@
+module Graphene
+  # Includes Enumerable and alculates @results lazily. An enumerate! method must be implemented.
+  module LazyEnumerable
+    def self.included(base) # :nodoc:
+      base.send(:include, Enumerable)
+    end
+
+    # Implements the "each" method required by Enumerable.
+    def each(&block)
+      lazily_enumerate!
+      @results.each &block
+    end
+
+    # Tests equality between this and another set
+    def ==(other)
+      lazily_enumerate!
+      to_a == other.to_a
+    end
+
+    # Tests equality between this and another set
+    def ===(other)
+      lazily_enumerate!
+      to_a === other.to_a
+    end
+
+    private
+
+    # Run the calculation if it hasn't already been
+    def lazily_enumerate!
+      enumerate! if @results.empty?
+    end
+  end
+end

data/lib/graphene/over_x.rb

@@ -0,0 +1,49 @@
+module Graphene
+  # Groups the stats of resources by the given method symbol or lambda.
+  # 
+  # Example by date
+  # 
+  #  Graphene.percentages(logs, :browser).over(:date)
+  #  => {#<Date: 2012-07-22> => [["Firefox", 45], ["Chrome", 40], ["Internet Explorer", 15]],
+  #      #<Date: 2012-07-23> => [["Firefox", 41], ["Chrome", 40], ["Internet Explorer", 19]],
+  #      #<Date: 2012-07-24> => [["Chrome", 50], ["Firefox", 40], ["Internet Explorer", 10]]}
+  #
+  # See Graphene::LazyEnumerable, Graphene::Tablize and Graphene::TwoDGraphs for more documentation.
+  class OverX
+    include LazyEnumerable
+    include TwoDGraphs
+
+    # The attribute that are being statted, passed in the constructor
+    attr_reader :result_set
+
+    # Accepts a ResultSet object (i.e. Graphene::Subtotals or Graphene::Percentages), and a
+    # method symbol or proc/lambda to build the X axis
+    def initialize(result_set, attr_or_lambda)
+      @result_set = result_set
+      @attribute = attr_or_lambda
+      @results = {}
+    end
+
+    # Returns a string representation of the results
+    def to_s
+      to_hash.to_s
+    end
+
+    # Returns a Hash representation of the results
+    def to_hash
+      @results.clone
+    end
+
+    private
+
+    # Run the calculation
+    def enumerate!
+      resources_by_x = result_set.resources.group_by(&@attribute).sort_by(&:first)
+      @results = resources_by_x.inject({}) do |results, (x, group)|
+        results[x] ||= []
+        results[x] += result_set.class.new(group, *result_set.attributes).to_a
+        results
+      end
+    end
+  end
+end

data/lib/graphene/percentages.rb

@@ -0,0 +1,36 @@
+require 'graphene/subtotals'
+
+module Graphene
+  # Calculates and contains the percent subtotals of each attr (or attr group). Inherits from Graphene::ResultSet.
+  # See Graphene::LazyEnumerable, Graphene::Tablize and Graphene::OneDGraphs for more documentation.
+  # 
+  # If you passed an options Hash containing :threshold to the constructor, 
+  # any results falling below it will be excluded.
+  # 
+  # Don't create instance manually. Instead, use the Graphene.percentages method, which will return
+  # a properly instantiated object.
+  class Percentages < ResultSet
+    # Convert the percentages to subtotals
+    def subtotals(opts=nil)
+      @subtotals ||= transmogrify(Subtotals, opts)
+    end
+
+    private
+
+    # Perform the calculations
+    def enumerate!
+      # Now replace them with the percentages
+      total = resources.size.to_f
+      # Replace the subtotal with the percent
+      @results = subtotals.map do |*args, count|
+        percent = ((count * 100) / total).round(2)
+        [*args, percent]
+      end
+
+      # Drop results that are too small
+      if options.has_key? :threshold
+        @results.reject! { |result| result[-1] < options[:threshold] }
+      end
+    end
+  end
+end

data/lib/graphene/result_set.rb

@@ -0,0 +1,59 @@
+module Graphene
+  # A generic class for Graphene stat result sets, which implements Enumerable and Graphene::LazyEnumerable.
+  # Calculations are performed lazily, so ResultSet objects are *cheap to create, but not necessarily cheap to use*.
+  class ResultSet
+    include LazyEnumerable
+    include Tablize
+    include OneDGraphs
+
+    # The options Hash passed in the constructor
+    attr_reader :options
+    # The attribute(s) that are being statted, passed in the constructor
+    attr_reader :attributes
+    # The original array of objects from which the stats were generated
+    attr_reader :resources
+
+    # Accepts an array of objects, and an unlimited number of method symbols (which sould be methods in the objects).
+    # Optionally accepts an options hash as a last argument.
+    #
+    # Implements Enumerable, so the results can be accessed by any of those methods, including each and to_a.
+    def initialize(resources, *args)
+      @options = args.last.is_a?(Hash) ? args.pop : {}
+      @attributes = args
+      @resources = resources
+      @results = []
+    end
+
+    # Calculates the resources, gropuing them by "over_x", which can be a method symbol or lambda
+    # 
+    # Example by date
+    # 
+    #  Graphene.percentages(logs, :browser).over(:date)
+    #  => {#<Date: 2012-07-22> => [["Firefox", 45], ["Chrome", 40], ["Internet Explorer", 15]],
+    #      #<Date: 2012-07-23> => [["Firefox", 41], ["Chrome", 40], ["Internet Explorer", 19]],
+    #      #<Date: 2012-07-24> => [["Chrome", 50], ["Firefox", 40], ["Internet Explorer", 10]]}
+    #
+    def over(over_x)
+      OverX.new(self, over_x)
+    end
+
+    # Returns a string representation of the results
+    def to_s
+      to_a.to_s
+    end
+
+    # Returns the maximum result
+    def max_result
+      x = attributes.size
+      sort_by { |result| result[x] }.last[x]
+    end
+
+    private
+
+    # Change it to another ResultSet subclass
+    def transmogrify(klass, opts=nil)
+      opts ||= self.options
+      klass.new(resources, *attributes, opts)
+    end
+  end
+end

data/lib/graphene/subtotals.rb

@@ -0,0 +1,32 @@
+require 'graphene/result_set'
+
+module Graphene
+  # Calculates and contains the subtotals of each attr (or attr group). Inherits from Graphene::ResultSet.
+  # See Graphene::LazyEnumerable, Graphene::Tablize and Graphene::OneDGraphs for more documentation.
+  # 
+  # Don't create instance manually. Instead, use the Graphene.subtotals method, which will return
+  # a properly instantiated object.
+  class Subtotals < ResultSet
+    # Convert the percentages to subtotals
+    def percentages(opts=nil)
+      transmogrify(Percentages, opts)
+    end
+
+    private
+
+    # Calculates the subtotals
+    def enumerate!
+      # Count the occurrence of each
+      results = resources.inject({}) do |res, resource|
+        attrs = attributes.map { |attr| attr.respond_to?(:call) ? attr.call(resource) : resource.send(attr) }
+        res[attrs] ||= 0
+        res[attrs] += 1
+        res
+      end.to_a
+      results.each(&:flatten!)
+      # Sort in ascending order
+      results.sort! { |a,b| b.last <=> a.last }
+      @results = results
+    end
+  end
+end

data/lib/graphene/tablizer.rb

@@ -0,0 +1,15 @@
+module Graphene
+  module Tablize
+    # Return the results formatted by the tablizer gem. Do disable headers, pass :header => false. Set alignment with :align.
+    def tablize(options={})
+      rows = to_a
+      # Default to including headers
+      unless options[:header] == false
+        headers = attributes.map(&:to_s) << self.class.name.scan(/\w+$/).last.to_s.gsub(/s$/, '').capitalize
+        rows.unshift(headers)
+        options[:header] = true
+      end
+      Tablizer::Table.new(rows, options)
+    end
+  end
+end

data/lib/graphene/version.rb

@@ -0,0 +1,4 @@
+module Graphene
+  # Version number
+  VERSION = '0.0.1'
+end

data/lib/graphene.rb

@@ -0,0 +1,21 @@
+# Required gems
+require 'tablizer'
+begin
+  require 'gruff'
+rescue LoadError => e
+  $stderr.puts "NOTICE Graphene cannot find Gruff; graphing will not be not available. Install the \"gruff\" gem in enable it."
+end
+
+require 'graphene/version'
+require 'graphene/graphene'
+
+# Formatters and helpers
+require 'graphene/tablizer'
+require 'graphene/gruff'
+
+# Calculators
+require 'graphene/lazy_enumerable'
+require 'graphene/result_set'
+require 'graphene/subtotals'
+require 'graphene/percentages'
+require 'graphene/over_x'

metadata

@@ -0,0 +1,89 @@
+--- !ruby/object:Gem::Specification 
+name: graphene
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 0
+  - 1
+  version: 0.0.1
+platform: ruby
+authors: 
+- Jordan Hollinger
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2012-07-22 00:00:00 -04:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: tablizer
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 1
+        - 0
+        version: "1.0"
+  type: :runtime
+  version_requirements: *id001
+description: Library for calculating subtotals, percentages, tables and graphs from collections of Ruby objects
+email: jordan@jordanhollinger.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- lib/graphene.rb
+- lib/graphene/graphene.rb
+- lib/graphene/gruff.rb
+- lib/graphene/gruff_helpers.rb
+- lib/graphene/percentages.rb
+- lib/graphene/result_set.rb
+- lib/graphene/subtotals.rb
+- lib/graphene/tablizer.rb
+- lib/graphene/version.rb
+- lib/graphene/over_x.rb
+- lib/graphene/lazy_enumerable.rb
+- README.rdoc
+- LICENSE
+has_rdoc: true
+homepage: http://github.com/jhollinger/graphene
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Easily create stats and graphs from collections of Ruby objects
+test_files: []
+