cmfrec 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e6dbbc801e415a4f505ffc436be23ccf066d144da072669e782b88c02e14b0f8
-  data.tar.gz: 3851230f0a4dc4be9fbc24fe81681de0758bdbb583803780f8e07b10741f4bd1
+  metadata.gz: 3bd946bc2c7425ba3550a9cd5bf346b0cac6de5597d0d38ff0dfb49db32e754d
+  data.tar.gz: 20038dc0c401389d75dc3a35415919f6721dab7e32459eeb34c9dcb23569c49a
 SHA512:
-  metadata.gz: 103c09a7c0e13fca3cb81dc68c667e776fc965a485cf358e0fc8f350a97474b54bdfc0910f4472051020dbe34b8c097908c1024d5fc036ad77d0444372885109
-  data.tar.gz: b107b36333f714106d981168f24fda48a2a211f288a2dbe01f570adb607b7d6a5215c18df4c67d159bb367d652f3d10faeb4dbc66688eaf117c5b7a1432ee951
+  metadata.gz: 1d0019e89fe0ca946cd83d60c052bff2e3dcc3990e3bf37de92b620870b6bf8a31010aec87bb2e5a352c446441b683f0148da83497b5d44ef89d62396f4b7d3c
+  data.tar.gz: f4d65f294b9a313c2c86111eaf66e734999924392fedc4715c51919a4ca4de3864ba3eec732f3d707dd06ea62ddb931d9b28b8436a09a807c01e14ac2c542e44

data/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 0.2.1 (2022-07-11)
+
+- Added support for JSON serialization
+
 ## 0.2.0 (2022-06-14)
 
 - Updated cmfrec to 3.4.2

data/README.md

@@ -82,11 +82,11 @@ Add side information about users, items, or both
 ```ruby
 user_info = [
   {user_id: 1, cats: 1, dogs: 0},
-  {user_id: 2, cats: 2, dogs: 1},
+  {user_id: 2, cats: 2, dogs: 1}
 ]
 item_info = [
   {item_id: 1, genre_comedy: 1, genre_drama: 0},
-  {item_id: 2, genre_comedy: 0, genre_drama: 1},
+  {item_id: 2, genre_comedy: 0, genre_drama: 1}
 ]
 recommender.fit(ratings, user_info: user_info, item_info: item_info)
 ```
@@ -213,17 +213,17 @@ Rover.read_csv("ratings.csv")
 Store the recommender
 
 ```ruby
-bin = Marshal.dump(recommender)
-File.binwrite("recommender.bin", bin)
+json = recommender.to_json
+File.write("recommender.json", json)
 ```
 
