libmf 0.1.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 85fc60af42649286b87cf23130c0efafd0d8951423d31b187d13097b2418e7d1
-  data.tar.gz: ab568af8e036b6d38fcc604746eeda4fa29e2e6e7541e6af53b77f9979e9fe82
+  metadata.gz: 1d7744d5436815acc2609c8c39566f5704513248b5fe0b7ddc1cc4fbd28c81e9
+  data.tar.gz: 0bcd219cc9360b0e9daefe418e2a14fc46969ab174db5ea93717c837e309c697
 SHA512:
-  metadata.gz: efcbffd9ed9e6f66911a63e74d694da77d798d0fde04cb1490c1ee4eaf8d9e1e93b1af13ab8e23a4a858b74503d28a616ad6499a590f4a1568df2a9dcb65d85f
-  data.tar.gz: 671b306cad36c2ea5da6633de6703892e19fbb5774cf22a0d458ba3d967ab50dc5ae56ed271771e4ed1a0483346d8d9f34ec5db9c8424d16f369e81c5f467857
+  metadata.gz: 49d31c33bea909e1a3a0a8cdebc6cce76b2cf19debc11420d76ad2016763961f376df56bdbba16e6a60e72a8014a2b44547045b2385f44b6c96f48f3f6148643
+  data.tar.gz: 3f264d87a4cc727634ac8b2cb5dc87a56a44c3fba7d77093c83ca3623437be6024c04b1fe154275fd3a14a6736bf6703ea2fae9b984570b5c4629af3b5c710f3

data/CHANGELOG.md

@@ -1,3 +1,27 @@
-## 0.1.0
+## 0.2.1 (2020-12-28)
+
+- Added ARM shared library for Mac
+
+## 0.2.0 (2020-03-26)
+
+- Changed to BSD 3-Clause license to match LIBMF
+- Added support for reading data directly from files
+- Added `format: :numo` option to `p_factors` and `q_factors`
+- Improved performance of loading data by 5x
+
+## 0.1.3 (2019-11-07)
+
+- Made parameter names more Ruby-like
+- No need to set `do_nmf` with generalized KL-divergence
+
+## 0.1.2 (2019-11-06)
+
+- Fixed bug in `p_factors` and `q_factors` methods
+
+## 0.1.1 (2019-11-05)
+
+- Fixed errors on Linux and Windows
+
+## 0.1.0 (2019-11-04)
 
 - First release

data/LICENSE.txt

@@ -1,22 +1,30 @@
-Copyright (c) 2019 Andrew Kane
+BSD 3-Clause License
 
-MIT License
+Copyright (c) 2014-2015, The LIBMF Project
+Copyright (c) 2019-2020, Andrew Kane
+All rights reserved.
 
-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:
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
 
-The above copyright notice and this permission notice shall be
-included in all copies or substantial portions of the Software.
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
 
