suggestor 0.0.6 → 0.0.8

data/README.md

@@ -18,16 +18,19 @@ In the example, the user "Alvaro Pereyra Rabanal" has seen movies "Primer" and "
 
 After loading the gem with the data: 
     
-    engine = Suggestor::Engine.new(data)
+    suggestor = Suggestor::Suggestor.new(data)
 
 We can start to get some results. 
 
+If using Ruby, you can also send Suggestor just a hash object and it'll take it aswell:
+
+    suggestor = Suggestor::Suggestor.new(JSON.parse(data))    
 
 ### Similar items
 
 For example, we can get similar users: 
 
-    engine.similar_to("Alvaro Pereyra Rabanal")
+    suggestor.similar_to("Alvaro Pereyra Rabanal")
 
 Which will return an structure like
 
@@ -41,15 +44,15 @@ Thus, you can load the data and save their similarity scores for later use.
 
 You can limit the data passing a "size" argument:
 
-  engine.similar_to("Alvaro Pereyra Rabanal", :size => 5)
+  suggestor.similar_to("Alvaro Pereyra Rabanal", :size => 5)
 
 Now, that fine and all, but what about Mr. Bob who always is ranking everything
 higher. ID4 maybe is not that good after all. If that happens, Suggestor allows you to change the algorithm used:
 
     algorithm = Suggestor::Algorithms::PearsonCorrelation
-    engine = Suggestor::Engine.new(data, algorithm)
+    suggestor = Suggestor::Suggestor.new(data, algorithm)
 
-    engine.recommended_to("Alvaro Pereyra Rabanal")
+    suggestor.recommended_to("Alvaro Pereyra Rabanal")
 
 There are two implemented methods, Euclidean Distance and Pearson Correlation.
 
@@ -64,7 +67,7 @@ take in mind if some user grades higher or lower and return more exact suggestio
 Most interestingly, the gem allows you to get suggestions base on the data.
 For example, which movies shoud user "2" watch based on his reviews, and similar other users tastes?
 
-    engine.recommended_to("Alvaro Pereyra Rabanal")
+    suggestor.recommended_to("Alvaro Pereyra Rabanal")
 
 As before, the structure returned will be
 
@@ -79,6 +82,21 @@ We can also invert the data that the user has added, enableing us to get
 similar related items. For example, let's say I'm on a Movie profile and
 want to check which other movies are similar to it:
 
-    engine.similar_related_to("Batman Begins ", :size => 5)
+    suggestor.similar_related_to("Batman Begins ", :size => 5)
+
+### Suggested items for a set
+
+Say that you have the list of the movies that you liked the most and you'd like to know what you should watch next. Suggestor has you covered:
+
+	suggestor.items_for_set ['Batman Begins', 'Cyrus']
+	# => [["Kung Fu Hustle", 0.5], ["Super 8 ", 0.5], ["Celda 211 ", 0.5], ... ]
+
+Suggestor of course considers the whole set when recommending new items, so different sets will yield different results, even if they differ in only one item. Say you picked Super 8 from the previous query:
+	suggestor.items_for_set ['Batman Begins', 'Cyrus', 'Super 8 ']
+	# => [["Rapidos y Furiosos 5", 0.3333333333333333], ["Agente Salt", 0.3333333333333333], ["Mary and Max ", 0.3333333333333333], ... ]
+
+But if you had picked Kung Fu Hustle:
+	suggestor.items_for_set ['Batman Begins', 'Cyrus', 'Kung Fu Hustle']
+	# => [["El mensajero ", 0.6666666666666666], ["El Club de la Pelea", 0.3333333333333333], ["Un tonto en el amor", 0.3333333333333333], ... ]
 
 Now you can go and build your awesome recommendations web site :)

data/examples/playing_around.rb

@@ -4,12 +4,12 @@ require_relative '../lib/suggestor'
 # Each user have a hash of their reviews with the movie and
 # what they've rate them with
 json = File.read("test/movies.json")
-engine = Suggestor::Engine.new(json, Suggestor::Algorithms::EuclideanDistance)
+suggestor = Suggestor::Suggestor.new(json)
 
 # Let's get some similar users 
 name = "Alvaro Pereyra Rabanal"
 puts "Who is similar to #{name}"