-> You can save it to a file, database, or any other storage system
+The serialized recommender includes user activity from the training data (to avoid recommending previously rated items), so be sure to protect it. You can save it to a file, database, or any other storage system, or use a tool like [Trove](https://github.com/ankane/trove). Also, user and item IDs should be integers or strings for this.
 
 Load a recommender
 
 ```ruby
-bin = File.binread("recommender.bin")
-recommender = Marshal.load(bin)
+json = File.read("recommender.json")
+recommender = Cmfrec::Recommender.load_json(json)
 ```
 
 Alternatively, you can store only the factors and use a library like [Neighbor](https://github.com/ankane/neighbor). See the [examples](https://github.com/ankane/neighbor/tree/master/examples) for Disco, which has a similar API. For explicit feedback, you should [disable the bias](#explicit-feedback) with this approach.

data/lib/cmfrec/recommender.rb

@@ -249,6 +249,68 @@ module Cmfrec
       similar(user_id, @user_map, user_factors, count, user_index)
     end
 
+    def to_json
+      require "base64"
+      require "json"
+
+      obj = {
+        implicit: @implicit
+      }
+
+      # options
+      obj[:factors] = @k
+      obj[:epochs] = @niter
+      obj[:verbose] = @verbose
+
+      # factors
+      obj[:user_ids] = @user_map.keys
+      obj[:item_ids] = @item_map.keys
+      obj[:rated] = @user_map.map { |_, u| (@rated[u] || {}).keys }
+      obj[:user_factors] = json_dump_ptr(@a)
+      obj[:item_factors] = json_dump_ptr(@b)
+
+      # bias
+      obj[:user_bias] = json_dump_ptr(@bias_a)
+      obj[:item_bias] = json_dump_ptr(@bias_b)
+
+      # mean
+      obj[:global_mean] = @global_mean
+
+      unless (@user_info_map.keys + @item_info_map.keys).all? { |v| v.is_a?(Symbol) }
+        raise "Side info keys must be symbols to save"
+      end
+
+      # side info
+      obj[:user_info_ids] = @user_info_map.keys
+      obj[:item_info_ids] = @item_info_map.keys
+      obj[:user_info_factors] = json_dump_ptr(@c)
+      obj[:item_info_factors] = json_dump_ptr(@d)
+
+      # implicit features
+      obj[:add_implicit_features] = @add_implicit_features
+      obj[:user_factors_implicit] = json_dump_ptr(@ai)
+      obj[:item_factors_implicit] = json_dump_ptr(@bi)
+
+      unless @implicit
+        obj[:min_rating] = @min_rating
+        obj[:max_rating] = @max_rating
+      end
+
+      obj[:user_means] = json_dump_ptr(@u_colmeans)
+
+      JSON.generate(obj)
+    end
+
+    def self.load_json(json)
+      require "json"
+
+      obj = JSON.parse(json)
+
+      recommender = new
+      recommender.send(:json_load, obj)
+      recommender
+    end
+
     private
 
     def user_index
@@ -856,5 +918,70 @@ module Cmfrec
 
       @fit = @m > 0
     end
+
+    def json_dump_ptr(ptr)
+      Base64.strict_encode64(ptr.to_s(ptr.size)) if ptr
+    end
+
+    def json_load_ptr(str)
+      Fiddle::Pointer[Base64.strict_decode64(str)] if str
+    end
+
+    def json_load(obj)
+      require "base64"
+
+      @implicit = obj["implicit"]
+
+      # options
+      set_params(
+        k: obj["factors"],
+        niter: obj["epochs"],
+        verbose: obj["verbose"],
+        user_bias: !obj["user_bias"].nil?,
+        item_bias: !obj["item_bias"].nil?,
+        add_implicit_features: obj["add_implicit_features"]
+      )
+
+      # factors
+      @user_map = obj["user_ids"].map.with_index.to_h
+      @item_map = obj["item_ids"].map.with_index.to_h
+      @rated = obj["rated"].map.with_index.to_h { |r, i| [i, r.to_h { |v| [v, true] }] }
+      @a = json_load_ptr(obj["user_factors"])
+      @b = json_load_ptr(obj["item_factors"])
+
+      # bias
+      @bias_a = json_load_ptr(obj["user_bias"])
+      @bias_b = json_load_ptr(obj["item_bias"])
+
+      # mean
+      @global_mean = obj["global_mean"]
+
+      # side info
+      @user_info_map = obj["user_info_ids"].map(&:to_sym).map.with_index.to_h
+      @item_info_map = obj["item_info_ids"].map(&:to_sym).map.with_index.to_h
+      @c = json_load_ptr(obj["user_info_factors"])
+      @d = json_load_ptr(obj["item_info_factors"])
+
+      # implicit features
+      @add_implicit_features = obj["add_implicit_features"]
+      @ai = json_load_ptr(obj["user_factors_implicit"])
+      @bi = json_load_ptr(obj["item_factors_implicit"])
+
+      unless @implicit
+        @min_rating = obj["min_rating"]
+        @max_rating = obj["max_rating"]
+      end
+
+      @u_colmeans = json_load_ptr(obj["user_means"])
+
+      @m = @user_map.size
+      @n = @item_map.size
+      @m_u = @user_info_map.size
+      @n_i = @item_info_map.size
+
+      set_implicit_vars if @implicit
+
+      @fit = @m > 0
+    end
   end
 end

data/lib/cmfrec/version.rb

@@ -1,3 +1,3 @@
 module Cmfrec
-  VERSION = "0.2.0"
+  VERSION = "0.2.1"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cmfrec
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Andrew Kane
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-06-15 00:00:00.000000000 Z
+date: 2022-07-11 00:00:00.000000000 Z
 dependencies: []
 description:
 email: andrew@ankane.org