rumale-nearest_neighbors 0.24.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: df277519a7d271e0bdf9fef8076a2ebb2476817dc2d9f3ca5076b2e0b0ac5b52
+  data.tar.gz: 8399d40f09a44e36c71a444c3d44ad5e419b42e0380dee531c68da3f484a8ab3
+SHA512:
+  metadata.gz: 9322178b341aa9a76e30ed13dec1e2711d75aea6868934f1cf47401f4e335d01290baa707ec2dcc0e94f8a15fb3d4b8eff1db65ef64bc65edab095c5e2df5d57
+  data.tar.gz: b0f554518ae703b23e21adc6c039f79e7e84da3b4c4a95f9776e38bd1a84fa468f7a60aeee30b0f3177d82630f739b9609e99da5c521b13366b88f685a3dd628

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,33 @@
+# Rumale::NearestNeighbors
+
+[![Gem Version](https://badge.fury.io/rb/rumale-nearest_neighbors.svg)](https://badge.fury.io/rb/rumale-nearest_neighbors)
+[![BSD 3-Clause License](https://img.shields.io/badge/License-BSD%203--Clause-orange.svg)](https://github.com/yoshoku/rumale/blob/main/rumale-nearest_neighbors/LICENSE.txt)
+[![Documentation](https://img.shields.io/badge/api-reference-blue.svg)](https://yoshoku.github.io/rumale/doc/Rumale/NearestNeighbors.html)
+
+Rumale is a machine learning library in Ruby.
+Rumale::NearestNeighbors provides classifier and regression based on nearest neighbors rule
+with Rumale interface.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'rumale-nearest_neighbors'
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install rumale-nearest_neighbors
+
+## Documentation
+
+- [Rumale API Documentation - NearestNeighbors](https://yoshoku.github.io/rumale/doc/Rumale/NearestNeighbors.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/nearest_neighbors/k_neighbors_classifier.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require 'rumale/base/estimator'
+require 'rumale/base/classifier'
+require 'rumale/pairwise_metric'
+require 'rumale/validation'
+
+module Rumale
+  # This module consists of the classes that implement estimators based on nearest neighbors rule.
+  module NearestNeighbors
+    # KNeighborsClassifier is a class that implements the classifier with the k-nearest neighbors rule.
+    # The current implementation uses the Euclidean distance for finding the neighbors.
+    #
+    # @example
+    #   require 'rumale/nearest_neighbors/k_neighbors_classifier'
+    #
+    #   estimator =
+    #     Rumale::NearestNeighbors::KNeighborsClassifier.new(n_neighbors: 5)
+    #   estimator.fit(training_samples, traininig_labels)
+    #   results = estimator.predict(testing_samples)
+    #
+    class KNeighborsClassifier < ::Rumale::Base::Estimator
+      include ::Rumale::Base::Classifier
+
+      # Return the prototypes for the nearest neighbor classifier.
+      # If the metric is 'precomputed', that returns nil.
+      # @return [Numo::DFloat] (shape: [n_training_samples, n_features])
+      attr_reader :prototypes
+
+      # Return the labels of the prototypes
+      # @return [Numo::Int32] (size: n_training_samples)
+      attr_reader :labels
+
+      # Return the class labels.
+      # @return [Numo::Int32] (size: n_classes)
+      attr_reader :classes
+
+      # Create a new classifier with the nearest neighbor rule.
+      #
+      # @param n_neighbors [Integer] The number of neighbors.
+      # @param metric [String] The metric to calculate the distances.
+      #   If metric is 'euclidean', Euclidean distance is calculated for distance between points.
+      #   If metric is 'precomputed', the fit and predict methods expect to be given a distance matrix.
+      def initialize(n_neighbors: 5, metric: 'euclidean')
+        super()
+        @params = {
+          n_neighbors: n_neighbors,
+          metric: (metric == 'precomputed' ? 'precomputed' : 'euclidean')
+        }
+      end
+
+      # Fit the model with given training data.
+      #
+      # @param x [Numo::DFloat] (shape: [n_training_samples, n_features]) The training data to be used for fitting the model.
+      #   If the metric is 'precomputed', x must be a square distance matrix (shape: [n_training_samples, n_training_samples]).
+      # @param y [Numo::Int32] (shape: [n_training_samples]) The labels to be used for fitting the model.
+      # @return [KNeighborsClassifier] The learned classifier itself.
+      def fit(x, y)
+        x = ::Rumale::Validation.check_convert_sample_array(x)
+        y = ::Rumale::Validation.check_convert_label_array(y)
+        ::Rumale::Validation.check_sample_size(x, y)
+        if @params[:metric] == 'precomputed' && x.shape[0] != x.shape[1]
+          raise ArgumentError, 'Expect the input distance matrix to be square.'
+        end
+
+        @prototypes = x.dup if @params[:metric] == 'euclidean'
+        @labels = Numo::Int32.asarray(y.to_a)
+        @classes = Numo::Int32.asarray(y.to_a.uniq.sort)
+        self
+      end
+
+      # Calculate confidence scores for samples.
+      #
+      # @param x [Numo::DFloat] (shape: [n_testing_samples, n_features]) The samples to compute the scores.
+      #   If the metric is 'precomputed', x must be a square distance matrix (shape: [n_testing_samples, n_training_samples]).
+      # @return [Numo::DFloat] (shape: [n_testing_samples, n_classes]) Confidence scores per sample for each class.
+      def decision_function(x)
+        x = ::Rumale::Validation.check_convert_sample_array(x)
+        if @params[:metric] == 'precomputed' && x.shape[1] != @labels.size
+          raise ArgumentError, 'Expect the size input matrix to be n_testing_samples-by-n_training_samples.'
+        end
+
+        n_prototypes = @labels.size
+        n_neighbors = [@params[:n_neighbors], n_prototypes].min
+        n_samples = x.shape[0]
+        n_classes = @classes.size
+        scores = Numo::DFloat.zeros(n_samples, n_classes)
+
+        distance_matrix = @params[:metric] == 'precomputed' ? x : ::Rumale::PairwiseMetric.euclidean_distance(x, @prototypes)
+        n_samples.times do |m|
+          neighbor_ids = distance_matrix[m, true].to_a.each_with_index.sort.map(&:last)[0...n_neighbors]
+          neighbor_ids.each { |n| scores[m, @classes.to_a.index(@labels[n])] += 1.0 }
+        end
+
+        scores
+      end
+
+      # Predict class labels for samples.
+      #
+      # @param x [Numo::DFloat] (shape: [n_testing_samples, n_features]) The samples to predict the labels.
+      #   If the metric is 'precomputed', x must be a square distance matrix (shape: [n_testing_samples, n_training_samples]).
+      # @return [Numo::Int32] (shape: [n_testing_samples]) Predicted class label per sample.
+      def predict(x)
+        x = ::Rumale::Validation.check_convert_sample_array(x)
+        if @params[:metric] == 'precomputed' && x.shape[1] != @labels.size
+          raise ArgumentError, 'Expect the size input matrix to be n_samples-by-n_training_samples.'
+        end
+
+        decision_values = decision_function(x)
+        n_samples = x.shape[0]
+        Numo::Int32.asarray(Array.new(n_samples) { |n| @classes[decision_values[n, true].max_index] })
+      end
+    end
+  end
+end

data/lib/rumale/nearest_neighbors/k_neighbors_regressor.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require 'rumale/base/estimator'
+require 'rumale/base/regressor'
+require 'rumale/pairwise_metric'
+require 'rumale/validation'
+
+module Rumale
+  module NearestNeighbors
+    # KNeighborsRegressor is a class that implements the regressor with the k-nearest neighbors rule.
+    # The current implementation uses the Euclidean distance for finding the neighbors.
+    #
+    # @example
+    #   require 'rumale/nearest_neighbors/k_neighbors_regressor'
+    #
+    #   estimator =
+    #     Rumale::NearestNeighbors::KNeighborsRegressor.new(n_neighbors: 5)
+    #   estimator.fit(training_samples, traininig_target_values)
+    #   results = estimator.predict(testing_samples)
+    #
+    class KNeighborsRegressor < ::Rumale::Base::Estimator
+      include ::Rumale::Base::Regressor
+
+      # Return the prototypes for the nearest neighbor regressor.
+      # If the metric is 'precomputed', that returns nil.
+      # If the algorithm is 'vptree', that returns Rumale::NearestNeighbors::VPTree.
+      # @return [Numo::DFloat] (shape: [n_training_samples, n_features])
+      attr_reader :prototypes
+
+      # Return the values of the prototypes
+      # @return [Numo::DFloat] (shape: [n_training_samples, n_outputs])
+      attr_reader :values
+
+      # Create a new regressor with the nearest neighbor rule.
+      #
+      # @param n_neighbors [Integer] The number of neighbors.
+      # @param metric [String] The metric to calculate the distances.
+      #   If metric is 'euclidean', Euclidean distance is calculated for distance between points.
+      #   If metric is 'precomputed', the fit and predict methods expect to be given a distance matrix.
+      def initialize(n_neighbors: 5, metric: 'euclidean')
+        super()
+        @params = {
+          n_neighbors: n_neighbors,
+          metric: (metric == 'precomputed' ? 'precomputed' : 'euclidean')
+        }
+      end
+
+      # Fit the model with given training data.
+      #
+      # @param x [Numo::DFloat] (shape: [n_training_samples, n_features]) The training data to be used for fitting the model.
+      #   If the metric is 'precomputed', x must be a square distance matrix (shape: [n_training_samples, n_training_samples]).
+      # @param y [Numo::DFloat] (shape: [n_training_samples, n_outputs]) The target values to be used for fitting the model.
+      # @return [KNeighborsRegressor] The learned regressor itself.
+      def fit(x, y)
+        x = ::Rumale::Validation.check_convert_sample_array(x)
+        y = ::Rumale::Validation.check_convert_target_value_array(y)
+        ::Rumale::Validation.check_sample_size(x, y)
+        if @params[:metric] == 'precomputed' && x.shape[0] != x.shape[1]
+          raise ArgumentError, 'Expect the input distance matrix to be square.'
+        end
+
+        @prototypes = x.dup if @params[:metric] == 'euclidean'
+        @values = y.dup
+        self
+      end
+
+      # Predict values for samples.
+      #
+      # @param x [Numo::DFloat] (shape: [n_testing_samples, n_features]) The samples to predict the values.
+      #   If the metric is 'precomputed', x must be a square distance matrix (shape: [n_testing_samples, n_training_samples]).
+      # @return [Numo::DFloat] (shape: [n_testing_samples, n_outputs]) Predicted values per sample.
+      def predict(x)
+        x = ::Rumale::Validation.check_convert_sample_array(x)
+        if @params[:metric] == 'precomputed' && x.shape[1] != @values.shape[0]
+          raise ArgumentError, 'Expect the size input matrix to be n_testing_samples-by-n_training_samples.'
+        end
+
+        # Initialize some variables.
+        n_samples = x.shape[0]
+        n_prototypes, n_outputs = @values.shape
+        n_neighbors = [@params[:n_neighbors], n_prototypes].min
+        # Predict values for the given samples.
+        distance_matrix = @params[:metric] == 'precomputed' ? x : ::Rumale::PairwiseMetric.euclidean_distance(x, @prototypes)
+        predicted_values = Array.new(n_samples) do |n|
+          neighbor_ids = distance_matrix[n, true].to_a.each_with_index.sort.map(&:last)[0...n_neighbors]
+          n_outputs.nil? ? @values[neighbor_ids].mean : @values[neighbor_ids, true].mean(0).to_a
+        end
+        Numo::DFloat[*predicted_values]
+      end
+    end
+  end
+end

data/lib/rumale/nearest_neighbors/version.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+# Rumale is a machine learning library in Ruby.
+module Rumale
+  # This module consists of the classes that implement estimators based on nearest neighbors rule.
+  module NearestNeighbors
+    # @!visibility private
+    VERSION = '0.24.0'
+  end
+end

data/lib/rumale/nearest_neighbors.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require 'numo/narray'
+
+require_relative 'nearest_neighbors/k_neighbors_classifier'
+require_relative 'nearest_neighbors/k_neighbors_regressor'
+require_relative 'nearest_neighbors/version'

metadata

@@ -0,0 +1,86 @@
+--- !ruby/object:Gem::Specification
+name: rumale-nearest_neighbors
+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::NearestNeighbors provides classifier and regression based on
+  nearest neighbors rule with Rumale interface.
+
+  '
+email:
+- yoshoku@outlook.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/rumale/nearest_neighbors.rb
+- lib/rumale/nearest_neighbors/k_neighbors_classifier.rb
+- lib/rumale/nearest_neighbors/k_neighbors_regressor.rb
+- lib/rumale/nearest_neighbors/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-nearest_neighbors
+  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::NearestNeighbors provides classifier and regression based on nearest
+  neighbors rule with Rumale interface.
+test_files: []