recommengine 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 3576a6e695494260a695452d8da638d6a37e4774
+  data.tar.gz: ed27b1734ddbef8e9504cc2c8cbd64dba6409fd7
+SHA512:
+  metadata.gz: 7b80f257d9f4931371e3c2130a606a323557d0acd0e570f43bb1585b29534dcf8691629d00a98abe148b6518419569d89644aa022af2fd93d6a34e94b748de6a
+  data.tar.gz: 66550d76441f76abca9249d6d557e785b4d98a5729b16a6d8fef05f6ea79f2842437a24c39d62919b470615e42f75c928610352e4f00af6485c090a29c390195

data/.gitignore

@@ -0,0 +1,37 @@
+*.gem
+*.rbc
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/test/tmp/
+/test/version_tmp/
+/tmp/
+
+.DS_Store
+
+## Specific to RubyMotion:
+.dat*
+.repl_history
+build/
+
+## Documentation cache and generated files:
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+
+## Environment normalisation:
+/.bundle/
+/vendor/bundle
+/lib/bundler/man/
+
+# for a library or gem, you might want to ignore these files since the code is
+# intended to run in multiple environments; otherwise, check them in:
+# Gemfile.lock
+# .ruby-version
+# .ruby-gemset
+
+# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
+.rvmrc

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--require spec_helper

data/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Cody Knauer
+
+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.md

@@ -0,0 +1,2 @@
+# RecommEngine
+A plug-and-play recommendation engine gem supporting multiple similarity algorithms.  Use to recommend products for people, or people for products.

data/lib/calculator.rb

@@ -0,0 +1,11 @@
+module RecommEngine
+  class Calculator
+    attr_reader :data, :subject, :comparate
+
+    def initialize(data:, subject:, comparate:)
+      @data = data
+      @subject = subject
+      @comparate = comparate
+    end
+  end
+end

data/lib/euclidean_calculator.rb

@@ -0,0 +1,19 @@
+module RecommEngine
+  class EuclideanCalculator < Calculator
+    attr_reader :data, :subject, :comparate
+
+    def initialize(data:, subject:, comparate:)
+      super
+    end
+
+    def calc
+      1.0 / (Math.sqrt(1.0 + sum_simalarities))
+    end
+
+    private
+
+    def sum_simalarities
+      @data[@subject].map{ |product, score| ((score - data[comparate][product])**2) if data[comparate][product] }.compact.inject(:+)
+    end
+  end
+end

data/lib/flipper.rb

@@ -0,0 +1,19 @@
+module RecommEngine
+  class Flipper
+    def initialize(data)
+      @data = data
+    end
+
+    def flip
+      result = {}
+      result.default = {}
+      @data.each_key do |k|
+        @data[k].each_key do |kk|
+          result[kk] = {} if result[kk].empty?
+          result[kk][k] = @data[k][kk]
+        end
+      end
+      result
+    end
+  end
+end

data/lib/matcher.rb

@@ -0,0 +1,43 @@
+module RecommEngine
+  class Matcher
+    attr_reader :data, :subject, :similarity, :num
+
+    def initialize(data:, subject:, similarity: RecommEngine::DEFAULT_ALGORITHM, num: RecommEngine::DEFAULT_MATCHES_NUMBER)
+      @data = data
+      @subject = subject
+      @similarity = similarity
+      @num = num
+    end
+
+    def top_matches
+      all_matches.reverse[0..upper_limit]
+    end
+
+    def bottom_matches
+      all_matches[0..upper_limit]
+    end
+
+    private
+
+    def all_matches
+      scores.sort_by{|k, v| v}
+    end
+
+    def scores
+      scores = {}
+      data.each_key do |k|
+        next if subject == k
+        scores[k] = similarity_calculator.new(data: @data, subject: @subject, comparate: k).calc
+      end
+      scores
+    end
+
+    def similarity_calculator
+      Module.const_get("RecommEngine::#{@similarity}Calculator")
+    end
+
+    def upper_limit
+      num - 1
+    end
+  end
+end

data/lib/pearson_calculator.rb

