xlearn 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: cbc492d4f4cb0de9c53cac0820251fc1f747de836348280dfa9d1b7e6475f745
+  data.tar.gz: d5f1fcbbb10b96714c38fd9c0c924c98fb01dccf1872734e1084a31ad855503c
+SHA512:
+  metadata.gz: '048e5915264ba2749e00a91b4c59a773efcd553cf7c764e56df0107e6dd08edcb7bcb86350181b217d095351ea79f47ba6daa84407069fcd9c445683ecdc22a8'
+  data.tar.gz: 46831787724f8ec1d4063859445a0a9e6aefd2a38b4267032eb11ffcadf145ebbd37ab3babcf56599cf31f3f4143126b1663baf409099926860ce88c591adb75

data/CHANGELOG.md

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

data/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.

data/README.md

@@ -0,0 +1,107 @@
+# xLearn
+
+[xLearn](https://github.com/aksnzhy/xlearn) - the high performance machine learning library - for Ruby
+
+:fire: Uses the C API for blazing performance
+
+Supports:
+
+- Linear models
+- Factorization machines
+- Field-aware factorization machines
+
+## Installation
+
+First, [install xLearn](https://xlearn-doc.readthedocs.io/en/latest/install/index.html). On Mac, copy `build/lib/libxlearn_api.dylib` to `/usr/local/lib`.
+
+Add this line to your application’s Gemfile:
+
+```ruby
+gem 'xlearn'
+```
+
+## Getting Started
+
+This library is modeled after the [Python Scikit-learn API](https://xlearn-doc.readthedocs.io/en/latest/python_api/index.html). Some methods are missing at the moment. PRs welcome!
+
+Prep your data
+
+```ruby
+x = [[1, 2], [3, 4], [5, 6], [7, 8]]
+y = [1, 2, 3, 4]
+```
+
+Train a model
+
+```ruby
+model = XLearn::Linear.new(task: "reg")
+model.fit(x, y)
+```
+
+Use `XLearn::FM` for factorization machines and `XLearn::FFM` for field-aware factorization machines
+
+Make predictions
+
+```ruby
+model.predict(x)
+```
+
+Save the model to a file
+
+```ruby
+model.save_model("model.bin")
+```
+
+Load the model from a file
+
+```ruby
+model.load_model("model.bin")
+```
+
+## Parameters
+
+Specify parameters
+
+```ruby
+model = XLearn::FM.new(k: 20, epoch: 50)
+```
+
+Supports the same parameters as [Python](https://xlearn-doc.readthedocs.io/en/latest/all_api/index.html)
+
+## Validation
+
+Pass a validation set when fitting
+
+```ruby
+model.fit(x_train, y_train, eval_set: [x_val, y_val])
+```
+
+## Performance
+
+For performance, you can read data directly from files
+
+```ruby
+model.fit("train.txt", eval_set: "validate.txt")
+model.predict("test.txt")
+```
+
+[These formats](https://xlearn-doc.readthedocs.io/en/latest/python_api/index.html#choose-machine-learning-algorithm) are supported
+
+You can also write predictions directly to a file
+
+```ruby
+model.predict("test.txt", out_file: "predictions.txt")
+```
+
+## History
+
+View the [changelog](https://github.com/ankane/xlearn/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/xlearn/issues)
+- Fix bugs and [submit pull requests](https://github.com/ankane/xlearn/pulls)
+- Write, clarify, or fix documentation
+- Suggest or add new features

data/lib/xlearn.rb

@@ -0,0 +1,28 @@
+# dependencies
+require "ffi"
+
+# stdlib
+require "csv"
+require "fileutils"
+require "tempfile"
+
+# modules
+require "xlearn/utils"
+require "xlearn/dmatrix"
+require "xlearn/model"
+require "xlearn/ffm"
+require "xlearn/fm"
+require "xlearn/linear"
+require "xlearn/version"
+
+module XLearn
+  class Error < StandardError; end
+
+  class << self
+    attr_accessor :ffi_lib
+  end
+  self.ffi_lib = ["xlearn_api"]
+
+  # friendlier error message
+  autoload :FFI, "xlearn/ffi"
+end

data/lib/xlearn/dmatrix.rb

@@ -0,0 +1,35 @@
+module XLearn
+  class DMatrix
+    include Utils
+
+    def initialize(data, label: nil)
+      @handle = ::FFI::MemoryPointer.new(:pointer)
+
+      nrow = data.count
+      ncol = data.first.count
+
+      c_data = ::FFI::MemoryPointer.new(:float, nrow * ncol)
+      c_data.put_array_of_float(0, data.flatten)
+
+      if label
+        c_label = ::FFI::MemoryPointer.new(:float, nrow)
+        c_label.put_array_of_float(0, label)
+      end
+
+      # TODO support this
+      field_map = nil
+
+      check_call FFI.XlearnCreateDataFromMat(c_data, nrow, ncol, c_label, field_map, @handle)
+      ObjectSpace.define_finalizer(self, self.class.finalize(@handle))
+    end
+
+    def to_ptr
+      @handle
+    end
+
+    def self.finalize(pointer)
+      # must use proc instead of stabby lambda
+      proc { FFI.XlearnDataFree(pointer) }
+    end
+  end
+end

data/lib/xlearn/ffi.rb

@@ -0,0 +1,39 @@
+module XLearn
+  module FFI
+    extend ::FFI::Library
+
+    begin
+      ffi_lib XLearn.ffi_lib
+    rescue LoadError => e
+      raise e if ENV["XLEARN_DEBUG"]
+      raise LoadError, "Could not find xLearn"
+    end
+
+    # https://github.com/aksnzhy/xlearn/blob/master/src/c_api/c_api.h
+    # keep same order
+
+    attach_function :XLearnHello, %i[], :int
+    attach_function :XLearnCreate, %i[string pointer], :int
+    attach_function :XlearnCreateDataFromMat, %i[pointer uint32 uint32 pointer pointer pointer], :int
+    attach_function :XlearnDataFree, %i[pointer], :int
+    attach_function :XLearnHandleFree, %i[pointer], :int
+    attach_function :XLearnShow, %i[pointer], :int
+    attach_function :XLearnSetTrain, %i[pointer string], :int
+    attach_function :XLearnSetTest, %i[pointer string], :int
+    attach_function :XLearnSetPreModel, %i[pointer string], :int
+    attach_function :XLearnSetValidate, %i[pointer string], :int
+    attach_function :XLearnSetTXTModel, %i[pointer string], :int
+    attach_function :XLearnFit, %i[pointer string], :int
+    attach_function :XLearnCV, %i[pointer], :int
+    attach_function :XLearnPredictForMat, %i[pointer string pointer pointer], :int
+    attach_function :XLearnPredictForFile, %i[pointer string string], :int
+    attach_function :XLearnSetDMatrix, %i[pointer string pointer], :int
+    attach_function :XLearnSetStr, %i[pointer string string], :int
+    attach_function :XLearnSetInt, %i[pointer string int], :int
+    attach_function :XLearnSetFloat, %i[pointer string float], :int
+    attach_function :XLearnSetBool, %i[pointer string bool], :int
+
+    # errors
+    attach_function :XLearnGetLastError, %i[], :string
+  end
+end

data/lib/xlearn/ffm.rb

@@ -0,0 +1,8 @@
+module XLearn
+  class FFM < Model
+    def initialize(**options)
+      @model_type = "ffm"
+      super
+    end
+  end
+end

data/lib/xlearn/fm.rb

@@ -0,0 +1,8 @@
+module XLearn
+  class FM < Model
+    def initialize(**options)
+      @model_type = "fm"
+      super
+    end
+  end
+end

data/lib/xlearn/linear.rb

@@ -0,0 +1,8 @@
+module XLearn
+  class Linear < Model
+    def initialize(**options)
+      @model_type = "linear"
+      super
+    end
+  end
+end

data/lib/xlearn/model.rb

@@ -0,0 +1,104 @@
+module XLearn
+  class Model
+    include Utils
+
+    def initialize(**options)
+      @handle = ::FFI::MemoryPointer.new(:pointer)
+      check_call FFI.XLearnCreate(@model_type, @handle)
+      ObjectSpace.define_finalizer(self, self.class.finalize(@handle))
+
+      options = {
+        task: "binary",
+        quiet: true
+      }.merge(options)
+
+      if options[:task] == "binary" && !options.key?(:sigmoid)
+        options[:sigmoid] = true
+      end
+
+      set_params(options)
+    end
+
+    def fit(x, y = nil, eval_set: nil)
+      if x.is_a?(String)
+        check_call FFI.XLearnSetTrain(@handle, x)
+        check_call FFI.XLearnSetBool(@handle, "from_file", true)
+      else
+        train_set = DMatrix.new(x, label: y)
+        check_call FFI.XLearnSetDMatrix(@handle, "train", train_set)
+        check_call FFI.XLearnSetBool(@handle, "from_file", false)
+      end
+
+      if eval_set
+        if eval_set.is_a?(String)
+          check_call FFI.XLearnSetValidate(@handle, eval_set)
+        else
+          valid_set = DMatrix.new(x, label: y)
+          check_call FFI.XLearnSetDMatrix(@handle, "validate", valid_set)
+        end
+      end
+
+      # TODO unlink in finalizer
+      @model_file = Tempfile.new("xlearn")
+      check_call FFI.XLearnFit(@handle, @model_file.path)
+    end
+
+    def predict(x, out_path: nil)
+      if x.is_a?(String)
+        check_call FFI.XLearnSetTest(@handle, x)
+        check_call FFI.XLearnSetBool(@handle, "from_file", true)
+      else
+        test_set = DMatrix.new(x)
+        check_call FFI.XLearnSetDMatrix(@handle, "test", test_set)
+        check_call FFI.XLearnSetBool(@handle, "from_file", false)
+      end
+
+      if out_path
+        check_call FFI.XLearnPredictForFile(@handle, @model_file.path, out_path)
+      else
+        length = ::FFI::MemoryPointer.new(:uint64)
+        out_arr = ::FFI::MemoryPointer.new(:pointer)
+        check_call FFI.XLearnPredictForMat(@handle, @model_file.path, length, out_arr)
+        out_arr.read_pointer.read_array_of_float(length.read_uint64)
+      end
+    end
+
+    def save_model(path)
+      raise Error, "Not trained" unless @model_file
+      FileUtils.cp(@model_file.path, path)
+    end
+
+    def load_model(path)
+      @model_file ||= Tempfile.new("xlearn")
+      # TODO ensure tempfile is still cleaned up
+      FileUtils.cp(path, @model_file.path)
+    end
+
+    def self.finalize(pointer)
+      # must use proc instead of stabby lambda
+      proc { FFI.XLearnHandleFree(pointer) }
+    end
+
+    private
+
+    def set_params(params)
+      params.each do |k, v|
+        k = k.to_s
+        ret =
+          case k
+          when "task", "metric", "opt", "log"
+            FFI.XLearnSetStr(@handle, k, v)
+          when "lr", "lambda", "init", "alpha", "beta", "lambda_1", "lambda_2"
+            FFI.XLearnSetFloat(@handle, k, v)
+          when "k", "epoch", "fold", "nthread", "block_size", "stop_window", "seed"
+            FFI.XLearnSetInt(@handle, k, v)
+          when "quiet", "on_disk", "bin_out", "norm", "lock_free", "early_stop", "sign", "sigmoid"
+            FFI.XLearnSetBool(@handle, k, v)
+          else
+            raise ArgumentError, "Invalid parameter: #{k}"
+          end
+        check_call ret
+      end
+    end
+  end
+end

data/lib/xlearn/utils.rb

@@ -0,0 +1,9 @@
+module XLearn
+  module Utils
+    private
+
+    def check_call(ret)
+      raise Error, FFI.XLearnGetLastError if ret != 0
+    end
+  end
+end

data/lib/xlearn/version.rb

@@ -0,0 +1,3 @@
+module XLearn
+  VERSION = "0.1.0"
+end

metadata

@@ -0,0 +1,110 @@
+--- !ruby/object:Gem::Specification
+name: xlearn
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Andrew Kane
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2019-10-12 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ffi
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !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'
+description: 
+email: andrew@chartkick.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/xlearn.rb
+- lib/xlearn/dmatrix.rb
+- lib/xlearn/ffi.rb
+- lib/xlearn/ffm.rb
+- lib/xlearn/fm.rb
+- lib/xlearn/linear.rb
+- lib/xlearn/model.rb
+- lib/xlearn/utils.rb
+- lib/xlearn/version.rb
+homepage: https://github.com/ankane/xlearn
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3
+signing_key: 
+specification_version: 4
+summary: xLearn - the high performance machine learning library - for Ruby
+test_files: []