co2_filter 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: aa78d78af6f6ed5e9dc74d4104f85759dc5299d6
-  data.tar.gz: d2b184ffa6deac97b8d0afc8e9020b92fc2263cd
+  metadata.gz: 200b98128f375b95bc95eeef7eee80e24f970f17
+  data.tar.gz: e1c8b8c12ef51beb83281a4af88045df6b27a7c2
 SHA512:
-  metadata.gz: 231065d35af899464b9aad9c690e29591eba7ae846f58b3886b3b5a0ce963fe69b370d2a6df52e37745b8ad6debadb09d10f8162a481a182e138afb596fc7b99
-  data.tar.gz: 46ffdb54af8bec7e72366bed2772d214344c65ee8c1a7d7cee23c33953f6aaab0075c86250a28add3c4901bd809ca519fba47d359a0a62ab7d06e51c099fe902
+  metadata.gz: 79e65ec47635ae4177f0f30aa420573d15c601fb5b4d521d3235046dd947f9c508d38fd1ef7121721e3071b2fc4a8c5eae3c36920870871368bfe21eb46d5260
+  data.tar.gz: c598b3125d2c286c60a8c47f63a64b70228ac81620b2b0f39d3ea51ef61873dd3e6baa9842e2bf5285f28aee0a76cd6bf02614e83c95f14fc4e0e9ff81bb0caf

data/README.rdoc

@@ -15,7 +15,7 @@ Rating ranges are irrelevant to the algorithm, as rating averages are the key po
 
 Add this line to your application's Gemfile:
 
-    gem 'co2_filter', git: 'https://github.com/comatose-turtle/co2_filter.git'
+    gem 'co2_filter'
 
 And then execute:
 
@@ -70,9 +70,28 @@ Attribute strength refers to a situation where attributes are applied in varying
 
 === Using Individual Filters
 
+==== Collaborative Filter
+
 To implement only the collaborative filter, just use:
     Co2Filter::Collaborative.filter(current_user: current_user, other_users: other_users)
 
+The collaborative filter accepts an argument that determines by what process users are determined to be similar, called +measure+:
+    Co2Filter::Collaborative.filter(current_user: current_user, other_users: other_users, measure: :euclidean)
+If is assigned to +:euclidean+, users will be considered similar based on the Euclidean distance of their rating sets.  This is a straight-forward comparison that makes sense to most people, but may overlook some subtleties.
+If assigned to +:cosine+, users' similarity is determined by a mean-based cosine coefficient.  This essentially means that the curve formed by users' rating sets is compared by shape to others'.  This technique is more reliable in some cases, but suffers considerably more in sparse data sets.
++:hybrid+ is the default measure, which represents an average of the above two measures.  Inherently, this makes it slower, but averaging may prove more reliable overall.  It unfortunately may also smooth over the uniquely accurate aspects of each technique, lowering opportunities for a surprisingly good recommendation (or surprisingly bad).
+
+You may also feed precalculated similarity coefficients into the filter using the +similarity_coefficients+ argument:
+    similarity_coefficients = {
+        'user1' => 0.56,
+        'user2' => 0.8,
+        'user3' => -0.4
+        # ...
+    }
+    Co2Filter::Collaborative.filter(current_user: current_user, other_users: other_users, similarity_coefficients: similarity_coefficients)
+
+==== Content-Based Filter
+
 To implement only the content-based filter, use:
     Co2Filter::ContentBased.filter(user: current_user, items: items)
 
@@ -83,6 +102,10 @@ The content-based filtering process consists of two steps:
 If you are interested in doing this process piecemeal (for instance, to save the user profile to the database for later use), you can do so:
     user_profile = Co2Filter::ContentBased.ratings_to_profile(user_ratings: current_user, items: items)
     Co2Filter::ContentBased.filter(user: user_profile, items: items)
+Note that a <tt>Co2Filter::ContentBased::UserProfile</tt> object like the one returned must be submitted as the user to trigger this shortcut.
+
+Separately run content-based filtering can be combined into the base (hybrid) filter by submitting the results (as a <tt>Co2Filter::Results</tt> object) to the filter as follows:
+    recommended = Co2Filter.filter(current_user: current_user, other_users: other_users, content_based_results: content_based_results)
 
 === Content-Boosted Collaborative Filtering
 
