rumale 0.19.0 → 0.19.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1cd1cdc16e6c72743d064db7d254c74eb98ca33e97cfdf9e8a76cc1fbe5dd29b
-  data.tar.gz: 2077cae2629f2c403cc0afc415dc4b4151a2eac2ab7a3230402bf761bb653829
+  metadata.gz: f49170105721cfebcae9f1a424e9a858650d78225541a8cb63b0ad4c70734988
+  data.tar.gz: ecc35086328eee1066252e75b8cd638256039e93beebc0bce5714493fe72570b
 SHA512:
-  metadata.gz: 2bbcdce6d0a31c95500a81a7d4a55407786068fac65ce1e5ede1bc3f56d97b2ec93fd9ca1dc52fc1a24782dba469099b25d0398a5993716da011851f18f8179c
-  data.tar.gz: cc9fc19ea73dfa76e8ede18df7cb57f931cccdea2c546f414746ed681afbd272e3866913c75534bbdce6b275d057baa2c793b4046c8e46f697e30d5b87dba066
+  metadata.gz: 68f432bb34ff6c8e467a91d7c7e3aa07e816c2dd8807defc9e4e82e7a720c925062dbd27c8a7ec3294ecef2d71041baead2510edaf03a1eee210dc811eede22d
+  data.tar.gz: 5854eacc12de6c3cdcdbab0f9b4e73fc64d1be0533732348da6b4d6dcb0be9f115e2415501b05148fd021fa844ac0c25adc1bb858432a02ca6fe19d30a3538c7

data/CHANGELOG.md

