rumale-kernel_approximation 0.24.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 30bd034634876366a9bcb1c4aad391a8447b2b6e4c9c11ef2626c20a55d5fbf6
+  data.tar.gz: bd072bc7a8927e5702ff4ec3bce9e2b289672d31bdab8503fcd77045a6d5d3eb
+SHA512:
+  metadata.gz: ab986c1eac6cc07412dbbcf025f5951ba42f6cf1f93cc4b9c7dcf7c815b0834a7ba24aa713999a0b97b0f4e065e4f2e705238baaca83a91cca0bf5c8cea5771f
+  data.tar.gz: 2c6abdd6c60d68353da3745a32338daa782ac84a1f1cd47e08816ea393a35d7d5199dfcdca0af4dede04bb5b95291cdc2424a01e69ba1734f3291c18d44d027a

data/LICENSE.txt

@@ -0,0 +1,27 @@
+Copyright (c) 2022 Atsushi Tatsuma
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* 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.
+
+* 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

@@ -0,0 +1,34 @@
+# Rumale::KernelApproximation
+
+[![Gem Version](https://badge.fury.io/rb/rumale-kernel_approximation.svg)](https://badge.fury.io/rb/rumale-kernel_approximation)
+[![BSD 3-Clause License](https://img.shields.io/badge/License-BSD%203--Clause-orange.svg)](https://github.com/yoshoku/rumale/blob/main/rumale-kernel_approximation/LICENSE.txt)
+[![Documentation](https://img.shields.io/badge/api-reference-blue.svg)](https://yoshoku.github.io/rumale/doc/Rumale/KernelApproximation.html)
+
+Rumale is a machine learning library in Ruby.
+Rumale::KernelApproximation provides kernel approximation algorithms,
+such as RBF feature mapping and Nystroem method,
+with Rumale interface.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'rumale-kernel_approximation'
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install rumale-kernel_approximation
+
+## Documentation
+
+- [Rumale API Documentation - KernelApproximation](https://yoshoku.github.io/rumale/doc/Rumale/KernelApproximation.html)
+
+## License
+
+The gem is available as open source under the terms of the [BSD-3-Clause License](https://opensource.org/licenses/BSD-3-Clause).

data/lib/rumale/kernel_approximation/nystroem.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require 'rumale/base/estimator'
+require 'rumale/base/transformer'
+require 'rumale/pairwise_metric'
+require 'rumale/validation'
+
+module Rumale
+  module KernelApproximation
+    # Nystroem is a class that implements feature mapping with Nystroem method.
+    #
+    # @example
+    #   require 'numo/linalg/autoloader'
+    #   require 'rumale/kernel_approximation/nystroem'
+    #
+    #   transformer = Rumale::KernelApproximation::Nystroem.new(kernel: 'rbf', gamma: 1, n_components: 128, random_seed: 1)
+    #   new_training_samples = transformer.fit_transform(training_samples)
+    #   new_testing_samples = transformer.transform(testing_samples)
+    #
+    # *Reference*
+    # - Yang, T., Li, Y., Mahdavi, M., Jin, R., and Zhou, Z-H., "Nystrom Method vs Random Fourier Features: A Theoretical and Empirical Comparison," Advances in NIPS'12, Vol. 1, pp. 476--484, 2012.
+    class Nystroem < ::Rumale::Base::Estimator
+      include ::Rumale::Base::Transformer
+
+      # Returns the randomly sampled training data for feature mapping.
+      # @return [Numo::DFloat] (shape: n_components, n_features])
+      attr_reader :components
+
+      # Returns the indices sampled training data.
+      # @return [Numo::Int32] (shape: [n_components])
+      attr_reader :component_indices
+
+      # Returns the normalizing factors.
+      # @return [Numo::DFloat] (shape: [n_components, n_components])
+      attr_reader :normalizer
+
+      # Return the random generator for transformation.
+      # @return [Random]
+      attr_reader :rng
+
+      # Create a new transformer for mapping to kernel feature space with Nystrom method.
+      #
+      # @param kernel [String] The type of kernel function ('rbf', 'linear', 'poly', and 'sigmoid)
+      # @param gamma [Float] The gamma parameter in rbf/poly/sigmoid kernel function.
+      # @param degree [Integer] The degree parameter in polynomial kernel function.
+      # @param coef [Float] The coefficient in poly/sigmoid kernel function.
+      # @param n_components [Integer] The number of dimensions of the kernel feature space.
+      # @param random_seed [Integer] The seed value using to initialize the random generator.
+      def initialize(kernel: 'rbf', gamma: 1, degree: 3, coef: 1, n_components: 100, random_seed: nil)
+        super()
+        @params = {
+          kernel: kernel,
+          gamma: gamma,
+          degree: degree,
+          coef: coef,
+          n_components: n_components,
+          random_seed: (random_seed || srand)
+        }
+        @rng = Random.new(@params[:random_seed])
+      end
+
+      # Fit the model with given training data.
+      #
+      # @overload fit(x) -> Nystroem
+      #   @param x [Numo::NArray] (shape: [n_samples, n_features]) The training data to be used for fitting the model.
+      #   @return [Nystroem] The learned transformer itself.
+      def fit(x, _y = nil)
+        x = ::Rumale::Validation.check_convert_sample_array(x)
+        raise 'Nystroem#fit requires Numo::Linalg but that is not loaded.' unless enable_linalg?(warning: false)
+
+        # initialize some variables.
+        sub_rng = @rng.dup
+        n_samples = x.shape[0]
+        n_components = [1, [@params[:n_components], n_samples].min].max
+
+        # random sampling.
+        @component_indices = Numo::Int32.cast(Array(0...n_samples).shuffle(random: sub_rng)[0...n_components])
+        @components = x[@component_indices, true].dup
+
+        # calculate normalizing factor.
+        kernel_mat = kernel_mat(@components)
+        eig_vals, eig_vecs = Numo::Linalg.eigh(kernel_mat)
+        la = eig_vals.class.maximum(eig_vals.reverse, 1e-12)
+        u = eig_vecs.reverse(1)
+        @normalizer = u.dot((1.0 / Numo::NMath.sqrt(la)).diag)
+
+        self
+      end
+
+      # Fit the model with training data, and then transform them with the learned model.
+      #
+      # @overload fit_transform(x) -> Numo::DFloat
+      #   @param x [Numo::DFloat] (shape: [n_samples, n_features]) The training data to be used for fitting the model.
+      #   @return [Numo::DFloat] (shape: [n_samples, n_components]) The transformed data
+      def fit_transform(x, _y = nil)
+        x = ::Rumale::Validation.check_convert_sample_array(x)
+
+        fit(x).transform(x)
+      end
+
+      # Transform the given data with the learned model.
+      #
+      # @param x [Numo::DFloat] (shape: [n_samples, n_features]) The data to be transformed with the learned model.
+      # @return [Numo::DFloat] (shape: [n_samples, n_components]) The transformed data.
+      def transform(x)
+        x = ::Rumale::Validation.check_convert_sample_array(x)
+
+        z = kernel_mat(x, @components)
+        z.dot(@normalizer)
+      end
+
+      private
+
+      def kernel_mat(x, y = nil)
+        case @params[:kernel]
+        when 'rbf'
+          ::Rumale::PairwiseMetric.rbf_kernel(x, y, @params[:gamma])
+        when 'poly'
+          ::Rumale::PairwiseMetric.polynomial_kernel(x, y, @params[:degree], @params[:gamma], @params[:coef])
+        when 'sigmoid'
+          ::Rumale::PairwiseMetric.sigmoid_kernel(x, y, @params[:gamma], @params[:coef])
+        when 'linear'
+          ::Rumale::PairwiseMetric.linear_kernel(x, y)
+        else
+          raise ArgumentError, "Expect kernel parameter to be given 'rbf', 'linear', 'poly', or 'sigmoid'."
+        end
+      end
+    end
+  end
+end

data/lib/rumale/kernel_approximation/rbf.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require 'rumale/base/estimator'
+require 'rumale/base/transformer'
+require 'rumale/utils'
+require 'rumale/validation'
+
+module Rumale
+  module KernelApproximation
+    # Class for RBF kernel feature mapping.
+    #
+    # @example
+    #   require 'rumale/kernel_approximation/rbf'
+    #
+    #   transformer = Rumale::KernelApproximation::RBF.new(gamma: 1.0, n_components: 128, random_seed: 1)
+    #   new_training_samples = transformer.fit_transform(training_samples)
+    #   new_testing_samples = transformer.transform(testing_samples)
+    #
+    # *Refernce*:
+    # - Rahimi, A., and Recht, B., "Random Features for Large-Scale Kernel Machines," Proc. NIPS'07, pp.1177--1184, 2007.
+    class RBF < ::Rumale::Base::Estimator
+      include ::Rumale::Base::Transformer
+
+      # Return the random matrix for transformation.
+      # @return [Numo::DFloat] (shape: [n_features, n_components])
+      attr_reader :random_mat
+
+      # Return the random vector for transformation.
+      # @return [Numo::DFloat] (shape: [n_components])
+      attr_reader :random_vec
+
+      # Return the random generator for transformation.
+      # @return [Random]
+      attr_reader :rng
+
+      # Create a new transformer for mapping to RBF kernel feature space.
+      #
+      # @param gamma [Float] The parameter of RBF kernel: exp(-gamma * x^2).
+      # @param n_components [Integer] The number of dimensions of the RBF kernel feature space.
+      # @param random_seed [Integer] The seed value using to initialize the random generator.
+      def initialize(gamma: 1.0, n_components: 128, random_seed: nil)
+        super()
+        @params = {
+          gamma: gamma,
+          n_components: n_components,
+          random_seed: (random_seed || srand)
+        }
+        @rng = Random.new(@params[:random_seed])
+      end
+
+      # Fit the model with given training data.
+      #
+      # @overload fit(x) -> RBF
+      #   @param x [Numo::NArray] (shape: [n_samples, n_features]) The training data to be used for fitting the model.
+      #     This method uses only the number of features of the data.
+      #   @return [RBF] The learned transformer itself.
+      def fit(x, _y = nil)
+        x = ::Rumale::Validation.check_convert_sample_array(x)
+
+        n_features = x.shape[1]
+        sub_rng = @rng.dup
+        @params[:n_components] = 2 * n_features if @params[:n_components] <= 0
+        @random_mat = ::Rumale::Utils.rand_normal([n_features, @params[:n_components]], sub_rng) * (2.0 * @params[:gamma])**0.5
+        n_half_components = @params[:n_components] / 2
+        @random_vec = Numo::DFloat.zeros(@params[:n_components] - n_half_components).concatenate(
+          Numo::DFloat.ones(n_half_components) * (0.5 * Math::PI)
+        )
+        self
+      end
+
+      # Fit the model with training data, and then transform them with the learned model.
+      #
+      # @overload fit_transform(x) -> Numo::DFloat
+      #   @param x [Numo::DFloat] (shape: [n_samples, n_features]) The training data to be used for fitting the model.
+      #   @return [Numo::DFloat] (shape: [n_samples, n_components]) The transformed data
+      def fit_transform(x, _y = nil)
+        x = ::Rumale::Validation.check_convert_sample_array(x)
+
+        fit(x).transform(x)
+      end
+
+      # Transform the given data with the learned model.
+      #
+      # @overload transform(x) -> Numo::DFloat
+      #   @param x [Numo::DFloat] (shape: [n_samples, n_features]) The data to be transformed with the learned model.
+      #   @return [Numo::DFloat] (shape: [n_samples, n_components]) The transformed data.
+      def transform(x)
+        x = ::Rumale::Validation.check_convert_sample_array(x)
+
+        n_samples, = x.shape
+        projection = x.dot(@random_mat) + @random_vec.tile(n_samples, 1)
+        Numo::NMath.sin(projection) * ((2.0 / @params[:n_components])**0.5)
+      end
+    end
+  end
+end

data/lib/rumale/kernel_approximation/version.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+# Rumale is a machine learning library in Ruby.
+module Rumale
+  # Module for kernel approximation algorithms.
+  module KernelApproximation
+    # @!visibility private
+    VERSION = '0.24.0'
+  end
+end

data/lib/rumale/kernel_approximation.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require 'numo/narray'
+
+require_relative 'kernel_approximation/nystroem'
+require_relative 'kernel_approximation/rbf'
+require_relative 'kernel_approximation/version'

metadata

@@ -0,0 +1,86 @@
+--- !ruby/object:Gem::Specification
+name: rumale-kernel_approximation
+version: !ruby/object:Gem::Version
+  version: 0.24.0
+platform: ruby
+authors:
+- yoshoku
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2022-12-31 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: numo-narray
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.9.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.9.1
+- !ruby/object:Gem::Dependency
+  name: rumale-core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.24.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.24.0
+description: |
+  Rumale::KernelApproximation provides kernel approximation algorithms,
+  such as RBF feature mapping and Nystroem method,
+  with Rumale interface.
+email:
+- yoshoku@outlook.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/rumale/kernel_approximation.rb
+- lib/rumale/kernel_approximation/nystroem.rb
+- lib/rumale/kernel_approximation/rbf.rb
+- lib/rumale/kernel_approximation/version.rb
+homepage: https://github.com/yoshoku/rumale
+licenses:
+- BSD-3-Clause
+metadata:
+  homepage_uri: https://github.com/yoshoku/rumale
+  source_code_uri: https://github.com/yoshoku/rumale/tree/main/rumale-kernel_approximation
+  changelog_uri: https://github.com/yoshoku/rumale/blob/main/CHANGELOG.md
+  documentation_uri: https://yoshoku.github.io/rumale/doc/
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.26
+signing_key:
+specification_version: 4
+summary: Rumale::KernelApproximation provides kernel approximation algorithms with
+  Rumale interface.
+test_files: []