@@ -92,7 +115,7 @@ Content-boosted collaborative filtering can be used as follows:
 This is the most processor-intensive algorithm, but it too can be split up into multiple pieces if you wish:
     boosted_users = Co2Filter::ContentBased.boost_ratings(users: other_users, items: items)
     Co2Filter::Collaborative.filter(current_user: current_user, other_users: boosted_users)
-Note that the second step is simply the basic collaborative filter.  If you wish to break up the +boost_ratings+ method even further, then you are actually talking about using the +Co2Filter::ContentBased.filter+ on each of the users. (See the definition for +boost_ratings+.)
+Note that the second step is simply the basic collaborative filter.  If you wish to break up the +boost_ratings+ method even further, then you are actually talking about using the <tt>Co2Filter::ContentBased.filter</tt> on each of the users. (See the definition for +boost_ratings+.)
 
 == Contributing
 

data/lib/co2_filter/collaborative.rb

@@ -1,9 +1,22 @@
 module Co2Filter::Collaborative
   autoload :Results, 'co2_filter/collaborative/results'
 
-  def self.filter(current_user:, other_users:, measure: :hybrid)
+  def self.filter(current_user: nil, other_users: nil, measure: :hybrid, similarity_coefficients: nil)
+    raise ArgumentError.new("A 'current_user' argument must be provided.") unless current_user
+    raise ArgumentError.new("An 'other_users' argument must be provided.") unless other_users
+
     current_user = Co2Filter::RatingSet.new(current_user) unless current_user.is_a? Co2Filter::RatingSet
-    if measure == :euclidean
+    if similarity_coefficients.is_a? Hash
+      processed_users = other_users.inject({}) do |processed, (user_id, ratings)|
+        ratings = Co2Filter::RatingSet.new(ratings) unless ratings.is_a? Co2Filter::RatingSet
+        processed[user_id] = {
+          ratings: ratings,
+          mean: ratings.mean,
+          coefficient: similarity_coefficients[user_id]
+        } if similarity_coefficients[user_id]
+        processed
+      end
+    elsif measure == :euclidean
       processed_users = euclidean(current_user: current_user, other_users: other_users, num_nearest: 30)
     elsif measure == :cosine
       processed_users = mean_centered_cosine(current_user: current_user, other_users: other_users, num_nearest: 30)
@@ -39,7 +52,10 @@ module Co2Filter::Collaborative
     Results.new(item_ratings)
   end
 
-  def self.mean_centered_cosine(current_user:, other_users:, num_nearest:)
+  def self.mean_centered_cosine(current_user: nil, other_users: nil, num_nearest: 30)
+    raise ArgumentError.new("A 'current_user' argument must be provided.") unless current_user
+    raise ArgumentError.new("An 'other_users' argument must be provided.") unless other_users
+
     processed = other_users.map do |key, user2|
       user2 = Co2Filter::RatingSet.new(user2) unless user2.is_a? Co2Filter::RatingSet
       [key, single_cosine(current_user, user2)]
@@ -85,7 +101,10 @@ module Co2Filter::Collaborative
     }
   end
 
-  def self.euclidean(current_user:, other_users:, num_nearest:, range:0)
+  def self.euclidean(current_user: nil, other_users: nil, num_nearest: 30, range:0)
+    raise ArgumentError.new("A 'current_user' argument must be provided.") unless current_user
+    raise ArgumentError.new("An 'other_users' argument must be provided.") unless other_users
+
     if range == 0
       lowest = nil
       highest = nil

data/lib/co2_filter/content_based.rb

@@ -2,7 +2,10 @@ module Co2Filter::ContentBased
   autoload :Results, 'co2_filter/content_based/results'
   autoload :UserProfile, 'co2_filter/content_based/user_profile'
 
-  def self.filter(user:, items:)
+  def self.filter(user: nil, items: nil)
+    raise ArgumentError.new("A 'user' argument must be provided.") unless user
+    raise ArgumentError.new("An 'items' argument must be provided.") unless items
+
     if(user.is_a?(UserProfile))
       user_profile = user
       new_items = items
@@ -25,7 +28,10 @@ module Co2Filter::ContentBased
     Results.new(results)
   end
 