-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.
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -2,7 +2,9 @@
 
 [LIBMF](https://github.com/cjlin1/libmf) - large-scale sparse matrix factorization - for Ruby
 
-:fire: Uses the C API for blazing performance
+Check out [Disco](https://github.com/ankane/disco) for higher-level collaborative filtering
+
+[![Build Status](https://github.com/ankane/libmf/workflows/build/badge.svg?branch=master)](https://github.com/ankane/libmf/actions)
 
 ## Installation
 
@@ -37,14 +39,19 @@ Make predictions
 model.predict(row_index, column_index)
 ```
 
-Get the bias and latent factors
+Get the latent factors (these approximate the training matrix)
 
 ```ruby
-model.bias
 model.p_factors
 model.q_factors
 ```
 
+Get the bias (average of all elements in the training matrix)
+
+```ruby
+model.bias
+```
+
 Save the model to a file
 
 ```ruby
@@ -63,48 +70,87 @@ Pass a validation set
 model.fit(data, eval_set: eval_set)
 ```
 
+## Cross-Validation
+
+Perform cross-validation
+
+```ruby
+model.cv(data)
+```
+
+Specify the number of folds
+
+```ruby
+model.cv(data, folds: 5)
+```
+
 ## Parameters
 
-Pass parameters
+Pass parameters - default values below
 
 ```ruby
-model = Libmf::Model.new(k: 20, nr_iters: 50)
-```
-
-Supports the same parameters as LIBMF
-
-```text
-variable      meaning                                    default
-================================================================
-fun           loss function                                    0
-k             number of latent factors                         8
-nr_threads    number of threads used                          12
-nr_bins       number of bins                                  25
-nr_iters      number of iterations                            20
-lambda_p1     coefficient of L1-norm regularization on P       0
-lambda_p2     coefficient of L2-norm regularization on P     0.1
-lambda_q1     coefficient of L1-norm regularization on Q       0
-lambda_q2     coefficient of L2-norm regularization on Q     0.1
-eta           learning rate                                  0.1
-alpha         importance of negative entries                 0.1
-c             desired value of negative entries           0.0001
-do_nmf        perform non-negative MF (NMF)                false
-quiet         no outputs to stdout                         false
-copy_data     copy data in training procedure               true
+Libmf::Model.new(
+  loss: 0,                # loss function
+  factors: 8,             # number of latent factors
+  threads: 12,            # number of threads used
+  bins: 25,               # number of bins
+  iterations: 20,         # number of iterations
+  lambda_p1: 0,           # coefficient of L1-norm regularization on P
+  lambda_p2: 0.1,         # coefficient of L2-norm regularization on P
+  lambda_q1: 0,           # coefficient of L1-norm regularization on Q
+  lambda_q2: 0.1,         # coefficient of L2-norm regularization on Q
+  learning_rate: 0.1,     # learning rate
+  alpha: 0.1,             # importance of negative entries
+  c: 0.0001,              # desired value of negative entries
+  nmf: false,             # perform non-negative MF (NMF)
+  quiet: false            # no outputs to stdout
+)
 ```
 
-## Cross-Validation
+### Loss Functions
 
-Perform cross-validation
+For real-valued matrix factorization
+
+- 0 - squared error (L2-norm)
+- 1 - absolute error (L1-norm)
+- 2 - generalized KL-divergence
+
+For binary matrix factorization
+
+- 5 - logarithmic error
+- 6 - squared hinge loss
+- 7 - hinge loss
+
+For one-class matrix factorization
+
+- 10 - row-oriented pair-wise logarithmic loss
+- 11 - column-oriented pair-wise logarithmic loss
+- 12 - squared error (L2-norm)
+
+## Performance
+
+For performance, read data directly from files
 
 ```ruby
-model.cv(data)
+model.fit("train.txt", eval_set: "validate.txt")
+model.cv("train.txt")
 ```
 
-Specify the number of folds
+Data should be in the format `row_index column_index value`:
+
+```txt
+0 0 5.0
+0 2 3.5
+1 1 4.0
+```
+
+## Numo
+
+Get latent factors as Numo arrays
 
 ```ruby
-model.cv(data, folds: 5)
+model.p_factors(format: :numo)
+model.q_factors(format: :numo)
 ```
 
 ## Resources
@@ -123,3 +169,13 @@ Everyone is encouraged to help improve this project. Here are a few ways you can
 - Fix bugs and [submit pull requests](https://github.com/ankane/libmf/pulls)
 - Write, clarify, or fix documentation
 - Suggest or add new features
+
+To get started with development:
+
+```sh
+git clone --recursive https://github.com/ankane/libmf.git
+cd libmf
+bundle install
+bundle exec rake vendor:all
+bundle exec rake test
+```

data/lib/libmf.rb

@@ -11,15 +11,18 @@ module Libmf
   class << self
     attr_accessor :ffi_lib
   end
-  self.ffi_lib = ["mf"]
-
-  lib_path =
-    if ::FFI::Platform.windows?
-      "../vendor/windows/mf.dll"
+  lib_name =
+    if Gem.win_platform?
+      "mf.dll"
+    elsif RbConfig::CONFIG["arch"] =~ /arm64-darwin/i
+      "libmf.arm64.dylib"
+    elsif RbConfig::CONFIG["host_os"] =~ /darwin/i
+      "libmf.dylib"
     else
-      "libmf.bundle"
+      "libmf.so"
     end
-  self.ffi_lib << File.expand_path(lib_path, __dir__)
+  vendor_lib = File.expand_path("../vendor/#{lib_name}", __dir__)
+  self.ffi_lib = [vendor_lib]
 
   # friendlier error message
   autoload :FFI, "libmf/ffi"

data/lib/libmf/ffi.rb

@@ -2,12 +2,7 @@ module Libmf
   module FFI
     extend ::FFI::Library
 
-    begin
-      ffi_lib Libmf.ffi_lib
-    rescue LoadError => e
-      raise e if ENV["LIBMF_DEBUG"]
-      raise LoadError, "Could not find LIBMF"
-    end
+    ffi_lib Libmf.ffi_lib
 
     class Node < ::FFI::Struct
       layout :u, :int,
@@ -51,6 +46,7 @@ module Libmf
     end
 
     attach_function :mf_get_default_param, [], Parameter.by_value
+    attach_function :mf_read_problem, [:string], Problem.by_value
     attach_function :mf_save_model, [Model.by_ref, :string], :int
     attach_function :mf_load_model, [:string], Model.by_ref
     attach_function :mf_destroy_model, [Model.by_ref], :void

data/lib/libmf/model.rb

@@ -51,16 +51,27 @@ module Libmf
       model[:b]
     end
 
-    def p_factors
-      reshape(model[:p].read_array_of_float(factors * rows), [rows, factors])
+    def p_factors(format: nil)
+      _factors(model[:p], rows, format)
     end
 
-    def q_factors
-      reshape(model[:q].read_array_of_float(factors * columns), [columns, factors])
+    def q_factors(format: nil)
+      _factors(model[:q], columns, format)
     end
 
     private
 
+    def _factors(ptr, n, format)
+      case format
+      when :numo
+        Numo::SFloat.from_string(ptr.read_bytes(n * factors * 4)).reshape(n, factors)
+      when nil
+        ptr.read_array_of_float(n * factors).each_slice(factors).to_a
+      else
+        raise ArgumentError, "Invalid format"
+      end
+    end
+
     def model
       raise Error, "Not fit" unless @model
       @model
@@ -68,45 +79,60 @@ module Libmf
 
     def param
       param = FFI.mf_get_default_param
+      options = @options.dup
       # silence insufficient blocks warning with default params
-      options = {nr_bins: 25}.merge(@options)
+      options[:bins] ||= 25 unless options[:nr_bins]
+      options[:copy_data] = false unless options.key?(:copy_data)
+      options_map = {
+        :loss => :fun,
+        :factors => :k,
+        :threads => :nr_threads,
+        :bins => :nr_bins,
+        :iterations => :nr_iters,
+        :learning_rate => :eta,
+        :nmf => :do_nmf
+      }
       options.each do |k, v|
+        k = options_map[k] if options_map[k]
         param[k] = v
       end
+      # do_nmf must be true for generalized KL-divergence
+      param[:do_nmf] = true if param[:fun] == 2
       param
     end
 
     def create_problem(data)
+      if data.is_a?(String)
+        # need to expand path so it's absolute
+        return FFI.mf_read_problem(File.expand_path(data))
+      end
+
       raise Error, "No data" if data.empty?
 
-      nodes = []
-      r = ::FFI::MemoryPointer.new(FFI::Node, data.size)
-      data.each_with_index do |row, i|
-        n = FFI::Node.new(r[i])
-        n[:u] = row[0]
-        n[:v] = row[1]
-        n[:r] = row[2]
-        nodes << n
+      # TODO do in C for better performance
+      # can use FIX2INT() and RFLOAT_VALUE() instead of pack
+      buffer = String.new
+      data.each do |row|
+        row[0, 2].pack("i*".freeze, buffer: buffer)
+        row[2, 1].pack("f".freeze, buffer: buffer)
       end
 
-      m = nodes.map { |n| n[:u] }.max + 1
-      n = nodes.map { |n| n[:v] }.max + 1
+      r = ::FFI::MemoryPointer.new(FFI::Node, data.size)
+      r.write_bytes(buffer)
+
+      # double check size is what we expect
+      # FFI will throw an error above if too long
+      raise Error, "Bad buffer size" if r.size != buffer.bytesize
+
+      m = data.max_by { |r| r[0] }[0] + 1
+      n = data.max_by { |r| r[1] }[1] + 1
 
       prob = FFI::Problem.new
       prob[:m] = m
       prob[:n] = n
-      prob[:nnz] = nodes.size
+      prob[:nnz] = data.size
       prob[:r] = r
       prob
     end
-
-    def reshape(arr, dims)
-      rows = dims.first
-      new_arr = rows.times.map { [] }
-      arr.each_with_index do |v, i|
-        new_arr[i % rows] << v
-      end
-      new_arr
-    end
   end
 end

data/lib/libmf/version.rb

@@ -1,3 +1,3 @@
 module Libmf
-  VERSION = "0.1.0"
+  VERSION = "0.2.1"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: libmf
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Andrew Kane
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2019-11-06 00:00:00.000000000 Z
+date: 2020-12-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ffi
@@ -24,103 +24,31 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-- !ruby/object:Gem::Dependency
-  name: bundler
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: rake
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: minitest
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '5'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '5'
-- !ruby/object:Gem::Dependency
-  name: rake-compiler
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-description: 
+description:
 email: andrew@chartkick.com
 executables: []
-extensions:
-- ext/libmf/extconf.rb
+extensions: []
 extra_rdoc_files: []
 files:
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
-- ext/libmf/extconf.rb
-- lib/libmf.bundle
 - lib/libmf.rb
 - lib/libmf/ffi.rb
 - lib/libmf/model.rb
 - lib/libmf/version.rb
-- vendor/libmf/COPYRIGHT
-- vendor/libmf/Makefile
-- vendor/libmf/Makefile.win
-- vendor/libmf/README
-- vendor/libmf/demo/all_one_matrix.te.txt
-- vendor/libmf/demo/all_one_matrix.tr.txt
-- vendor/libmf/demo/binary_matrix.te.txt
-- vendor/libmf/demo/binary_matrix.tr.txt
-- vendor/libmf/demo/demo.bat
-- vendor/libmf/demo/demo.sh
-- vendor/libmf/demo/real_matrix.te.txt
-- vendor/libmf/demo/real_matrix.tr.txt
-- vendor/libmf/mf-predict.cpp
-- vendor/libmf/mf-train.cpp
-- vendor/libmf/mf.cpp
-- vendor/libmf/mf.def
-- vendor/libmf/mf.h
-- vendor/libmf/windows/mf-predict.exe
-- vendor/libmf/windows/mf-train.exe
-- vendor/libmf/windows/mf.dll
+- vendor/COPYRIGHT
+- vendor/demo/real_matrix.te.txt
+- vendor/demo/real_matrix.tr.txt
+- vendor/libmf.arm64.dylib
+- vendor/libmf.dylib
+- vendor/libmf.so
+- vendor/mf.dll
 homepage: https://github.com/ankane/libmf
 licenses:
-- MIT
+- BSD-3-Clause
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -135,8 +63,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
-signing_key: 
+rubygems_version: 3.2.3
+signing_key:
 specification_version: 4
-summary: LIBMF - large-scale sparse matrix factorization - for Ruby
+summary: Large-scale sparse matrix factorization for Ruby
 test_files: []