acts_as_recommendable 0.0.2

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    NTViNzc1YWExZjJkZTY4YTIxYzRlMGM5YmU2ZjEwMGNmNDI2ZGM4OQ==
+  data.tar.gz: !binary |-
+    MmIwNzJhMGIxYzNkN2Q1ZGU3YjJkMzIxNDc3OTdlYmI1OGE5YmVjYQ==
+SHA512:
+  metadata.gz: !binary |-
+    MDc3NmE1Mzk5OWQ0ZmRhYTJiNzViOTg4ZTc1NTY2NTY3ZTE3MjRkM2I4ODFh
+    NDEwMWU5ZDIzMWVhNzIzZTUwYWFiODY5YzI5OWUzOTM3OTY0NGY5OWMwYjNl
+    MzY4M2YwMGRkZDUzMzk3OTJmZTUwZjZlYWI0ODI0NTQ2YWU4NzE=
+  data.tar.gz: !binary |-
+    ZTE2YTY2MTRiMGNjYWJjOWE2ZDY2OTc5YWRkMTQ1ZjIzMDEwMjgwMGM4NjI4
+    MThhZmU5ZTQ0ZWVjOTQ2NGQwYmU2NmM4MDQxNWQ1YWMyNmZjMDFjNzU0NjUy
+    ZGU4MDRlNjA2MzBlMTMwMjAyNWMzNDY1Y2JjZTFhMmE2ZDQ1YWE=

data/Gemfile

@@ -0,0 +1,3 @@
+source "https://rubygems.org"
+
+gemspec

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2008 Made by Many Ltd
+
+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.

data/README

