suggestor 0.0.3

data/.gitignore

@@ -0,0 +1 @@
+.DS_Store

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in suggestor.gemspec
+gemspec

data/README.md

@@ -0,0 +1,64 @@
+# Suggestor 
+## Recommendations gem
+
+Suggestor is a gem that will help you relating data. For example, given a User, Movie and Review class, 
+being the Review related to the User and and Movie and having a rating attribute, the gem would use those 
+information to correlate the information, and give results, like related Movies, Similar Users (based on their
+tastes) and alike. 
+
+## Usage
+
+The gem needs an structure of date like this:
+ 
+    data = {"1": {"10": 10, "12": 1}, "2": {"11":5, "12": 4}}
+
+Each element will ("1" or "2") correspond to, following the example, to user ids. They will gave access to related items (movies). 
+
+In the example, the user "1" has seen movies identified with ids "10" and "12", given them a rating of 10 and 1, respectively. Similar with user with id "2".
+
+After loading the gem with the data: 
+    
+    engine = Suggestor::Engine.new
+    engine.load_data(data)
+
+We can start to get some results. 
+
+
+### Similar items
+
+For example, we can get similar users: 
+
+    engine.similar_items_to("1")
+
+Which will return an structure like
+
+    {id: similarity_score, id2: similarity_score }
+
+Thus, you can load the data and save their similarity scores for later use.
+
+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:
+
+    engine.similar_items_to("1", :algorithm => :pearson_correlation)
+
+There are two implemented methods, Euclidean Distance and Pearson Correlation.
+
+Use Euclidean Distance (default) to compare items and get suggestions base on
+actions that are normalized or not subjective (like user points earned by actions on a web site).
+
+Use Pearson Correlation is there's some bias on the data. The algorithm will
+take in mind if some user grades higher or lower and return more exact suggestions than Euclidean on that area.
+
+### Suggested items
+
+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.recommented_related_items_for("2",:pearson_correlation)
+
+As before, the structure returned will be
+
+    {id: similarity_score, id2: similarity_score }
+
+But in this case, it will represent movie id's, and how similar are. You
+can easily use this data to save it to a BD, since Movie ratings tend to estabilize on time and won't change that often. 

data/Rakefile

@@ -0,0 +1,2 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks

data/demos/playing_around.rb

@@ -0,0 +1,16 @@
+require_relative '../lib/suggestor'
+
+engine = Suggestor::Engine.new
+
+# I'm using test data of Users and their movie recommendations
+# Each user (identified by their ids) have a hash of their movies ids and
+# what they've rate them with
+json = File.read("test/test.json")
+
+engine.load_data(json)
+
+# Let's get some similar users 
+puts engine.similar_items_to("2").inspect
+
+# So, after knowing them, why not having some recommendations? 
+puts engine.recommented_related_items_for("2", algorithm: :euclidean_distance)

data/lib/suggestor.rb

@@ -0,0 +1,3 @@
+require_relative 'suggestor/engine'
+
+

data/lib/suggestor/algorithms/euclidean_distance.rb

@@ -0,0 +1,44 @@
+require_relative 'recommendation_algorithm'
+
+module Suggestor
+  module Algorithms
+
+    # The euclidean distance will compare two structures of 
+    # data, and map them on a chart, each their related element
+    # on each axis. 
+
+    # For example, if we are dealing with user and movies, related
+    # by user reviews of each movie, each couple of shared movie
+    # rating will be used as the axis (LOTR on one, and The Matrix on other)
+
+    # The user ratings will be used to position them on the chart. Thus,
+    # if a user review LOTR as 1 and The Matrix with 5, it will position it 
+    # on [1,5].
+
+    # The closest they are, the more similar their tastes are.
+    # More info at: 
+    #   http://en.wikipedia.org/wiki/Euclidean_metric
+    #   http://en.wikipedia.org/wiki/Distance_correlation
+
+    class EuclideanDistance
+
+      include RecommendationAlgorithm
+
+      def similarity_score_between(first, second)
+        return 0.0 if no_shared_items_between?(first, second)
+        inverse_of_sum_of_squares_between(first, second)
+      end
+
+      def inverse_of_sum_of_squares_between(first, second)
+        1/(1+sum_squares_of_shared_items_between(first, second))
+      end
+
+      def sum_squares_of_shared_items_between(first, second)
+        shared_items_between(first, second).inject(0.0) do |sum, item|
+          sum + (values_for(first)[item] - values_for(second)[item])**2
+        end
+      end
+
+    end
+  end
+end

data/lib/suggestor/algorithms/pearson_correlation.rb