-puts engine.similar_to(name, size: 5).inspect
+puts suggestor.similar_to(name, size: 5).inspect
 
 puts
 puts
@@ -17,7 +17,7 @@ puts
 # So, after knowing them, why not having some recommendations? 
 puts "Interesting! But I want to see some stuff at the movies, what to watch?"
 opts = {size: 5}
-results = engine.recommended_to("Alvaro Pereyra Rabanal", opts)
+results = suggestor.recommended_to("Alvaro Pereyra Rabanal", opts)
 
 puts results.inspect
 
@@ -26,17 +26,29 @@ puts
 
 # That's good, but let's take in mind bias while using Pearson Correlation:
 puts "Adjust this results please"
-engine = Suggestor::Engine.new(json,Suggestor::Algorithms::PearsonCorrelation)
+suggestor = Suggestor::Suggestor.new(json,Suggestor::Algorithms::PearsonCorrelation)
 
 ops = {size: 5}
-results = engine.recommended_to("Alvaro Pereyra Rabanal", opts)
+results = suggestor.recommended_to("Alvaro Pereyra Rabanal", opts)
 puts results.inspect
 
 puts
 puts
 
+puts "Adjust this results please"
+suggestor = Suggestor::Suggestor.new(json)
+
 name = "Batman Begins "
 puts "Now that was nice. But which others are similar to '#{name}'"
 ops = {size: 10}
-results = engine.similar_related_to(name, opts)
+results = suggestor.similar_related_to(name, opts)
+puts results.inspect
+
+puts
+puts
+
+set = ['Batman Begins', 'Cyrus']
+puts "Great! One more thing: if I've watched all these movies: #{set.inspect},
+which should I watch next?"
+results = suggestor.items_for_set set
 puts results.inspect

data/lib/suggestor.rb

@@ -1,5 +1,47 @@
-require_relative 'suggestor/engine'
+require_relative 'suggestor/algorithms/records'
 require_relative 'suggestor/algorithms/recommendation_algorithm'
 require_relative 'suggestor/algorithms/euclidean_distance'
 require_relative 'suggestor/algorithms/pearson_correlation'
 
+require 'json'
+module Suggestor
+  class WrongInputFormat < Exception; end
+  
+  class Suggestor
+
+    def initialize(input, algorithm = Algorithms::EuclideanDistance)
+      collection = load_from(input)
+      @algorithm  = algorithm.new(collection)
+    end
+
+    def similar_to(item, opts={})
+      @algorithm.similar_to(item, opts)
+    end
+
+    def recommended_to(item, opts={})
+      @algorithm.recommended_to(item, opts)
+    end
+
+    def similar_related_to(item, opts={})
+      @algorithm.similar_related_to(item, opts)
+    end
+
+    def items_for_set(set, opts={})
+      @algorithm.items_for_set(set, opts)
+    end
+
+    private
+
+    def load_from(input)
+      return input if input.is_a? Hash
+      parse_from_json(input)
+    end
+
+    def parse_from_json(json)
+      JSON.parse(json)
+    rescue Exception => ex
+      raise WrongInputFormat, "Wrong Data format: #{ex.message}" 
+    end
+
+  end
+end

data/lib/suggestor/algorithms/euclidean_distance.rb

@@ -23,18 +23,8 @@ module Suggestor
       include RecommendationAlgorithm
 
       def similarity_score(first, second)
-        return 0.0 if nothing_shared?(first, second)
-        inverse_of_squares(first, second)
-      end
-
-      def inverse_of_squares(first, second)
-        1/(1+Math.sqrt(sum_squares(first, second)))
-      end
-
-      def sum_squares(first, second)
-        shared_items(first, second).inject(0.0) do |sum, item|
-          sum + ( values_for(first)[item] - values_for(second)[item] ) ** 2
-        end
+        return 0.0 if @collection.nothing_shared?(first, second)
+        @collection.inverse_of_squares(first, second)
       end
 
     end

data/lib/suggestor/algorithms/pearson_correlation.rb