@@ -0,0 +1,123 @@
+ActsAsRecommendable
+===================
+
+ActsAsRecommendable is a plugin for Rails that simplifies collaborative filtering
+
+The plugin provides a mechanism for finding loose associations between users and items which we can tell you
+* Given a user, return other similar users based on what items they have all bought/bookmarked/rated/etc
+* Given a user, return recommended items based on the items bought/bookmarked/rated/etc by that user and the items bought/bookmarked/rated/etc by other users.
+
+The plugin calculations can be made online and offline and stored using the rails cache (such as memcache) for online retrieval. Online retrieval of recommendations uses item-based collaborative filtering using the offline items similarity matrix stored in the cache. This can give up-to-date results with a much lower processing overhead.
+
+Much thanks to Toby Segaran and his excellent book Programming Collective Intelligence (http://oreilly.com/catalog/9780596529321/).
+
+Features
+========
+
+Use join rating scores
+Using abitary calculated scores
+Similar Items
+Recommended Users
+Cached dataset
+
+Current Release
+===============
+
+v0.1 should be considered early alpha and not ready for production applications.
+
+Lots of performance optimisations still to be done.
+
+Example
+=======
+
+class Book < ActiveRecord::Base
+  has_many :user_books
+  has_many :users, :through => :user_books
+end
+
+class UserBook < ActiveRecord::Base
+  belongs_to :book
+  belongs_to :user
+end
+
+class User < ActiveRecord::Base
+  has_many :user_books
+  has_many :books, :through => :user_books
+  acts_as_recommendable :books, :through => :user_books
+end
+
+user = User.find(:first)
+user.similar_users #=> [...]
+user.recommended_books #=> [...]
+
+book = Book.find(:first)
+book.similar_books #=> [...]
+
+Example 2
+=========
+
+class Movie < ActiveRecord::Base
+  has_many :user_movies
+  has_many :users, :through => :user_movies
+end
+
+class UserMovie < ActiveRecord::Base
+  belongs_to :movie
+  belongs_to :user
+end
+
+class User < ActiveRecord::Base
+  has_many :user_movies
+  has_many :movies, :through => :user_movies
+  acts_as_recommendable :movies, :through => :user_movies, :score => :score
+  # 'score' is an attribute on the users_movies table
+end
+
+user = User.find(:first)
+user.similar_users #=> [...]
+user.recommended_movies #=> [...]
+
+Example 3
+=========
+
+class Book < ActiveRecord::Base
+  has_many :user_books
+  has_many :users, :through => :user_books, :use_dataset => true
+  # Uses cached dataset
+end
+
+class UserBook < ActiveRecord::Base
+  belongs_to :book
+  belongs_to :user
+end
+
+class User < ActiveRecord::Base
+  has_many :user_books
+  has_many :books, :through => :user_books
+  acts_as_recommendable :books, :through => :user_books
+end
+
+user = User.find(:first)
+user.recommended_books #=> [...]
+
+# The example above uses a cached dataset.
+# You need to generate a cached dataset every so often (depending on how much your content changes)
+# You can do that by calling the rake task recommendations:build, you should run this with a cron job every so often.
+
+  
+# If you only want to use the dataset in production put this in production.rb:
+  User.aar_options[:use_dataset] = true
+  
+# Note:
+# user.similar_users doesn't use the dataset
+#
+# The advantage of using a dataset is that you don't need to load all the users & items into
+# memory (which you do normally). The disadvantage is that you won't get as accurate results.
+#
+
+Contact
+=======
+alex@madebymany.co.uk
+
+
+Copyright (c) 2008 Made by Many Ltd, released under the MIT license

data/Rakefile

@@ -0,0 +1,17 @@
+require 'rake'
+require 'rake/testtask'
+require 'rubygems'
+require 'bundler'
+require 'bundler/gem_tasks'
+
+Bundler::GemHelper.install_tasks
+
+desc 'Default: run unit tests.'
+task :default => :test
+
+desc 'Test the acts_as_recommended plugin.'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+end

data/acts_as_recommendable.gemspec

@@ -0,0 +1,29 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+
+Gem::Specification.new do |s|
+  s.name        = "acts_as_recommendable"
+  s.version     = '0.0.2'
+  s.authors     = ["macman"]
+  s.email       = %q{info@eribium.org}
+  s.homepage    = %q{https://github.com/maccman/acts_as_recommendable}
+  s.summary     = %q{Recommendation engine for Rails}
+  s.description = %q{A recommendation engine for Rails.}
+  s.license     = "MIT"
+
+  s.required_ruby_version = '~> 1.9.3'
+
+  s.add_dependency             'ruby-progressbar', '~> 0'
+  s.add_dependency             'RubyInline', '~> 3.12', '>= 3.12.3'
+  s.add_runtime_dependency     'rails', '~> 3.2', '>= 3.2.0'
+  s.add_development_dependency 'rake', '~> 0'
+  s.add_development_dependency 'sdoc', '~> 0'
+  s.add_development_dependency 'minitest', '~> 0'
+  s.add_development_dependency 'sqlite3', '~> 0'
+  s.add_development_dependency 'ruby-debug-completion', '~> 0'
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+end

data/init.rb

@@ -0,0 +1,14 @@
+# Include hook code here
+require File.dirname(__FILE__) + '/lib/acts_as_recommendable'
+require File.dirname(__FILE__) + '/lib/cache_fix'
+
+# Fix RubyInline's permission problem,
+# RubyInline doesn't like directories with
+# group write permissions (like /tmp).                            
+
+
+ENV['INLINEDIR'] = File.join(Rails.respond_to?(:root) && !Rails.root.nil? ? Rails.root : RAILS_ROOT, 'tmp', 'rubyinline')
+begin
+  require 'inline'
+  require File.dirname(__FILE__) + '/lib/optimizations'
+rescue LoadError; end

data/lib/acts_as_recommendable.rb

@@ -0,0 +1,365 @@
+require File.dirname(__FILE__) + '/cache_fix'
+require File.dirname(__FILE__) + '/optimizations'
+
+# ActsAsRecommended
+module MadeByMany
+  module ActsAsRecommendable
+    def self.included(base)
+      base.extend(ActsMethods)
+    end
+      
+    module ActsMethods
+      # Send an array to ActiveRecord without fear that some elements don't exist.
+      def find_some_without_failing(ids)
+        return self.where("1 = 0") if !ids or ids.empty?
+
+        ids_list   = ids.map { |id| quote_value(id,columns_hash[primary_key]) }
+        where(table_name.to_sym => {primary_key.to_sym => ids_list})
+      end
+      
+      def acts_as_recommendable(on, options = {})
+        defaults = {
+          :algorithm      => :sim_pearson,
+          :use_dataset    => false,
+          :split_dataset  => true,
+          :limit          => 10,
+          :min_score      => 0.0
+        }
+        
+        options = defaults.merge(options)
+
+        # reflect on the specified association to derive the extra details we need
+        options[:on]          =   on
+        assoc = self.reflections[on.to_sym]
+        through_assoc = assoc.through_reflection
+        options[:through] = through_assoc.name
+        raise "No association specified to recommend." if assoc.nil?
+        raise "The #{on} association does not have a :through association" unless through_assoc
+        
+        on_class_name         =   assoc.class_name
+        options[:on_singular] ||= on_class_name.underscore
+        options[:on_class]    ||= assoc.klass
+        
+        options[:class] = self
+        
+        options[:through_singular]  ||= through_assoc.class_name.downcase
+        options[:through_class]     ||= through_assoc.klass
+        
+        class_attribute :aar_options
+        self.aar_options = options
+        
+        options[:on_class].class_eval do
+          define_method "similar_#{options[:on]}" do
+            Logic.similar_items(self, options)
+          end
+        end
+
+        define_method "similar_#{options[:class].name.underscore.pluralize}" do
+          Logic.similar_users(self, options)
+        end
+          
+        define_method "recommended_#{options[:on_class].name.underscore.pluralize}" do
+          if self.aar_options[:use_dataset]
+            Logic.dataset_recommended(self, options)
+          else
+            Logic.recommended(self, options)
+          end
+        end
+        
+        define_method "aar_items_with_scores" do
+          @aar_items_with_scores ||= begin
+            self.__send__(self.aar_options[:through]).collect {|ui|
+              item = ui.__send__(self.aar_options[:on_singular])
+              next unless item
+              if self.aar_options[:score]
+                score = ui.__send__(self.aar_options[:score]).to_f
+                score = 1.0 if !score or score <= 0
+              else
+                score = 1.0
+              end
+              def item.aar_score; @aar_score; end
+              def item.aar_score=(d); @aar_score = d; end
+              item.aar_score = score
+              item
+            }.compact.inject({}) {|h, item| h[item.id] = item; h }
+          end
+        end
+                
+      end
+    end
+      
+    module Logic
+      
+      def self.matrix(options)
+        items = options[:on_class].pluck(:id)
+        prefs = {}
+        users = options[:class].includes(options[:on])
+        users.each do |user|
+          prefs[user.id] ||= {}
+          items.each do |item_id|
+            if user.aar_items_with_scores[item_id]
+              score = user.aar_items_with_scores[item_id].aar_score
+              prefs[user.id][item_id] = score
+            end
+          end
+        end
+        [items, prefs]
+      end
+      
+      def self.inverted_matrix(options)
+        items = options[:on_class].pluck(:id)
+        prefs = {}
+        users = options[:class].includes(options[:on])
+        items.each do |item_id|
+          prefs[item_id] ||= {}
+          users.each do |user|
+            if user.aar_items_with_scores[item_id]
+              score = user.aar_items_with_scores[item_id].aar_score
+              prefs[item_id][user.id] = score
+            end
+          end
+        end
+        [users.collect(&:id), prefs]
+      end
+    
+      # Euclidean distance 
+      def self.sim_distance(prefs, items, person1, person2)
+        return 0 if items.length == 0
+
+        squares = []
+        
+        items.each do |item|
+          squares << ((prefs[person1][item] || 0.0) - (prefs[person2][item] || 0.0)) ** 2
+        end
+        
+        sum_of_squares = squares.inject { |sum,value| sum += value }
+        return 1/(1 + sum_of_squares)
+      end
+    
+      # Pearson score
+      def self.sim_pearson(prefs, items, person1, person2)
+        n = items.length
+        return 0 if n == 0
+
+        sum1 = sum2 = sum1Sq = sum2Sq = pSum = 0.0
+        
+        items.each do |item|
+          prefs1_item = prefs[person1][item] || 0.0
+          prefs2_item = prefs[person2][item] || 0.0
+          sum1   += prefs1_item
+          sum2   += prefs2_item
+          sum1Sq += prefs1_item ** 2
+          sum2Sq += prefs2_item ** 2
+          pSum   += prefs2_item * prefs1_item
+        end
+
+        num = pSum - ( ( sum1 * sum2 ) / n )
+        den = Math.sqrt( ( sum1Sq - ( sum1 ** 2 ) / n ) * ( sum2Sq - ( sum2 ** 2 ) / n ) )
+        
+        return 0 if den == 0
+
+        num / den
+      end
+      
+      def self.similar_users(user, options)
+        rankings = []
+        items, prefs = self.matrix(options)
+        prefs.each do |u, _|
+          next if u == user.id
+          rankings << [self.__send__(options[:algorithm], prefs, items, user.id, u), u]
+        end
+        
+        rankings = rankings.select {|score, _| score > options[:min_score] }
+        rankings = rankings.sort_by {|score, _| score }.reverse
+        rankings = rankings[0..(options[:limit] - 1)]
+        
+        # Return the sorted list
+        ranking_ids = rankings.collect {|_, u| u }
+        ar_users = options[:class].find_some_without_failing(ranking_ids)
+        ar_users = ar_users.inject({}){ |h, user| h[user.id] = user; h }
+        
+        rankings.collect {|score, user_id|
+          user = ar_users[user_id]
+          def user.similar_score; return @similar_score; end
+          def user.similar_score=(d); @similar_score = d; end
+          user.similar_score = score
+          user
+        }
+      end
+      
+      def self.similar_items(item, options)
+        if options[:use_dataset]
+          if options[:split_dataset]
+            rankings = Rails.cache.read("aar_#{options[:on]}_#{item.id}")
+          else
+            cached_dataset = Rails.cache.read("aar_#{options[:on]}_dataset")
+            logger.warn 'ActsRecommendable has an empty dataset - rebuild it' unless cached_dataset
+            rankings = cached_dataset && cached_dataset[item.id]
+          end      
+        else
+          users, prefs = self.inverted_matrix(options)
+          rankings = []
+          prefs.each do |i, _|
+            next if i == item.id
+            rankings << [self.__send__(options[:algorithm], prefs, users, item.id, i), i]
+          end
+        end
+        return [] unless rankings
+        
+        rankings = rankings.select {|score, _| score > options[:min_score] }
+        rankings = rankings.sort_by {|score, _| score }.reverse
+        rankings = rankings[0..(options[:limit] - 1)]
+        
+        # Return the sorted list
+        ranking_ids = rankings.collect {|_, u| u }
+        ar_items = options[:on_class].find_some_without_failing(ranking_ids)
+        ar_items = ar_items.inject({}){ |h, item| h[item.id] = item; h }
+        
+        rankings.collect {|score, item_id|
+          item = ar_items[item_id]
+          def item.similar_score; return @similar_score; end
+          def item.similar_score=(d); @similar_score = d; end
+          item.similar_score = score
+          item
+        }
+      end
+        
+      def self.recommended(user, options)
+        totals        = {}
+        sim_sums      = {}
+        items, prefs  = self.matrix(options)
+        user          = user.id
+        user_ratings  = prefs[user]
+  
+        prefs.keys.each do |other|
+          # don't compare me to myself
+          next if other == user
+
+          sim = self.__send__(options[:algorithm], prefs, items, user, other)
+
+          # ignore scores of zero or lower
+          next if sim <= 0
+
+          prefs[other].keys.each do |item|
+            if !prefs[user].include? item or prefs[user][item] == 0
+              # similarity * score
+              totals.default = 0
+              totals[item] += prefs[other][item] * sim
+              # sum of similarities
+              sim_sums.default = 0
+              sim_sums[item] += sim
+            end
+          end
+        end
+
+        # Create a normalized list
+        rankings = []
+        items = []
+        totals.each do |item,total|
+          rankings << [total/sim_sums[item], item]
+        end
+        
+        # Return the sorted list
+        rankings = rankings.select {|score, _| score > options[:min_score] }
+        rankings = rankings.sort_by {|score, _| score }.reverse
+        rankings = rankings[0..(options[:limit] - 1)]
+        
+        # So we can do everything in one SQL query
+        ranking_ids = rankings.collect {|_, i| i }
+        ar_items = options[:on_class].find_some_without_failing(ranking_ids)
+        ar_items = ar_items.inject({}){ |h, item| h[item.id] = item; h }
+        
+        rankings.collect {|score, item_id|
+          item = ar_items[item_id]
+          def item.recommendation_score; return @recommendation_score; end
+          def item.recommendation_score=(d); @recommendation_score = d; end
+          item.recommendation_score = score
+          item
+        }
+      end
+      
+      def self.generate_dataset(options, matrix = nil)
+        users, prefs = matrix || self.inverted_matrix(options)
+        for item in prefs.keys
+          scores = []
+          for other in prefs.keys
+            next if other == item
+            scores << [self.__send__(options[:algorithm], prefs, users, item, other), other]
+          end
+          scores = scores.sort_by {|score, _| score }.reverse
+          yield(item, scores) if block_given?
+        end
+      end
+      
+      def self.dataset_recommended(user, options)
+        scores    = {}
+        total_sim = {}
+        items     = user.aar_items_with_scores
+        item_ids  = items.values.collect(&:id)
+        unless options[:split_dataset]
+          cached_dataset = Rails.cache.read("aar_#{options[:on]}_dataset")
+          logger.warn 'ActsRecommendable has an empty dataset - rebuild it' unless cached_dataset
+        end
+        
+        item_ids.each do |item_id|
+          if options[:split_dataset] 
+            ratings = Rails.cache.read("aar_#{options[:on]}_#{item_id}")
+          else
+            ratings = cached_dataset && cached_dataset[item_id]
+          end
+          next unless ratings
+          
+          ratings.each do |similarity, item2_id|
+            # Ignore if this user has already rated this item
+            next if item_ids.include?(item2_id)
+            
+            scores[item2_id]    ||= 0
+            total_sim[item2_id] ||= 0
+            if options[:score]
+              # Weighted sum of rating times similarity
+              scores[item2_id]    += similarity * items[item_id].aar_score
+
+              # Sum of all the similarities
+              total_sim[item2_id] += similarity
+            else
+              scores[item2_id]    += similarity 
+              total_sim[item2_id] += 1.0
+            end
+          end
+        end
+        
+        # Divide each total score by total weighting to get an average
+        rankings = []
+        scores.each do |item, score|
+          next unless score > 0.0
+          rankings << [score/total_sim[item], item]
+        end
+        
+        rankings = rankings.select {|score, _| score > options[:min_score] }
+        rankings = rankings.sort_by {|score, _| score }.reverse
+        rankings = rankings[0..(options[:limit] - 1)]
+        
+        # So we can do everything in one SQL query
+        ranking_ids = rankings.collect {|_, i| i }
+        ar_items = options[:on_class].find_some_without_failing(ranking_ids)
+        ar_items = ar_items.inject({}){ |h, item| h[item.id] = item; h }
+
+        rankings.collect {|score, item_id|
+          item = ar_items[item_id]
+          def item.recommendation_score; @recommendation_score; end
+          def item.recommendation_score=(d); @recommendation_score = d; end
+          item.recommendation_score = score
+          item
+        }
+      end
+      
+      def self.logger
+        RAILS_DEFAULT_LOGGER
+      end
+    
+    end
+
+  end
+end
+
+require 'railtie'