@@ -0,0 +1,105 @@
+require_relative 'recommendation_algorithm'
+
+module Suggestor
+  module Algorithms
+
+    # The Pearson Correlation calculates a coefficient
+    # between two related items from the main element.
+
+    # For example, if we are dealing with user and movies, related
+    # by user reviews of each movie, each couple of users
+    # will be used as the axis ("Alvaro" on one, and "Andres" on other)
+
+    # The user movie ratings will be used to position movies on the chart.  
+    # Thus, if a "Alvaro" reviews LOTR as 1 and "Andres" with 3, 
+    # it will position it on [1,3].
+
+    # A line, "best-fit line", will be traced between all items, showing
+    # the closest distance to all of them. If the two users have the same
+    # ratings, it would show as a perfect diagonal (score of 1)
+
+    # The closest the movies to the line are, the more similar their tastes are.
+
+    # The great thing about using Pearson Correlation is that it works with
+    # bias to valuating the results. Thus, a user that always rates movies
+    # with great scores won't impact and mess up the results.
+
+    # It's probably a best fit for subjetive reviews (movies reviews, profile points, etc).
+    
+    # More info at: http://en.wikipedia.org/wiki/Pearson_product-moment_correlation_coefficient
+
+    class PearsonCorrelation
+
+      include RecommendationAlgorithm
+
+      def similarity_score_between(first, second)
+        return 0.0 if no_shared_items_between?(first, second)
+
+        calculate_all_sums_for(first, second)
+        numerator = difference_from_total_and_normalize_values
+        # 10.5 /    0.0 / 
+        denominator = square_root_from_differences_of_sums
+
+        return 0.0 if denominator == 0
+
+        numerator / denominator
+
+      end
+
+      private
+
+      def calculate_all_sums_for(first,second)
+        
+        shared_items = shared_items_between(first, second)
+        @total_related_items = shared_items.size
+
+        #simplify access
+        first_values = values_for(first)
+        second_values = values_for(second)
+
+        @first_values_sum = @second_values_sum = @first_square_values_sum = \
+        @second_square_values_sum = @products_sum = 0.0
+
+        shared_items.each do |item|
+
+          # Gets the corresponding value for each item on both elements
+          # For ex., the rating of the same movie by different users
+          first_value = first_values[item]
+          second_value = second_values[item]
+
+          # Will add all the related items values  for the first
+          # and second item
+          # For ex., all movie recommendations ratings
+          @first_values_sum += first_value
+          @second_values_sum += second_value
+
+          # Adds the squares of both elements
+          @first_square_values_sum += first_value ** 2
+          @second_square_values_sum += second_value ** 2
+
+          # Adds the product of both values
+          @products_sum += first_value*second_value
+        end
+
+      end
+
+      def difference_from_total_and_normalize_values
+        product = @first_values_sum * @second_values_sum
+        normalized = product / @total_related_items
+        @products_sum - normalized
+      end
+
+      def square_root_from_differences_of_sums
+        
+        power_left_result = @first_values_sum **2 /@total_related_items
+        equation_left = @first_square_values_sum - power_left_result
+
+        power_right_result = ( @second_values_sum **2 )/@total_related_items
+        equation_right = @second_square_values_sum - power_right_result
+        Math.sqrt(equation_left * equation_right)
+
+      end
+
+    end
+  end
+end

data/lib/suggestor/algorithms/recommendation_algorithm.rb

