recommengine 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3576a6e695494260a695452d8da638d6a37e4774
-  data.tar.gz: ed27b1734ddbef8e9504cc2c8cbd64dba6409fd7
+  metadata.gz: 496f46662c16632ef87c39362da42b9bd87ee70b
+  data.tar.gz: 7f8b0dbafa5eedca41292a3fdc07b1ed857b7c4a
 SHA512:
-  metadata.gz: 7b80f257d9f4931371e3c2130a606a323557d0acd0e570f43bb1585b29534dcf8691629d00a98abe148b6518419569d89644aa022af2fd93d6a34e94b748de6a
-  data.tar.gz: 66550d76441f76abca9249d6d557e785b4d98a5729b16a6d8fef05f6ea79f2842437a24c39d62919b470615e42f75c928610352e4f00af6485c090a29c390195
+  metadata.gz: b21579175a273f54b84053b0a512c30c0ff63cbf0bc6f60e6708da970c491ed78a536f7c49bfdb63a18ba13a5e09fa159308d409c774807c8704a85572e6c3e1
+  data.tar.gz: 17a40493de4d89b42adcfb84425b7eabb3079682bfd6a41a78762324fc565e0b0630550c507b36f6e5d57caef7eaf2ee30d9b1589c545e94f70614a7b1698b90

data/README.md

@@ -1,2 +1,117 @@
 # RecommEngine
 A plug-and-play recommendation engine gem supporting multiple similarity algorithms.  Use to recommend products for people, or people for products.
