Working gem

Author: David Roberts

.ruby-version

@@ -0,0 +1 @@
+2.1.3

Gemfile

@@ -1,4 +1,4 @@
 source 'https://rubygems.org'
 
-# Specify your gem's dependencies in activerecord_pg_histogram.gemspec
+# Specify your gem's dependencies in pg_histogram.gemspec
 gemspec

README.md

@@ -1,29 +1,51 @@
-# ActiverecordPgHistogram
+# PostgreSQL Histogram (for ActiveRecord)
+
+This gem allows for you to efficiently create a histogram from large data sets in your Rails applications.
+
+It uses PostgreSQL's [width_bucket](http://www.postgresql.org/docs/9.3/static/functions-math.html) function to handle the majority of the processing in the database, and only requires 3 database queries.
+
 
-TODO: Write a gem description
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
-    gem 'activerecord_pg_histogram'
+    gem 'pg_histogram'
 
 And then execute:
 
     $ bundle
 
 Or install it yourself as:
 
-    $ gem install activerecord_pg_histogram
+    $ gem install pg_histogram
 
 ## Usage
 
-TODO: Write usage instructions here
+Create a Histogram object using the following there parameters:
+1. ActiveRecord query to use
+2. Name of column to count frequency of
+3. Bucket size (OPTIONAL - default is 0.5)
+
+
+    histogram = PgHistogram::Histogram.new(Widget.all, 'price', 0.5)
+
+
+Call the results method to retrieve a Hash of bucket minimums and frequency counts
+
+    # create sample data
+    5.times do { Widget.create(price: 1.2) }
+    10.times do { Widget.create(price: 2.9 ) }
+
+    # get the results
+    @histogram_data = histogram.results
+     => {1.0=>5, 2.5=>10}
+
+
+The results can be used by your favorite charting libary, such as [Chartkick](https://github.com/ankane/chartkick), to plot the data.
+
+    <%= column_chart @histogram_data %>
 
-## Contributing
+## Dependencies
 
-1. Fork it
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create new Pull Request
+This gem has been tested with Ruby 2.1.3 and ActiveRecord 4.1.6. Please open an issue or PR if you experience issues with other versions.

lib/activerecord_pg_histogram.rb

@@ -0,0 +1,5 @@
+require 'pg_histogram/version'
+require 'pg_histogram/histogram'
+
+module PgHistogram
+end

lib/activerecord_pg_histogram/histogram.rb

@@ -0,0 +1,86 @@
+module PgHistogram
+  class Histogram
+    attr_reader :query, :column, :bucket_size
+
+    BUCKET_COL = 'bucket'
+    FREQUENCY_COL = 'frequency'
+    ROUND_METHODS_BY_DIRECTION = {
+      nil => :round,
+      down:  :floor,
+      up:    :ceil
+    }
+
+    # column_name name must be safe for SQL injection
+    def initialize(query, column_name, bucket_size = 0.5)
+      @query = query
+      @column = column_name.to_s
+      @bucket_size = bucket_size
+    end
+
+    # returns histogram as hash
+    # bucket minimum as a key
+    # frequency as value
+    def results
+      # error handling case
+      if max == min
+        { min => query.where("#{column} = ?", min).count }
+      else
+        labeled_histogram
+      end
+    end
+
+    def min
+      @min ||= round_to_increment(query.minimum(column), :down)
+    end
+
+    def max
+      @max ||= round_to_increment(query.maximum(column), :up)
+    end
+
+    private
+
+    def num_buckets
+      @buckets ||= ((max - min) / bucket_size).to_i
+    end
+
+    # returns the bucket label (minimum which can be in bucket) based on bucket #
+    def bucket_num_to_label(bucket_num)
+      min + bucket_size * (bucket_num - 1)
+    end
+
+    # rounds to the nearest bucket_size increment
+    # can optionally pass :up or :down to always round in one direction
+    def round_to_increment(num, direction = nil)
+      return 0 if num.nil?
+      round_method = ROUND_METHODS_BY_DIRECTION[direction]
+      denominator = 1 / bucket_size
+      (num * denominator).send(round_method) / denominator.to_f
+    end
+
+    # executes the query and converts bucket numbers to minimum step in bucket
+    def labeled_histogram
+      query_for_buckets.each_with_object({}) do |row, results|
+        results[bucket_num_to_label(row[BUCKET_COL].to_i)] = row[FREQUENCY_COL].to_i \
+          unless row[BUCKET_COL].nil?
+      end
+    end
+
+    def query_for_buckets
+      ActiveRecord::Base.connection.execute(
+        <<-SQL
+          SELECT width_bucket(#{column}, #{min}, #{max}, #{num_buckets}) as #{BUCKET_COL},
+            count(*) as #{FREQUENCY_COL}
+          FROM (#{subquery.to_sql}) as subq_results
+          GROUP BY #{BUCKET_COL}
+          ORDER BY #{BUCKET_COL}
+        SQL
+      )
+    end
+
+    # use passed AR query as a subquery to not interfere with group clause
+    def subquery
+      # override default order
+      query.select(column).order('1')
+    end
+  end
+end

lib/activerecord_pg_histogram/version.rb

@@ -0,0 +1,3 @@
+module PgHistogram
+  VERSION = "0.1"
+end

lib/pg_histogram.rb

@@ -1,11 +1,11 @@
 # coding: utf-8
 lib = File.expand_path('../lib', __FILE__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
-require 'activerecord_pg_histogram/version'
+require 'pg_histogram/version'
 
 Gem::Specification.new do |spec|
-  spec.name          = "activerecord_pg_histogram"
-  spec.version       = ActiverecordPgHistogram::VERSION
+  spec.name          = "pg_histogram"
+  spec.version       = PgHistogram::VERSION
   spec.authors       = ["David Roberts"]
   spec.email         = ["[email protected]"]
   spec.description   = %q{Creates a Histogram fron an ActiveRecord query}
@@ -22,5 +22,4 @@ Gem::Specification.new do |spec|
   spec.add_dependency "pg"
   spec.add_development_dependency "bundler", "~> 1.3"
   spec.add_development_dependency "rake"
-  spec.add_development_dependency "factory_girl"
 end