@@ -0,0 +1,108 @@
+module Suggestor
+  module Algorithms    
+    module RecommendationAlgorithm
+
+      attr_accessor :collection
+
+      def initialize(collection)
+        @collection = collection
+      end
+
+      # returns similar items based on their similary score
+      # for example, similar users based on their movies reviews
+      def similar_items_to(main)
+
+        #just compare those whore aren't the main item
+        compare_to = collection.dup
+        compare_to.delete(main)
+
+        # return results based on their score
+        compare_to.keys.inject({}) do |result, other|
+          result.merge!({other => similarity_score_between(main,other)})
+        end
+
+      end
+
+      # returns recommended related items for the main user
+      # The most important feature. For example, a user will get
+      # movie recommendations based on his past movie reviews
+      # and how it compares with others
+      def recommented_related_items_for(main)
+
+        @similarities = @totals = Hash.new(0)
+        @main = main
+
+        create_similarities_totals
+        generate_rankings
+
+      end
+
+      def no_shared_items_between?(first,second)
+        shared_items_between(first,second).empty?
+      end
+
+      def shared_items_between(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
+
+      def main_already_has?(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
+        @similarities[item] += score
+      end
+
+      def generate_rankings
+        @rankings = {}
+
+        @totals.each_pair do |item, total|
+          normalized_value = (total / @similarities[item])
+          @rankings.merge!( { item => normalized_value} )
+        end
+
+        @rankings
+
+      end
+
+      def create_similarities_totals
+        
+        collection.keys.each do |other|
+         
+          # won't bother comparing it if the compared item is the same
+          # as the main, or if they scores are below 0 (nothing in common)
+          next if other == @main
+          score = similarity_score_between(@main,other)
+          next if score <= 0
+
+          # will compare each the results but only for related items
+          # that the main item doesn't already have
+          # For ex., if they have already saw a movie they won't 
+          # get it suggested 
+          collection[other].keys.each do |item|
+
+            unless main_already_has?(item)
+              add_to_totals(other,item,score)            
+            end
+
+          end
+        end
+      end
+
+    end
+  end
+end

data/lib/suggestor/datum.rb

@@ -0,0 +1,13 @@
+require 'delegate'
+
+module Suggestor
+
+  class Datum < DelegateClass(Hash)
+
+    def initialize(hash)
+      super(hash)
+    end
+
+  end
+
+end

data/lib/suggestor/engine.rb

@@ -0,0 +1,63 @@
+require 'json'
+require_relative 'algorithms/euclidean_distance'
+require_relative 'algorithms/pearson_correlation'
+
+module Suggestor
+
+  class WrongInputFormat < Exception; end
+
+  class Engine
+
+    attr_accessor :collection
+
+    def initialize
+      @collection = {}
+    end
+
+    def load_data(input)
+      add_to_collection(input)
+    end
+
+    def similarity_score_for(first, second, opts={})
+      opts[:algorithm] ||= :euclidean_distance 
+      strategy_for(opts[:algorithm]).similarity_score_between(first, second)
+    end
+
+    def similar_items_to(item, opts={})
+      opts[:algorithm] ||= :euclidean_distance 
+      strategy_for(opts[:algorithm]).similar_items_to(item)
+    end
+
+    def recommented_related_items_for(item, opts={})
+      opts[:algorithm] ||= :euclidean_distance 
+      strategy_for(opts[:algorithm]).recommented_related_items_for(item)
+    end
+
+    private
+
+    def strategy_for(algorithm)
+      constantize(classify(algorithm)).new(collection)
+    end
+
+    # based on Rail's code
+    def classify(name)
+      name.to_s.gsub(/\/(.?)/) { "::#{$1.upcase}" }.gsub(/(?:^|_)(.)/) { $1.upcase }  
+    end
+
+    def constantize(name)
+      Suggestor::Algorithms.const_get(name)
+    end
+    
+    def add_to_collection(input)
+      @collection.merge! 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/version.rb

@@ -0,0 +1,3 @@
+module Suggestor
+  VERSION = "0.0.3"
+end

data/suggestor.gemspec

@@ -0,0 +1,21 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "suggestor/version"
+
+Gem::Specification.new do |s|
+  s.name        = "suggestor"
+  s.version     = Suggestor::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["Alvaro Pereyra"]
+  s.email       = ["alvaro@xendacentral.com"]
+  s.homepage    = ""
+  s.summary     = %q{Suggestor allows you to get suggestions of related items in your data}
+  s.description = %q{Suggestor allows you to get suggestions of related items in your data}
+
+  s.rubyforge_project = "suggestor"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = []
+  s.require_paths = ["lib"]
+end

data/test/euclidean_test.rb

@@ -0,0 +1,30 @@
+require 'minitest/autorun'
+require_relative '../lib/suggestor/algorithms/euclidean_distance'
+require_relative '../lib/suggestor/engine'
+
+  describe Suggestor::Algorithms::EuclideanDistance do
+    
+    before do
+      @data_string = File.read("test/test.json")
+      @suggestor = Suggestor::Engine.new
+      @suggestor.load_data(@data_string)
+      @algorithm = Suggestor::Algorithms::EuclideanDistance.new(@suggestor.collection)
+    end
+
+    describe "when building up recommendations" do
+
+      it "must return a list of shared items between two people" do 
+        @algorithm.shared_items_between(1,2).must_be :==, ["1","2"]
+      end
+
+      it "must return 0 as similarity record if two elements hace no shared items" do 
+        @algorithm.similarity_score_between(1,99).must_be :==, 0
+      end
+
+      it "must return 1 as similarity record if two elements have equal related values" do 
+        puts @algorithm.shared_items_between(1,1).inspect
+        @algorithm.similarity_score_between(1,1).must_be :==, 1
+      end
+
+    end
+  end

data/test/pearon_correlation.rb

@@ -0,0 +1,34 @@
+require 'minitest/autorun'
+require_relative '../lib/suggestor/algorithms/pearson_correlation'
+require_relative '../lib/suggestor/engine'
+
+  describe Suggestor::Algorithms::PearsonCorrelation do
+    
+    before do
+      @data_string = File.read("test/test.json")
+      @suggestor = Suggestor::Engine.new
+      @suggestor.load_data(@data_string)
+      @algorithm = Suggestor::Algorithms::PearsonCorrelation.new(@suggestor.collection)
+    end
+
+    describe "when building up recommendations" do
+
+      it "must return a list of shared items between two people" do 
+        @algorithm.shared_items_between(1,2).must_be :==, ["1","2"]
+      end
+
+      it "must return 0 as similarity record if two elements hace no shared items" do 
+        @algorithm.similarity_score_between(1,4).must_be :==, 0
+      end
+
+      it "must return 1 as similarity record if two elements have equal related values" do 
+        @algorithm.similarity_score_between(1,1).must_be :==, 1
+      end
+
+      it "must return -1 as similarity record if two elements are totally distant" do 
+        @algorithm.similarity_score_between(1,99).must_be :==, 0
+      end
+
+
+    end
+  end

data/test/suggestor_test.rb

@@ -0,0 +1,48 @@
+require 'minitest/autorun'
+require_relative '../lib/suggestor'
+
+  describe Suggestor::Engine do
+    before do
+      @suggestor = Suggestor::Engine.new
+      @data_string = File.read("test/test.json")
+    end
+
+    describe "when loading up the data structure" do
+      it "must raise an exception with invalid data" do
+        lambda{ @suggestor.load_data("GIBBERISH}") }.must_raise Suggestor::WrongInputFormat
+      end
+
+      it "must return an array structure if data is ok" do
+        @suggestor.load_data(@data_string).must_be_instance_of Hash
+      end
+
+    end
+
+    describe "when accesing the data after load_dataing it" do
+
+      before do
+        @suggestor.load_data(@data_string)
+      end
+
+      it "must return a similarty score between to elements" do
+        @suggestor.similarity_score_for("1","1").must_be :==, 1
+      end
+
+      it "must return similar items from the base one with euclidean distance" do
+        expected = {"2"=>0.02702702702702703, "3"=>0.02702702702702703}
+        @suggestor.similar_items_to("1").must_be :==, expected
+      end
+
+      it "must return similar items from the base one with pearson correlation" do
+        expected = {"1"=>1.0, "3"=>0.0} 
+        @suggestor.similar_items_to("2",:algorithm => :pearson_correlation).must_be :==, expected
+      end
+
+      it "must return similar items from the base one with euclidean distance" do
+        expected = {"4"=>1.0} 
+        @suggestor.recommented_related_items_for("2").must_be :==, expected
+      end
+
+    end
+
+  end

data/test/test.json

@@ -0,0 +1,20 @@
+{  
+  "1": 
+    {
+      "1" : 10,
+      "2": 3
+    }
+    ,
+  "2": 
+    {
+      "2": 3,
+      "5": 1,
+      "1": 4,
+      "3": 6
+    },
+  "3": 
+    {
+      "1": 4,
+      "4": 6
+    }       
+}

metadata

@@ -0,0 +1,76 @@
+--- !ruby/object:Gem::Specification 
+name: suggestor
+version: !ruby/object:Gem::Version 
+  prerelease: 
+  version: 0.0.3
+platform: ruby
+authors: 
+- Alvaro Pereyra
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-09-19 00:00:00 -05:00
+default_executable: 
+dependencies: []
+
+description: Suggestor allows you to get suggestions of related items in your data
+email: 
+- alvaro@xendacentral.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- Gemfile
+- README.md
+- Rakefile
+- demos/playing_around.rb
+- lib/suggestor.rb
+- lib/suggestor/algorithms/euclidean_distance.rb
+- lib/suggestor/algorithms/pearson_correlation.rb
+- lib/suggestor/algorithms/recommendation_algorithm.rb
+- lib/suggestor/datum.rb
+- lib/suggestor/engine.rb
+- lib/suggestor/version.rb
+- suggestor.gemspec
+- test/euclidean_test.rb
+- test/pearon_correlation.rb
+- test/suggestor_test.rb
+- test/test.json
+has_rdoc: true
+homepage: ""
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+requirements: []
+
+rubyforge_project: suggestor
+rubygems_version: 1.5.0
+signing_key: 
+specification_version: 3
+summary: Suggestor allows you to get suggestions of related items in your data
+test_files: 
+- test/euclidean_test.rb
+- test/pearon_correlation.rb
+- test/suggestor_test.rb
+- test/test.json