@@ -1,3 +1,7 @@
+# 0.19.1
+- Add cluster analysis class for [mini-batch K-Means](https://yoshoku.github.io/rumale/doc/Rumale/Clustering/MiniBatchKMeans.html).
+- Fix some typos.
+
 # 0.19.0
 - Change mmh3 and mopti gem to non-runtime dependent library.
   - The mmh3 gem is used in [FeatureHasher](https://yoshoku.github.io/rumale/doc/Rumale/FeatureExtraction/FeatureHasher.html).

data/lib/rumale.rb

@@ -70,6 +70,7 @@ require 'rumale/ensemble/random_forest_regressor'
 require 'rumale/ensemble/extra_trees_classifier'
 require 'rumale/ensemble/extra_trees_regressor'
 require 'rumale/clustering/k_means'
+require 'rumale/clustering/mini_batch_k_means'
 require 'rumale/clustering/k_medoids'
 require 'rumale/clustering/gaussian_mixture'
 require 'rumale/clustering/dbscan'

data/lib/rumale/clustering/mini_batch_k_means.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require 'rumale/base/base_estimator'
+require 'rumale/base/cluster_analyzer'
+require 'rumale/pairwise_metric'
+
+module Rumale
+  module Clustering
+    # MniBatchKMeans is a class that implements K-Means cluster analysis
+    # with mini-batch stochastic gradient descent (SGD).
+    #
+    # @example
+    #   analyzer = Rumale::Clustering::MiniBatchKMeans.new(n_clusters: 10, max_iter: 50, batch_size: 50, random_seed: 1)
+    #   cluster_labels = analyzer.fit_predict(samples)
+    #
+    # *Reference*
+    # - Sculley, D., "Web-scale k-means clustering," Proc. WWW'10, pp. 1177--1178, 2010.
+    class MiniBatchKMeans
+      include Base::BaseEstimator
+      include Base::ClusterAnalyzer
+
+      # Return the centroids.
+      # @return [Numo::DFloat] (shape: [n_clusters, n_features])
+      attr_reader :cluster_centers
+
+      # Return the random generator.
+      # @return [Random]
+      attr_reader :rng
+
+      # Create a new cluster analyzer with K-Means method with mini-batch SGD.
+      #
+      # @param n_clusters [Integer] The number of clusters.
+      # @param init [String] The initialization method for centroids ('random' or 'k-means++').
+      # @param max_iter [Integer] The maximum number of iterations.
+      # @param batch_size [Integer] The size of the mini batches.
+      # @param tol [Float] The tolerance of termination criterion.
+      # @param random_seed [Integer] The seed value using to initialize the random generator.
+      def initialize(n_clusters: 8, init: 'k-means++', max_iter: 100, batch_size: 100, tol: 1.0e-4, random_seed: nil)
+        check_params_numeric(n_clusters: n_clusters, max_iter: max_iter, batch_size: batch_size, tol: tol)
+        check_params_string(init: init)
+        check_params_numeric_or_nil(random_seed: random_seed)
+        check_params_positive(n_clusters: n_clusters, max_iter: max_iter)
+        @params = {}
+        @params[:n_clusters] = n_clusters
+        @params[:init] = init == 'random' ? 'random' : 'k-means++'
+        @params[:max_iter] = max_iter
+        @params[:batch_size] = batch_size
+        @params[:tol] = tol
+        @params[:random_seed] = random_seed
+        @params[:random_seed] ||= srand
+        @cluster_centers = nil
+        @rng = Random.new(@params[:random_seed])
+      end
+
+      # Analysis clusters with given training data.
+      #
+      # @overload fit(x) -> MiniBatchKMeans
+      #
+      # @param x [Numo::DFloat] (shape: [n_samples, n_features]) The training data to be used for cluster analysis.
+      # @return [KMeans] The learned cluster analyzer itself.
+      def fit(x, _y = nil)
+        x = check_convert_sample_array(x)
+        # initialization.
+        n_samples = x.shape[0]
+        update_counter = Numo::Int32.zeros(@params[:n_clusters])
+        sub_rng = @rng.dup
+        init_cluster_centers(x, sub_rng)
+        # optimization with mini-batch sgd.
+        @params[:max_iter].times do |_t|
+          sample_ids = [*0...n_samples].shuffle(random: sub_rng)
+          old_centers = @cluster_centers.dup
+          until (subset_ids = sample_ids.shift(@params[:batch_size])).empty?
+            # sub sampling
+            sub_x = x[subset_ids, true]
+            # assign nearest centroids
+            cluster_labels = assign_cluster(sub_x)
+            # update centroids
+            @params[:n_clusters].times do |c|
+              assigned_bits = cluster_labels.eq(c)
+              next unless assigned_bits.count.positive?
+
+              update_counter[c] += 1
+              learning_rate = 1.fdiv(update_counter[c])
+              update = sub_x[assigned_bits.where, true].mean(axis: 0)
+              @cluster_centers[c, true] = (1 - learning_rate) * @cluster_centers[c, true] + learning_rate * update
+            end
+          end
+          error = Numo::NMath.sqrt(((old_centers - @cluster_centers)**2).sum(axis: 1)).mean
+          break if error <= @params[:tol]
+        end
+        self
+      end
+
+      # Predict cluster labels for samples.
+      #
+      # @param x [Numo::DFloat] (shape: [n_samples, n_features]) The samples to predict the cluster label.
+      # @return [Numo::Int32] (shape: [n_samples]) Predicted cluster label per sample.
+      def predict(x)
+        x = check_convert_sample_array(x)
+        assign_cluster(x)
+      end
+
+      # Analysis clusters and assign samples to clusters.
+      #
+      # @param x [Numo::DFloat] (shape: [n_samples, n_features]) The training data to be used for cluster analysis.
+      # @return [Numo::Int32] (shape: [n_samples]) Predicted cluster label per sample.
+      def fit_predict(x)
+        x = check_convert_sample_array(x)
+        fit(x)
+        predict(x)
+      end
+
+      private
+
+      def assign_cluster(x)
+        distance_matrix = PairwiseMetric.euclidean_distance(x, @cluster_centers)
+        distance_matrix.min_index(axis: 1) - Numo::Int32[*0.step(distance_matrix.size - 1, @cluster_centers.shape[0])]
+      end
+
+      def init_cluster_centers(x, sub_rng)
+        # random initialize
+        n_samples = x.shape[0]
+        rand_id = [*0...n_samples].sample(@params[:n_clusters], random: sub_rng)
+        @cluster_centers = x[rand_id, true].dup
+        return unless @params[:init] == 'k-means++'
+
+        # k-means++ initialize
+        (1...@params[:n_clusters]).each do |n|
+          distance_matrix = PairwiseMetric.euclidean_distance(x, @cluster_centers[0...n, true])
+          min_distances = distance_matrix.flatten[distance_matrix.min_index(axis: 1)]
+          probs = min_distances**2 / (min_distances**2).sum
+          cum_probs = probs.cumsum
+          selected_id = cum_probs.gt(sub_rng.rand).where.to_a.first
+          @cluster_centers[n, true] = x[selected_id, true].dup
+        end
+      end
+    end
+  end
+end

data/lib/rumale/neural_network/adam.rb

@@ -32,7 +32,7 @@ module Rumale
         end
 
         # @!visibility private
-        # Calculate the updated weight with Nadam adaptive learning rate.
+        # Calculate the updated weight with Adam adaptive learning rate.
         #
         # @param weight [Numo::DFloat] (shape: [n_features]) The weight to be updated.
         # @param gradient [Numo::DFloat] (shape: [n_features]) The gradient for updating the weight.

data/lib/rumale/version.rb

@@ -3,5 +3,5 @@
 # Rumale is a machine learning library in Ruby.
 module Rumale
   # The version of Rumale you are using.
-  VERSION = '0.19.0'
+  VERSION = '0.19.1'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rumale
 version: !ruby/object:Gem::Version
-  version: 0.19.0
+  version: 0.19.1
 platform: ruby
 authors:
 - yoshoku
-autorequire: 
+autorequire:
 bindir: exe
 cert_chain: []
-date: 2020-05-23 00:00:00.000000000 Z
+date: 2020-06-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: numo-narray
@@ -72,6 +72,7 @@ files:
 - lib/rumale/clustering/hdbscan.rb
 - lib/rumale/clustering/k_means.rb
 - lib/rumale/clustering/k_medoids.rb
+- lib/rumale/clustering/mini_batch_k_means.rb
 - lib/rumale/clustering/power_iteration.rb
 - lib/rumale/clustering/single_linkage.rb
 - lib/rumale/clustering/snn.rb
@@ -196,7 +197,7 @@ metadata:
   source_code_uri: https://github.com/yoshoku/rumale
   documentation_uri: https://yoshoku.github.io/rumale/doc/
   bug_tracker_uri: https://github.com/yoshoku/rumale/issues
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -212,7 +213,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubygems_version: 3.1.2
-signing_key: 
+signing_key:
 specification_version: 4
 summary: Rumale is a machine learning library in Ruby. Rumale provides machine learning
   algorithms with interfaces similar to Scikit-Learn in Python.