@@ -0,0 +1,52 @@
+module RecommEngine
+  class PearsonCalculator < Calculator
+    attr_accessor :sum1, :sum2, :sq_sum1, :sq_sum2, :product_sum
+
+    def initialize(data:, subject:, comparate:)
+      super
+      @sum1 = @sum2 = @sq_sum1 = @sq_sum2 = @product_sum = 0
+    end
+
+    def calc
+      return 0 if similar_items.empty?
+      sum_all_similarities
+      perform_equation
+    end
+
+    private
+
+    def similar_items
+      @similar_items ||= @data[@subject].map{ |k, v| k if @data[@comparate].keys.include?(k) }.compact
+    end
+
+    def number_of_hits
+      @number_of_hits ||= similar_items.length
+    end
+
+    def sum_all_similarities
+      similar_items.each{ |item| sum_simalarities(item) }
+    end
+
+    def sum_simalarities(item)
+      subject_val = @data[@subject][item]
+      comparate_val = @data[@comparate][item]
+      @sum1 += subject_val
+      @sum2 += comparate_val
+      @sq_sum1 += subject_val**2
+      @sq_sum2 += comparate_val**2
+      @product_sum += subject_val * comparate_val
+    end
+
+    def perform_equation
+      denominator.zero? ? 0 : numerator/denominator
+    end
+
+    def numerator
+      @product_sum - (@sum1 * @sum2/number_of_hits)
+    end
+
+    def denominator
+      @denominator ||= Math.sqrt((@sq_sum1 - (@sum1**2)/number_of_hits)*(@sq_sum2 - (@sum2**2)/number_of_hits))
+    end
+  end
+end

data/lib/recommender.rb

@@ -0,0 +1,62 @@
+module RecommEngine
+  class Recommender
+    attr_reader :data, :subject, :similarity, :similarity_scores, :totals, :similarity_sums
+
+    def initialize(data:, subject:, similarity: RecommEngine::DEFAULT_ALGORITHM)
+      @data = data
+      @subject = subject
+      @similarity = similarity
+      @similarity_scores = {}
+      @totals = {}
+      @similarity_sums = {}
+      @totals.default = 0
+      @similarity_sums.default = 0
+    end
+
+    def recs
+      @data.each_key do |comperate|
+        next if is_subject?(comperate) || non_positive_similarity?(comperate)
+        @data[comperate].each_key do |product|
+          update_sums(comperate, product) unless scored_by_subject?(@subject, product)
+        end
+      end
+      rankings
+    end
+
+    private
+
+    def is_subject?(comperate)
+      comperate == @subject
+    end
+
+    def score(comperate)
+      return @similarity_scores[comperate] if @similarity_scores && @similarity_scores[comperate]
+      @similarity_scores[comperate] = similarity_calculator.new(data: @data, subject: @subject, comparate: comperate).calc
+    end
+
+    def similarity_calculator
+      Module.const_get("RecommEngine::#{@similarity}Calculator")
+    end
+
+    def non_positive_similarity?(comperate)
+      score(comperate) <= 0
+    end
+
+    def scored_by_subject?(subject, product)
+      if @data[subject][product]
+        !@data[subject][product].zero?  || @data[subject].include?(product)
+      end
+    end
+
+    def update_sums(comperate, product)
+      @totals[product] += @data[comperate][product] * score(comperate)
+      @similarity_sums[product] += score(comperate)
+    end
+
+    def rankings
+      rankings = {}
+      @totals.each { |subject, total| rankings[subject] = total / @similarity_sums[subject] }
+      rankings.sort_by{|k, v| v}.reverse
+    end
+  end
+end

data/lib/recommengine.rb