@@ -34,11 +34,12 @@ module Suggestor
       include RecommendationAlgorithm
 
       def similarity_score(first, second)
-        return -1.0 if nothing_shared?(first, second)
+        return -1.0 if @collection.nothing_shared?(first, second)
 
         process_values(first, second)
 
         numerator   = difference_from_values
+
         denominator = square_root_from_differences
 
         return 0.0 if denominator == 0
@@ -48,11 +49,11 @@ module Suggestor
       private
 
       def process_values(first, second)
-        items                = shared_items(first, second)
+        items                = @collection.shared_items(first, second)
         @total_related_items = items.size.to_f
 
-        first_values  = values_for(first)
-        second_values = values_for(second)
+        first_values  = @collection.values_for(first)
+        second_values = @collection.values_for(second)
 
         create_helper_variables
 

data/lib/suggestor/algorithms/recommendation_algorithm.rb

@@ -5,15 +5,16 @@ module Suggestor
       attr_accessor :collection
 
       def initialize(collection)
-        @collection = collection
+        @collection = Records.new(collection)
       end
 
       # Ex. Similar users based on their movies reviews
       def similar_to(main, opts={})
         opts.merge!(default_options)
- 
-        collection = remove_self(main)
-        results    = order_by_similarity_score(main,collection)
+        
+        cleaned = @collection.remove(main)
+
+        results = order_by_similarity_score(main, cleaned)
 
         sort_results(results,opts[:size])
       end
@@ -25,6 +26,7 @@ module Suggestor
         @similarities = @totals = Hash.new(0)
 
         create_similarities_totals(main)
+
         results = generate_rankings
 
         sort_results(results,opts[:size])
@@ -34,72 +36,43 @@ module Suggestor
       def similar_related_to(main, opts={})
         opts.merge!(default_options)
 
-        collection = invert_collection
-        engine     = self.class.new(collection)
+        inverted_collection = @collection.invert
+        suggestor     = self.class.new(inverted_collection)
         
-        engine.similar_to(main,opts)
+        suggestor.similar_to(main,opts)
       end
 
-      def shared_items(first, second)
-        return [] unless values_for(first) && values_for(second)        
-         
-        related_keys_for(first).select do |item| 
-          related_keys_for(second).include? item
-        end
-      end           
-
-     private
+      # Takes a set and returns suggestions based on the weighted average of
+      # the similarities to all of the items in it.
+      def items_for_set(set, opts={})
+        opts.merge!(default_options)
 
-      def default_options
-        {size: 5}
-      end
+        suggestions = Hash.new(0.0)
 
-      def nothing_shared?(first, second)
-        shared_items(first, second).empty?
-      end
+        set.each do |item|
+          related = similar_related_to(item, opts)
+          related.each { |rel| suggestions[rel[0]] += rel[1] unless
+            set.include? rel[0] }
+        end
 
-      def remove_self(main)
-        cleaned = collection.dup
-        cleaned.delete(main)
-        cleaned
+        suggestions = suggestions.map { |label, score| [label, score / set.length] }
+        suggestions.sort_by { |sug| sug[1] }.reverse
       end
 
+     private
 
-      # changes { "Cat": {"1": 10, "2":20}, "Dog": {"1":5, "2": 15} }
-      # to {"1": {"Cat": 10, "Dog": 5}, "2": {"Cat": 20, "Dog": 15}
-      def invert_collection
-        results = {}
-
-        collection.keys.each do |main|
-          collection[main].keys.each do |item|
-            results[item] ||= {}
-            results[item][main] = collection[main][item]
-          end
-        end
-
-        results
+      def default_options
+        {size: 5}
       end
 
-      def order_by_similarity_score(main,collection)
+      def order_by_similarity_score(main, collection)
         result = collection.keys.inject({}) do |res, other|
           res.merge!({other => similarity_score(main, other)})
         end
       end
-
-      def already_has?(main, related)
-        collection[main].has_key?(related)
-      end
       
-      def values_for(id)
-        collection[id.to_s]
-      end
-
-      def related_keys_for(id)
-        values_for(id).keys
-      end
- 
       def add_to_totals(other, item, score)