-  def self.ratings_to_profile(user_ratings:, items:)
+  def self.ratings_to_profile(user_ratings: nil, items: nil)
+    raise ArgumentError.new("A 'user_ratings' argument must be provided.") unless user_ratings
+    raise ArgumentError.new("An 'items' argument must be provided.") unless items
+
     user_ratings = Co2Filter::RatingSet.new(user_ratings) unless user_ratings.is_a? Co2Filter::RatingSet
     user_prefs = {}
     strength_normalizers = {}
@@ -47,7 +53,10 @@ module Co2Filter::ContentBased
     UserProfile.new(user_prefs, user_ratings.mean)
   end
 
-  def self.boost_ratings(users:, items:)
+  def self.boost_ratings(users: nil, items: nil)
+    raise ArgumentError.new("A 'users' argument must be provided.") unless users
+    raise ArgumentError.new("An 'items' argument must be provided.") unless items
+
     users.inject({}) do |content_boosted_users, (user_id, ratings)|
       content_boosted_users[user_id] = ratings.merge(filter(user: ratings, items: items))
       content_boosted_users

data/lib/co2_filter/version.rb

@@ -1,3 +1,3 @@
 module Co2Filter
-  VERSION = "0.0.1"
+  VERSION = "0.1.0"
 end

data/lib/co2_filter.rb

@@ -1,6 +1,9 @@
 module Co2Filter
-  def self.filter(current_user: , other_users: , items: nil, user_profile: nil, content_based_results: nil)
+  def self.filter(current_user: nil, other_users: nil, items: nil, user_profile: nil, content_based_results: nil)
+    raise ArgumentError.new("A 'current_user' argument must be provided.") unless current_user
+    raise ArgumentError.new("An 'other_users' argument must be provided.") unless other_users
     raise ArgumentError.new("An 'items' or 'content_based_results' argument must be provided.") unless items || content_based_results
+
     collab = Collaborative.filter(current_user: current_user, other_users: other_users)
     
     if content_based_results && content_based_results.is_a?(Results)
@@ -17,7 +20,11 @@ module Co2Filter
     Results.new(hybrid)
   end
 
-  def self.content_boosted_collaborative_filter(current_user:, other_users:, items:)
+  def self.content_boosted_collaborative_filter(current_user: nil, other_users: nil, items: nil)
+    raise ArgumentError.new("A 'current_user' argument must be provided.") unless current_user
+    raise ArgumentError.new("An 'other_users' argument must be provided.") unless other_users
+    raise ArgumentError.new("An 'items' argument must be provided.") unless items
+
     content_boosted_users = ContentBased.boost_ratings(users: other_users, items: items)
     results = Collaborative.filter(current_user: current_user, other_users: content_boosted_users)
     Results.new(results)

metadata

@@ -1,55 +1,55 @@
 --- !ruby/object:Gem::Specification
 name: co2_filter
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.0
 platform: ruby
 authors:
 - Tommy Orr
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-02-19 00:00:00.000000000 Z
+date: 2016-03-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
         version: '1.11'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
         version: '1.11'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
         version: '10.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
         version: '10.0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
         version: '3.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
         version: '3.0'
 description: 
@@ -59,20 +59,20 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- MIT-LICENSE
-- README.rdoc
-- Rakefile
-- lib/co2_filter.rb
-- lib/co2_filter/collaborative.rb
 - lib/co2_filter/collaborative/results.rb
-- lib/co2_filter/content_based.rb
+- lib/co2_filter/collaborative.rb
 - lib/co2_filter/content_based/results.rb
 - lib/co2_filter/content_based/user_profile.rb
+- lib/co2_filter/content_based.rb
 - lib/co2_filter/hash_wrapper.rb
 - lib/co2_filter/rating_set.rb
 - lib/co2_filter/results.rb
 - lib/co2_filter/version.rb
+- lib/co2_filter.rb
 - lib/tasks/co2_filter_tasks.rake
+- MIT-LICENSE
+- Rakefile
+- README.rdoc
 homepage: https://github.com/comatose-turtle/co2_filter
 licenses:
 - MIT
@@ -83,17 +83,17 @@ 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.1
+rubygems_version: 2.0.14
 signing_key: 
 specification_version: 4
 summary: Uses both collaborative and content-based filtering methods to enable a complex,