@@ -0,0 +1,26 @@
+Dir['./lib/*.rb'].each { |f| require f }
+
+module RecommEngine
+  DEFAULT_ALGORITHM = 'Pearson'
+  DEFAULT_MATCHES_NUMBER = 3
+
+  def recommendations(data:, subject:, similarity: RecommEngine::DEFAULT_ALGORITHM)
+    RecommEngine::Recommender.new(data: data, subject: subject, similarity: similarity).recs
+  end
+
+  alias_method :recs, :recommendations
+
+  def top_matches(data:, subject:, similarity: RecommEngine::DEFAULT_ALGORITHM, num: RecommEngine::DEFAULT_MATCHES_NUMBER)
+    RecommEngine::Matcher.new(data: data, subject: subject, similarity: similarity, num: num).top_matches
+  end
+
+  def bottom_matches(data:, subject:, similarity: RecommEngine::DEFAULT_ALGORITHM, num: RecommEngine::DEFAULT_MATCHES_NUMBER)
+    RecommEngine::Matcher.new(data: data, subject: subject, similarity: similarity, num: num).bottom_matches
+  end
+
+  def flip(data)
+    RecommEngine::Flipper.new(data).flip
+  end
+
+  module_function :recommendations, :recs, :top_matches, :flip
+end

data/recommengine.gemspec