-        @totals[item]       += collection[other][item]*score
+        @totals[item]       += @collection[other][item] * score
         @similarities[item] += score
       end
 
@@ -123,23 +96,19 @@ module Suggestor
         score > 0
       end
 
-      def same_item?(main, other)
-        other == main
-      end
-
       def create_similarities_totals(main)
         
-        collection.keys.each do |other|
+        @collection.keys.each do |other|
          
-          next if same_item?(main,other)
+          next if other == main
 
           score = similarity_score(main, other)
 
           next unless something_in_common?(score)
 
-          collection[other].keys.each do |item|
+          @collection[other].keys.each do |item|
 
-            unless already_has?(main, item)
+            unless @collection.already_has?(main, item)
               add_to_totals(other, item, score)            
             end
 
@@ -152,4 +121,4 @@ module Suggestor
 
     end
   end
-end
+end

data/lib/suggestor/algorithms/records.rb

@@ -0,0 +1,76 @@
+require 'delegate'
+
+module Suggestor
+  module Algorithms
+    class Records < DelegateClass(Hash)
+      
+      def initialize(hash)
+        super(hash)
+      end
+
+      def dup
+        Marshal.load(Marshal.dump(self))
+      end
+
+      def remove(item)
+        cleaned = self.dup
+        cleaned.delete(item)
+        cleaned
+      end
+
+      def common_items(first, other)
+        values_for(first) && values_for(other)
+      end
+
+      def already_has?(main, related)
+        self[main].has_key?(related)
+      end
+      
+      def values_for(id)
+        self[id.to_s]
+      end
+
+      def related_keys_for(id)
+        values_for(id).keys
+      end
+
+      def shared_items(first, other)
+        return [] unless common_items(first, other)
+         
+        related_keys_for(first).select do |item| 
+          related_keys_for(other).include? item
+        end
+      end           
+
+      def nothing_shared?(first, second)
+        shared_items(first, second).empty?
+      end
+
+      def inverse_of_squares(first, second)
+        1/(1+Math.sqrt(sum_squares(first, second)))
+      end
+
+      def sum_squares(first, second)
+        shared_items(first, second).inject(0.0) do |sum, item|
+          sum + ( values_for(first)[item] - values_for(second)[item] ) ** 2
+        end
+      end
+   
+      # changes { "Cat": {"1": 10, "2":20}, "Dog": {"1":5, "2": 15} }
+      # to {"1": {"Cat": 10, "Dog": 5}, "2": {"Cat": 20, "Dog": 15}
+      def invert
+        results = {}
+
+        self.keys.each do |main|
+          self[main].keys.each do |item|
+            results[item] ||= {}
+            results[item][main] = self[main][item]
+          end
+        end
+
+        results
+      end
+
+    end
+  end
+end

data/lib/suggestor/version.rb

@@ -1,3 +1,3 @@
 module Suggestor
-  VERSION = "0.0.6"
+  VERSION = "0.0.8"
 end

data/test/suggestor_test.rb

@@ -1,21 +1,37 @@
 require 'minitest/autorun'
 require_relative '../lib/suggestor'
 
-  describe Suggestor::Engine do
+  describe Suggestor::Suggestor do
     before do
       @data_string = File.read("test/numbers.json")
     end
 
     describe "when loading up the data structure" do
       it "must raise an exception with invalid data" do
-        lambda{ Suggestor::Engine.new("GIBBERISH") }.must_raise Suggestor::WrongInputFormat
+        lambda{ Suggestor::Suggestor.new("GIBBERISH") }.must_raise Suggestor::WrongInputFormat
       end
     end
 
+    describe "when using a hash object for loading" do
+
+      before do
+        @data_string = File.read("test/numbers.json")
+        @data = JSON.parse(@data_string)
+        @suggestor = Suggestor::Suggestor.new(@data)
+      end
+
+      it "must return similar items from the base one with euclidean distance" do
+        expected = [["3", 0.14285714285714285], ["2", 0.14285714285714285]]
+        @suggestor.similar_to("1").must_be :==, expected
+      end
+      
+
+    end
+
     describe "when accesing the data after load_dataing it" do
 
       before do