+
+## Installation
+Simply `gem install recommengine` or if using bundler, add recommengine to your Gemfile thusly
+```ruby
+require 'recommengine'
+```
+
+## Methodology
+RecommEngine uses a weighted scoring system in conjunction with a similarity algorithm (of either the Pearson or Euclidean variety) to suggest 'products' to users based on their prior behavior in accordance with the principle of collaborative filtering.  In order to utilize this gem, you must have users, products, and some kind of numerical scoring system that describes a user's interaction with a given product.
+Products need not be physical items, as this gem has applications outside the ecommerce realm. Products can be things like movies or web links as well.  Similarly, scores aren't limited to only to ratings -- they only need to be a numerical representation that describes a user's behavior.  For example:
+
+
+|(Score)| Physical Goods | Movies |  Web Habits  |
+--------|:--------------:|:------:|-------------:|
+|   0   | No Interaction |  < *   | Didn't Click |
+|   1   | Browsed        |   *    | Clicked      |
+|   2   | Searched For   |   **   | Searched for |
+|   3   | Bought         |   ***  |     N/A      |
+|   4   | Bought > 1x    |   **** |     N/A      |
+
+### Euclidean Algorithm
+
+The Euclidean distance algorithm is a simplistic similarity measure that determines how close two points are when plotted in [Cartesian coordinates](https://en.wikipedia.org/wiki/Cartesian_coordinate_system).  Read more about Euclidean distance on [wikipedia](https://en.wikipedia.org/wiki/Euclidean_distance).
+
+### Pearson Algorithm
+
+The Pearson similarity score adds a bit more complexity.  Feel free to read up on it on [wikipedia](https://en.wikipedia.org/wiki/Pearson_product-moment_correlation_coefficient).  The Pearson method is the default similarity algorithm in RecommEngine, primarily because it compensates for grade inflation when determining similarity.
+
+### How Recommendations Work
+
+When passing 'data' and 'subject' arguments to the recommendations method, RecommEngine will compare the similarity between all members of the data hash and the subject using the specified similarity algorithm, and determine a weighted predicted score for each product based upon each user's similarity to the subject.  Only 'products' that the subject has not yet rated will be returned.  The products are sorted by score in descending order.
+
+## Usage
+
+The RecommEngine module can be safely mixed in to your own classes, but in many cases the simplest solution is to call the module function and pass your data, subject, and preferred algorithm (optional) in.
+
+Data must be in the form of a nested hash. Example:
+
+```ruby
+books = {
+  alice: {"War and Peace" => 2.5, "Crime and Punishment" => 3.5},
+  bob: {"War of the Worlds" => 5.0, "War and Peace" => 1.5, "The Great Gatsby" => 4.0},
+  cindy: {"War and Peace" => 5.0, "The Great Gatsby" => 4.5, "War of the Worlds" => 3.0, "Twenty Thousand Leagues Under the Sea" => 3.0},
+  don: {"War of the Worlds" => 4.0, "The Great Gatsby" => 2.5, "Twenty Thousand Leagues Under the Sea" => 5.0, "Crime and Punishment" => 4.5, "War and Peace" => 3.0},
+  erica: {"War of the Worlds" => 3.0, "The Great Gatsby" => 4.5, "Twenty Thousand Leagues Under the Sea" => 4.0, "Crime and Punishment" => 4.5, "War and Peace" => 3.5}}
+```
+### Recommendations
+
+With the above 'data' in place, we can then call
+
+```ruby
+RecommEngine.recs(data: books, subject: :alice)
+```
+
+...which will return:
+
+```ruby
+[["Twenty Thousand Leagues Under the Sea", 4.5],
+ ["The Great Gatsby", 3.5],
+ ["War of the Worlds", 3.5]]
+```
+
+Only products the subject has not rated will be returned.  The second element in each array is the predicted score the subject will give to the product, based upon the weighted average that similar users to alice have rated the product.  Since no similarity algorithm was specified, the Pearson score is used by default.
+
+Alternatively, we could specify the use of the Euclidean algorithm as follows.
+
+```ruby
+RecommEngine(data: books, subject: :alice, similarity: 'Euclidean')
+```
+
+Which returns a similar, though subtly different set of results:
+
+```ruby
+[["Twenty Thousand Leagues Under the Sea", 4.182787296581158],
+ ["War of the Worlds", 3.8959601003790714],
+ ["The Great Gatsby", 3.7736808311188366]]
+```
+### Top Matches
+
+RecommEngine includes a utility to find similar users to a subject.  This can be done by calling:
+
+```ruby
+RecommEngine.top_matches(data: books, subject: :bob)
+```
+
+which returns:
+
+```ruby
+[[:don, 0.4539206495016016], [:alice, 0], [:erica, -0.09078412990032045]]
+```
+
+You'll notice a reasonably strong positive correlation with Don (meaning Don and Bob have similar taste), a neutral correlation with Alice, and a slightly negative correlation with Erica.
+
+By default, the Pearson algorithm is used, and only 3 results are returned.  These  parameters can be defined explicitly when calling the method, by passing for example `num: 5` and/or `similarity: 'Euclidean'`.
+
+### Flipper
+
+RecommEngine also provides a handy means to 'flip' your data -- transposing products and users.  This can be handy when attempting direct marketing campaigns for instance.  Products are compared by similarity, and users are recommended for each products.  It can lead to some interesting results.  For example
+
+```ruby
+RecommEngine.recs(data: RecommEngine.flip(books), subject: 'Crime and Punishment')
+```
+returns
+
+```ruby
+[[:cindy, 5.0], [:bob, 1.5]]
+```
+
+## Contributing
+
+Contributions are welcome; feel encouraged to fork the repo and submit PRs!  Current priorities include adding additional similarity algorithms and working more closely in conjunction with ActiveRecord to form our 'data' objects rather than explicitly declaring hashes.  Please ensure all specs pass before submitting a pull request is submitted, and be sure to add test coverage for any additional features.
+
+## Questions?
+
+codyknauer@gmail.com

data/lib/recommengine.rb

@@ -1,4 +1,15 @@
-Dir['./lib/*.rb'].each { |f| require f }
+# Dir['recommengine/*.rb'].each { |f| require f.gsub('.rb', ''); puts f }
+
+# require 'calculator'
+# require 'euclidean_calculator'
+# require 'flipper'
+# require 'pearson_calculator'
+# require 'matcher'
+# require 'recommender'
+
+files = %w[calculator euclidean_calculator flipper matcher pearson_calculator recommender]
+files.each { |f| require f}
+
 
 module RecommEngine
   DEFAULT_ALGORITHM = 'Pearson'

data/recommengine.gemspec

@@ -2,8 +2,8 @@ $:.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.version       = '0.1.2'
+  s.date          = '2015-09-12'
   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"]
@@ -14,5 +14,7 @@ Gem::Specification.new do |s|
   s.license       = 'MIT'
   s.require_paths = ["lib"]
 
+  s.required_ruby_version = '>= 2.1.0'
+
   s.add_development_dependency 'rspec', '~> 3.1'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: recommengine
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Cody Knauer
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-08-27 00:00:00.000000000 Z
+date: 2015-09-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -35,13 +35,13 @@ files:
 - ".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
+- lib/recommengine/calculator.rb
+- lib/recommengine/euclidean_calculator.rb
+- lib/recommengine/flipper.rb
+- lib/recommengine/matcher.rb
+- lib/recommengine/pearson_calculator.rb
+- lib/recommengine/recommender.rb
 - recommengine.gemspec
 - spec/lib/euclidean_calculator_spec.rb
 - spec/lib/flipper_spec.rb
@@ -62,7 +62,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 2.1.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="