@@ -0,0 +1,18 @@
+$:.push File.expand_path("../lib", __FILE__)
+
+Gem::Specification.new do |s|
+  s.name          = 'recommengine'
+  s.version       = '0.1.1'
+  s.date          = '2015-08-27'
+  s.summary       = "A flexible recommendation engine."
+  s.description   = "A flexible recommendation engine supporting multiple similarity algorithms for use in ecommerce sites, marketplaces, social sharing apps, and more."
+  s.authors       = ["Cody Knauer"]
+  s.email         = 'codyknauer@gmail.com'
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- spec/*`.split("\n")
+  s.homepage      = 'http://github.com/c0d3s/recommengine'
+  s.license       = 'MIT'
+  s.require_paths = ["lib"]
+
+  s.add_development_dependency 'rspec', '~> 3.1'
+end

data/spec/lib/euclidean_calculator_spec.rb

@@ -0,0 +1,10 @@
+describe '.EuclideanCalculator' do
+  include_context "test data"
+  let(:euclidean_calc) { RecommEngine::EuclideanCalculator.new(data: data, subject: 'ODB', comparate: 'Raekwon') }
+
+  describe '#calc' do
+    it 'calculates euclidean similarity' do
+      expect(euclidean_calc.calc).to eq(0.42640143271122083)
+    end
+  end
+end

data/spec/lib/flipper_spec.rb

@@ -0,0 +1,53 @@
+describe '.recommender' do
+  include_context "test data"
+  let(:flipper) { RecommEngine::Flipper.new(data) }
+
+  describe '#flip' do
+    it 'flips products and users' do
+      expect(flipper.flip).to eq(
+        {"The Sixth Sense"=>
+          {"Ghostface Killah"=>2.5,
+           "RZA"=>3.0,
+           "Raekwon"=>2.5,
+           "Method Man"=>3.0,
+           "ODB"=>3.0},
+         "Snakes on a Plane"=>
+          {"Ghostface Killah"=>3.5,
+           "RZA"=>3.5,
+           "Raekwon"=>3.0,
+           "GZA"=>3.5,
+           "Method Man"=>4.0,
+           "ODB"=>4.0,
+           "Inspectah Deck"=>4.5},
+         "27 Dresses"=>
+          {"Ghostface Killah"=>3.0,
+           "RZA"=>1.5,
+           "GZA"=>3.0,
+           "Method Man"=>2.0},
+         "The Avengers"=>
+          {"Ghostface Killah"=>3.5,
+           "RZA"=>5.0,
+           "Raekwon"=>3.5,
+           "GZA"=>4.0,
+           "Method Man"=>3.0,
+           "ODB"=>5.0,
+           "Inspectah Deck"=>4.0},
+         "Pootie Tang"=>
+          {"Ghostface Killah"=>2.5,
+           "RZA"=>3.5,
+           "GZA"=>2.5,
+           "Method Man"=>2.0,
+           "ODB"=>3.5,
+           "Inspectah Deck"=>1.0},
+         "Titanic"=>
+          {"Ghostface Killah"=>3.0,
+           "RZA"=>3.0,
+           "Raekwon"=>4.0,
+           "GZA"=>4.5,
+           "Method Man"=>3.0,
+           "ODB"=>3.0}
+        }
+      )
+    end
+  end
+end

data/spec/lib/matcher_spec.rb

@@ -0,0 +1,62 @@
+describe '.matcher' do
+  include_context "test data"
+  let(:default_matcher) { RecommEngine::Matcher.new(data: data, subject: 'ODB') }
+  let(:euclidean_matcher) { RecommEngine::Matcher.new(data: data, subject: 'ODB', similarity: 'Euclidean') }
+  let(:default_2_matcher) { RecommEngine::Matcher.new(data: data, subject: 'ODB', num: 2) }
+
+  describe '#initialize' do
+    it 'defaults to Pearson similarity algorithm if none is specified' do
+      expect(default_matcher.similarity).to eq('Pearson')
+    end
+
+    it 'defaults to top 3 matches if num is not specified' do
+      expect(default_matcher.num).to eq(3)
+    end
+  end
+
+  context 'when default calculator' do
+    describe '#bottom_matches' do
+      it 'utilizes Pearson algorithm' do
+        expect(default_matcher.send('similarity_calculator')).to eq(Module.const_get('RecommEngine::PearsonCalculator'))
+      end
+
+      it 'returns bottom most matches' do
+        expect(default_matcher.bottom_matches).to eq([["GZA", 0.02857142857142857], ["Raekwon", 0.13483997249264842], ["Method Man", 0.21128856368212925]])
+      end
+    end
+
+    describe '#top_matches' do
+      it 'returns bottom most matches' do
+        expect(default_matcher.top_matches).to eq([["RZA", 0.963795681875635], ["Ghostface Killah", 0.7470178808339965], ["Inspectah Deck", 0.66284898035987]])
+      end
+    end
+  end
+
+  context 'when euclidean calculator' do
+    describe '#bottom_matches' do
+      it 'returns bottom most matches' do
+        expect(euclidean_matcher.bottom_matches).to eq([["Inspectah Deck", 0.34299717028501764], ["Method Man", 0.3713906763541037], ["Raekwon", 0.42640143271122083]])
+      end
+    end
+
+    describe '#top_matches' do
+      it 'returns bottom most matches' do
+        expect(euclidean_matcher.top_matches).to eq([["RZA", 0.8944271909999159], ["Ghostface Killah", 0.4588314677411235], ["GZA", 0.42640143271122083]])
+      end
+    end
+  end
+
+  context 'when specified number' do
+    describe '#top_matches' do
+      it 'returns 2 records' do
+        expect(default_2_matcher.top_matches.length).to eq(2)
+      end
+    end
+
+    describe '#bottom_matches' do
+      it 'returns 2 records' do
+        expect(default_2_matcher.bottom_matches.length).to eq(2)
+      end
+    end
+  end
+end

data/spec/lib/pearson_calculator_spec.rb

@@ -0,0 +1,10 @@
+describe '.PearsonCalculator' do
+  include_context "test data"
+  let(:pearson_calc) { RecommEngine::PearsonCalculator.new(data: data, subject: 'ODB', comparate: 'Raekwon') }
+
+  describe '#calc' do
+    it 'calculates pearson similarity' do
+      expect(pearson_calc.calc).to eq(0.13483997249264842)
+    end
+  end
+end

data/spec/lib/recommender_spec.rb

@@ -0,0 +1,29 @@
+describe '.recommender' do
+  include_context "test data"
+  let(:default_recommender) { RecommEngine::Recommender.new(data: data, subject: 'Raekwon') }
+  let(:euclidean_recommender) { RecommEngine::Recommender.new(data: data, subject: 'Raekwon', similarity: 'Euclidean') }
+
+  describe '#initialize' do
+    it 'defaults to Pearson similarity algorithm if none is specified' do
+      expect(default_recommender.similarity).to eq('Pearson')
+    end
+  end
+
+  context 'when default calculator' do
+    describe '#recs' do
+      it 'utilizes Pearson algorithm' do
+        expect(default_recommender.send('similarity_calculator')).to eq(Module.const_get('RecommEngine::PearsonCalculator'))
+      end
+
+      it 'returns ranked recommendations' do
+        expect(default_recommender.recs).to eq([["27 Dresses", 2.8092760065251268], ["Pootie Tang", 2.694636703980363]])
+      end
+    end
+  end
+
+  context 'when euclidean calculator' do
+    it 'returns ranked recommendations' do
+      expect(euclidean_recommender.recs).to eq([["27 Dresses", 2.493876153902421], ["Pootie Tang", 2.445567381116539]])
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,3 @@
+Dir['./spec/support/*.rb'].each { |f| require f }
+Dir['./lib/*.rb'].each { |f| require f }
+

data/spec/support/test_data.rb

@@ -0,0 +1,21 @@
+shared_context 'test data' do
+    let(:data) {
+      {'Ghostface Killah'=> {'The Sixth Sense'=> 2.5, 'Snakes on a Plane'=> 3.5,
+   '27 Dresses'=> 3.0, 'The Avengers'=> 3.5, 'Pootie Tang'=> 2.5,
+   'Titanic'=> 3.0},
+  'RZA'=> {'The Sixth Sense'=> 3.0, 'Snakes on a Plane'=> 3.5,
+   '27 Dresses'=> 1.5, 'The Avengers'=> 5.0, 'Titanic'=> 3.0,
+   'Pootie Tang'=> 3.5},
+  'Raekwon'=> {'The Sixth Sense'=> 2.5, 'Snakes on a Plane'=> 3.0,
+   'The Avengers'=> 3.5, 'Titanic'=> 4.0},
+  'GZA'=> {'Snakes on a Plane'=> 3.5, '27 Dresses'=> 3.0,
+   'Titanic'=> 4.5, 'The Avengers'=> 4.0,
+   'Pootie Tang'=> 2.5},
+  'Method Man'=> {'The Sixth Sense'=> 3.0, 'Snakes on a Plane'=> 4.0,
+   '27 Dresses'=> 2.0, 'The Avengers'=> 3.0, 'Titanic'=> 3.0,
+   'Pootie Tang'=> 2.0},
+  'ODB' => {'The Sixth Sense'=> 3.0, 'Snakes on a Plane'=> 4.0,
+   'Titanic'=> 3.0, 'The Avengers'=> 5.0, 'Pootie Tang'=> 3.5},
+  'Inspectah Deck'=> {'Snakes on a Plane'=>4.5, 'Pootie Tang'=>1.0, 'The Avengers'=>4.0}}
+  }
+end

metadata

@@ -0,0 +1,84 @@
+--- !ruby/object:Gem::Specification
+name: recommengine
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- Cody Knauer
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-08-27 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+description: A flexible recommendation engine supporting multiple similarity algorithms
+  for use in ecommerce sites, marketplaces, social sharing apps, and more.
+email: codyknauer@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- LICENSE
+- README.md
+- lib/calculator.rb
+- lib/euclidean_calculator.rb
+- lib/flipper.rb
+- lib/matcher.rb
+- lib/pearson_calculator.rb
+- lib/recommender.rb
+- lib/recommengine.rb
+- recommengine.gemspec
+- spec/lib/euclidean_calculator_spec.rb
+- spec/lib/flipper_spec.rb
+- spec/lib/matcher_spec.rb
+- spec/lib/pearson_calculator_spec.rb
+- spec/lib/recommender_spec.rb
+- spec/spec_helper.rb
+- spec/support/test_data.rb
+homepage: http://github.com/c0d3s/recommengine
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.5
+signing_key: 
+specification_version: 4
+summary: A flexible recommendation engine.
+test_files:
+- spec/lib/euclidean_calculator_spec.rb
+- spec/lib/flipper_spec.rb
+- spec/lib/matcher_spec.rb
+- spec/lib/pearson_calculator_spec.rb
+- spec/lib/recommender_spec.rb
+- spec/spec_helper.rb
+- spec/support/test_data.rb