-        @suggestor = Suggestor::Engine.new(@data_string)
+        @suggestor = Suggestor::Suggestor.new(@data_string)
       end
 
       it "must return similar items from the base one with euclidean distance" do
@@ -24,7 +40,7 @@ require_relative '../lib/suggestor'
       end
 
       it "must return similar items from the base one with pearson correlation" do
-        @suggestor = Suggestor::Engine.new(@data_string,Suggestor::Algorithms::PearsonCorrelation)
+        @suggestor = Suggestor::Suggestor.new(@data_string,Suggestor::Algorithms::PearsonCorrelation)
         expected = [["2", 0.0], ["1", 0.0]]
         @suggestor.similar_to("3").must_be :==, expected
       end
@@ -39,5 +55,10 @@ require_relative '../lib/suggestor'
         @suggestor.similar_related_to("2").must_be :==, expected
       end
 
+      it "must return items that might follow a sequence" do
+        expected = [["5", 0.29166666666666663], ["3", 0.29166666666666663], ["4", 0.16666666666666666]]
+        @suggestor.items_for_set(['1', '2']).must_be :==, expected
+      end
+
     end
-  end
+  end

metadata

@@ -1,38 +1,39 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: suggestor
-version: !ruby/object:Gem::Version 
+version: !ruby/object:Gem::Version
+  version: 0.0.8
   prerelease: 
-  version: 0.0.6
 platform: ruby
-authors: 
+authors:
 - Alvaro Pereyra
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2011-09-24 00:00:00 Z
-dependencies: 
-- !ruby/object:Gem::Dependency 
+date: 2014-04-01 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
   name: rake
-  prerelease: false
-  requirement: &id001 !ruby/object:Gem::Requirement 
+  requirement: !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        version: "0"
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :runtime
-  version_requirements: *id001
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Suggestor allows you to get suggestions of related items in your data
-email: 
+email:
 - alvaro@xendacentral.com
 executables: []
-
 extensions: []
-
 extra_rdoc_files: []
-
-files: 
+files:
 - .gitignore
 - Gemfile
 - README.md
@@ -42,7 +43,7 @@ files:
 - lib/suggestor/algorithms/euclidean_distance.rb
 - lib/suggestor/algorithms/pearson_correlation.rb
 - lib/suggestor/algorithms/recommendation_algorithm.rb
-- lib/suggestor/engine.rb
+- lib/suggestor/algorithms/records.rb
 - lib/suggestor/version.rb
 - suggestor.gemspec
 - test/euclidean_test.rb
@@ -50,34 +51,31 @@ files:
 - test/numbers.json
 - test/pearson_correlation.rb
 - test/suggestor_test.rb
-homepage: ""
+homepage: ''
 licenses: []
-
 post_install_message: 
 rdoc_options: []
-
-require_paths: 
+require_paths:
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement 
+required_ruby_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      version: "0"
-required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      version: "0"
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
 requirements: []
-
 rubyforge_project: suggestor
-rubygems_version: 1.8.10
+rubygems_version: 1.8.23.2
 signing_key: 
 specification_version: 3
 summary: Suggestor allows you to get suggestions of related items in your data
-test_files: 
+test_files:
 - test/euclidean_test.rb
 - test/movies.json
 - test/numbers.json

data/lib/suggestor/engine.rb

@@ -1,36 +0,0 @@
-require 'json'
-
-module Suggestor
-
-  class WrongInputFormat < Exception; end
-
-  class Engine
-
-    def initialize(input, algorithm = Algorithms::EuclideanDistance)
-      @collection = parse_from_json(input)
-      @algorithm  = algorithm.new(@collection)
-    end
-    
-    def similar_to(item, opts={})
-      @algorithm.similar_to(item, opts)
-    end
-
-    def recommended_to(item, opts={})
-      @algorithm.recommended_to(item, opts)
-    end
-
-    def similar_related_to(item, opts={})
-      @algorithm.similar_related_to(item, opts)
-    end
-
-    private
-    
-    def parse_from_json(json)
-      JSON.parse(json)
-    rescue Exception => ex
-      raise WrongInputFormat, "Wrong Data format: #{ex.message}" 
-    end
-
-  end
-
-end