First commit

.gitignore

@@ -0,0 +1,9 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.lock

CHANGELOG.md

@@ -0,0 +1,3 @@
+## 0.1.0
+
+- First release

Gemfile

@@ -0,0 +1,3 @@
+source "https://rubygems.org"
+
+gemspec

LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2019 Andrew Kane
+
+MIT License
+
+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.

README.md

@@ -0,0 +1,279 @@
+# Disco
+
+:fire: Collaborative filtering for Ruby
+
+- Supports user-based and item-based recommendations
+- Works with explicit and implicit feedback
+- Uses matrix factorization
+
+## Installation
+
+Add this line to your application’s Gemfile:
+
+```ruby
+gem 'disco'
+```
+
+## Getting Started
+
+Create a recommender
+
+```ruby
+recommender = Disco::Recommender.new
+```
+
+If users rate items directly, this is known as explicit feedback. Fit the recommender with:
+
+```ruby
+recommender.fit([
+  {user_id: 1, item_id: 1, rating: 5},
+  {user_id: 2, item_id: 1, rating: 3}
+])
+```
+
+> IDs can be integers, strings, or any other data type
+
+If users don’t rate items directly (for instance, they’re purchasing items or reading posts), this is known as implicit feedback. Leave out the rating, or use a value like number of purchases, number of page views, or time spent on page:
+
+```ruby
+recommender.fit([
+  {user_id: 1, item_id: 1, value: 1},
+  {user_id: 2, item_id: 1, value: 1}
+])
+```
+
+> Use `value` instead of rating for implicit feedback
+
+Get user-based (user-item) recommendations - “users like you also liked”
+
+```ruby
+recommender.user_recs(user_id)
+```
+
+Get item-based (item-item) recommendations - “users who liked this item also liked”
+
+```ruby
+recommender.item_recs(item_id)
+```
+
+Use the `count` option to specify the number of recommendations (default is 5)
+
+```ruby
+recommender.user_recs(user_id, count: 3)
+```
+
+Get predicted ratings for specific items
+
+```ruby
+recommender.user_recs(user_id, item_ids: [1, 2, 3])
+```
+
+Get similar users
+
+```ruby
+recommender.similar_users(user_id)
+```
+
+## Examples
+
+### MovieLens
+
+Load the data
+
+```ruby
+data = Disco.load_movielens
+```
+
+Create a recommender and get similar movies
+
+```ruby
+recommender = Disco::Recommender.new(factors: 20)
+recommender.fit(data)
+recommender.item_recs("Star Wars (1977)")
+```
+
+### Ahoy
+
+[Ahoy](https://github.com/ankane/ahoy) is a great source for implicit feedback
+
+```ruby
+views = Ahoy::Event.
+  where(name: "Viewed post").
+  group(:user_id, "properties->>'post_id'") # postgres syntax
+  count
+
+data =
+  views.map do |(user_id, post_id), count|
+    {
+      user_id: user_id,
+      post_id: post_id,
+      value: count
+    }
+  end
+```
+
+Create a recommender and get recommended posts for a user
+
+```ruby
+recommender = Disco::Recommender.new
+recommender.fit(data)
+recommender.user_recs(current_user.id)
+```
+
+## Storing Recommendations
+
+Disco makes it easy to store recommendations in Rails.
+
+```sh
+rails generate disco:recommendation
+rails db:migrate
+```
+
+For user-based recommendations, use:
+
+```ruby
+class User < ApplicationRecord
+  has_recommended :products
+end
+```
+
+> Change `:products` to match the model you’re recommending
+
+Save recommendations
+
+```ruby
+User.find_each do |user|
+  recs = recommender.user_recs(user.id)
+  user.update_recommended_products(recs)
+end
+```
+
+Get recommendations
+
+```ruby
+user.recommended_products
+```
+
+For item-based recommendations, use:
+
+```ruby
+class Product < ApplicationRecord
+  has_recommended :products
+end
+```
+
+Specify multiple types of recommendations for a model with:
+
+```ruby
+class User < ApplicationRecord
+  has_recommended :products
+  has_recommended :products_v2, class_name: "Product"
+end
+```
+
+And use the appropriate methods:
+
+```ruby
+user.update_recommended_products_v2(recs)
+user.recommended_products_v2
+```
+
+For Rails < 6, speed up inserts by adding [activerecord-import](https://github.com/zdennis/activerecord-import) to your app.
+
+## Storing Recommenders
+
+If you’d prefer to perform recommendations on-the-fly, store the recommender
+
+```ruby
+bin = Marshal.dump(recommender)
+File.binwrite("recommender.bin", bin)
+```
+
+> You can save it to a file, database, or any other storage system
+
+Load a recommender
+
+```ruby
+bin = File.binread("recommender.bin")
+recommender = Marshal.load(bin)
+```
+
+## Algorithms
+
+Disco uses matrix factorization.
+
+- For explicit feedback, it uses [stochastic gradient descent](https://www.csie.ntu.edu.tw/~cjlin/papers/libmf/libmf_journal.pdf)
+- For implicit feedback, it uses [coordinate descent](https://www.csie.ntu.edu.tw/~cjlin/papers/one-class-mf/biased-mf-sdm-with-supp.pdf)
+
+Specify the number of factors and epochs
+
+```ruby
+Disco::Recommender.new(factors: 8, epochs: 20)
+```
+
+If recommendations look off, trying changing `factors`. The default is 8, but 3 could be good for some applications and 300 good for others.
+
+## Validation
+
+Pass a validation set with:
+
+```ruby
+recommender.fit(data, validation_set: validation_set)
+```
+
+## Cold Start
+
+Collaborative filtering suffers from the [cold start problem](https://www.yuspify.com/blog/cold-start-problem-recommender-systems/). It’s unable to make good recommendations without data on a user or item, which is problematic for new users and items.
+
+```ruby
+recommender.user_recs(new_user_id) # returns empty array
+```
+
+There are a number of ways to deal with this, but here are some common ones:
+
+- For user-based recommendations, show new users the most popular items.
+- For item-based recommendations, make content-based recommendations with a gem like [tf-idf-similarity](https://github.com/jpmckinney/tf-idf-similarity).
+
+## Daru
+
+Disco works with Daru data frames
+
+```ruby
+data = Daru::DataFrame.from_csv("ratings.csv")
+recommender.fit(data)
+```
+
+## Reference
+
+Get the global mean
+
+```ruby
+recommender.global_mean
+```
+
+Get the factors
+
+```ruby
+recommender.user_factors
+recommender.item_factors
+```
+
+## Credits
+
+Thanks to:
+
+- [LIBMF](https://github.com/cjlin1/libmf) for providing high performance matrix factorization
+- [Implicit](https://github.com/benfred/implicit/) for serving as an initial reference for user and item similarity
+
+## History
+
+View the [changelog](https://github.com/ankane/disco/blob/master/CHANGELOG.md)
+
+## Contributing
+
+Everyone is encouraged to help improve this project. Here are a few ways you can help:
+
+- [Report bugs](https://github.com/ankane/disco/issues)
+- Fix bugs and [submit pull requests](https://github.com/ankane/disco/pulls)
+- Write, clarify, or fix documentation
+- Suggest or add new features

Rakefile

@@ -0,0 +1,9 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+task default: :test
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.pattern = "test/**/*_test.rb"
+  t.warning = false
+end

app/models/disco/recommendation.rb

@@ -0,0 +1,8 @@
+module Disco
+  class Recommendation < ActiveRecord::Base
+    self.table_name = "disco_recommendations"
+
+    belongs_to :subject, polymorphic: true
+    belongs_to :item, polymorphic: true
+  end
+end

disco.gemspec

@@ -0,0 +1,27 @@
+require_relative "lib/disco/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "disco"
+  spec.version       = Disco::VERSION
+  spec.summary       = "Collaborative filtering for Ruby"
+  spec.homepage      = "https://github.com/ankane/disco"
+  spec.license       = "MIT"
+
+  spec.author        = "Andrew Kane"
+  spec.email         = "andrew@chartkick.com"
+
+  spec.files         = Dir["*.{md,txt}", "{lib}/**/*"]
+  spec.require_path  = "lib"
+
+  spec.required_ruby_version = ">= 2.4"
+
+  spec.add_dependency "libmf", ">= 0.1.3"
+  spec.add_dependency "numo-narray"
+
+  spec.add_development_dependency "bundler"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "minitest", ">= 5"
+  spec.add_development_dependency "activerecord"
+  spec.add_development_dependency "sqlite3"
+  spec.add_development_dependency "daru"
+end

lib/disco.rb

@@ -0,0 +1,29 @@
+# dependencies
+require "libmf"
+require "numo/narray"
+
+# stdlib
+require "csv"
+require "fileutils"
+require "net/http"
+
+# modules
+require "disco/data"
+require "disco/recommender"
+require "disco/version"
+
+# integrations
+require "disco/engine" if defined?(Rails)
+
+module Disco
+  class Error < StandardError; end
+
+  extend Data
+end
+
+if defined?(ActiveSupport.on_load)
+  ActiveSupport.on_load(:active_record) do
+    require "disco/model"
+    extend Disco::Model
+  end
+end