rumale 0.23.3 → 0.24.0

data/lib/rumale/clustering/hdbscan.rb

@@ -1,291 +0,0 @@
-# frozen_string_literal: true
-
-require 'rumale/base/base_estimator'
-require 'rumale/base/cluster_analyzer'
-require 'rumale/pairwise_metric'
-require 'rumale/clustering/single_linkage'
-
-module Rumale
-  module Clustering
-    # HDBSCAN is a class that implements HDBSCAN cluster analysis.
-    #
-    # @example
-    #   analyzer = Rumale::Clustering::HDBSCAN.new(min_samples: 5)
-    #   cluster_labels = analyzer.fit_predict(samples)
-    #
-    # *Reference*
-    # - Campello, R J. G. B., Moulavi, D., Zimek, A., and Sander, J., "Hierarchical Density Estimates for Data Clustering, Visualization, and Outlier Detection," TKDD, Vol. 10 (1), pp. 5:1--5:51, 2015.
-    # - Campello, R J. G. B., Moulavi, D., and Sander, J., "Density-Based Clustering Based on Hierarchical Density Estimates," Proc. PAKDD'13, pp. 160--172, 2013.
-    # - Lelis, L., and Sander, J., "Semi-Supervised Density-Based Clustering," Proc. ICDM'09, pp. 842--847, 2009.
-    class HDBSCAN
-      include Base::BaseEstimator
-      include Base::ClusterAnalyzer
-
-      # Return the cluster labels. The negative cluster label indicates that the point is noise.
-      # @return [Numo::Int32] (shape: [n_samples])
-      attr_reader :labels
-
-      # Create a new cluster analyzer with HDBSCAN algorithm.
-      #
-      # @param min_samples [Integer] The number of neighbor samples to be used for the criterion whether a point is a core point.
-      # @param min_cluster_size [Integer/Nil] The minimum size of cluster. If nil is given, it is set equal to min_samples.
-      # @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 fit_transform methods expect to be given a distance matrix.
-      def initialize(min_samples: 10, min_cluster_size: nil, metric: 'euclidean')
-        check_params_numeric(min_samples: min_samples)
-        check_params_numeric_or_nil(min_cluster_size: min_cluster_size)
-        check_params_string(metric: metric)
-        check_params_positive(min_samples: min_samples)
-        @params = {}
-        @params[:min_samples] = min_samples
-        @params[:min_cluster_size] = min_cluster_size || min_samples
-        @params[:metric] = metric == 'precomputed' ? 'precomputed' : 'euclidean'
-        @labels = nil
-      end
-
-      # Analysis clusters with given training data.
-      #
-      # @overload fit(x) -> HDBSCAN
-      #
-      # @param x [Numo::DFloat] (shape: [n_samples, n_features]) The training data to be used for cluster analysis.
-      #   If the metric is 'precomputed', x must be a square distance matrix (shape: [n_samples, n_samples]).
-      # @return [HDBSCAN] The learned cluster analyzer itself.
-      def fit(x, _y = nil)
-        x = check_convert_sample_array(x)
-        raise ArgumentError, 'Expect the input distance matrix to be square.' if @params[:metric] == 'precomputed' && x.shape[0] != x.shape[1]
-
-        fit_predict(x)
-        self
-      end
-
-      # Analysis clusters and assign samples to clusters.
-      #
-      # @param x [Numo::DFloat] (shape: [n_samples, n_features]) The samples to be used for cluster analysis.
-      #   If the metric is 'precomputed', x must be a square distance matrix (shape: [n_samples, n_samples]).
-      # @return [Numo::Int32] (shape: [n_samples]) Predicted cluster label per sample.
-      def fit_predict(x)
-        x = check_convert_sample_array(x)
-        raise ArgumentError, 'Expect the input distance matrix to be square.' if @params[:metric] == 'precomputed' && x.shape[0] != x.shape[1]
-
-        distance_mat = @params[:metric] == 'precomputed' ? x : Rumale::PairwiseMetric.euclidean_distance(x)
-        @labels = partial_fit(distance_mat)
-      end
-
-      private
-
-      # @!visibility private
-      class UnionFind
-        def initialize(n)
-          @parent = Numo::Int32.new(n).seq
-          @rank = Numo::Int32.zeros(n)
-        end
-
-        # @!visibility private
-        def union(x, y)
-          x_root = find(x)
-          y_root = find(y)
-
-          return if x_root == y_root
-
-          # :nocov:
-          if @rank[x_root] < @rank[y_root]
-            @parent[x_root] = y_root
-          else
-            @parent[y_root] = x_root
-            @rank[x_root] += 1 if @rank[x_root] == @rank[y_root]
-          end
-          # :nocov:
-
-          nil
-        end
-
-        # @!visibility private
-        def find(x)
-          @parent[x] = find(@parent[x]) if @parent[x] != x
-          @parent[x]
-        end
-      end
-
-      # @!visibility private
-      class Node
-        # @!visibility private
-        attr_reader :x, :y, :weight, :n_elements
-
-        # @!visibility private
-        def initialize(x:, y:, weight:, n_elements: 0)
-          @x = x
-          @y = y
-          @weight = weight
-          @n_elements = n_elements
-        end
-
-        # @!visibility private
-        def ==(other)
-          # :nocov:
-          x == other.x && y == other.y && weight == other.weight && n_elements == other.n_elements
-          # :nocov:
-        end
-      end
-
-      private_constant :UnionFind, :Node
-
-      def partial_fit(distance_mat)
-        mr_distance_mat = mutual_reachability_distances(distance_mat, @params[:min_samples])
-        hierarchy = Rumale::Clustering::SingleLinkage.new(n_clusters: 1, metric: 'precomputed').fit(mr_distance_mat).hierarchy
-        tree = condense_tree(hierarchy, @params[:min_cluster_size])
-        stabilities = cluster_stability(tree)
-        flatten(tree, stabilities)
-      end
-
-      def mutual_reachability_distances(distance_mat, min_samples)
-        core_distances = distance_mat.sort(axis: 1)[true, min_samples + 1]
-        Numo::DFloat.maximum(core_distances.expand_dims(1), Numo::DFloat.maximum(core_distances, distance_mat))
-      end
-
-      def breadth_first_search_hierarchy(hierarchy, root)
-        n_edges = hierarchy.size
-        n_points = n_edges + 1
-        to_process = [root]
-        res = []
-        while to_process.any?
-          res.concat(to_process)
-          to_process = to_process.select { |n| n >= n_points }.map { |n| n - n_points }
-          to_process = to_process.map { |n| [hierarchy[n].x, hierarchy[n].y] }.flatten if to_process.any?
-        end
-        res
-      end
-
-      # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
-      def condense_tree(hierarchy, min_cluster_size)
-        n_edges = hierarchy.size
-        root = 2 * n_edges
-        n_points = n_edges + 1
-        next_label = n_points + 1
-
-        node_ids = breadth_first_search_hierarchy(hierarchy, root)
-
-        relabel = Numo::Int32.zeros(root + 1)
-        relabel[root] = n_points
-        res = []
-        visited = {}
-
-        node_ids.each do |n_id|
-          next if visited[n_id] || n_id < n_points
-
-          edge = hierarchy[n_id - n_points]
-
-          density = edge.weight > 0.0 ? 1.fdiv(edge.weight) : Float::INFINITY
-          n_x_elements = edge.x >= n_points ? hierarchy[edge.x - n_points].n_elements : 1
-          n_y_elements = edge.y >= n_points ? hierarchy[edge.y - n_points].n_elements : 1
-
-          if n_x_elements >= min_cluster_size && n_y_elements >= min_cluster_size
-            relabel[edge.x] = next_label
-            res.push(Node.new(x: relabel[n_id], y: relabel[edge.x], weight: density, n_elements: n_x_elements))
-            next_label += 1
-            relabel[edge.y] = next_label
-            res.push(Node.new(x: relabel[n_id], y: relabel[edge.y], weight: density, n_elements: n_y_elements))
-            next_label += 1
-          elsif n_x_elements < min_cluster_size && n_y_elements < min_cluster_size
-            breadth_first_search_hierarchy(hierarchy, edge.x).each do |sn_id|
-              res.push(Node.new(x: relabel[n_id], y: sn_id, weight: density, n_elements: 1)) if sn_id < n_points
-              visited[sn_id] = true
-            end
-            breadth_first_search_hierarchy(hierarchy, edge.y).each do |sn_id|
-              res.push(Node.new(x: relabel[n_id], y: sn_id, weight: density, n_elements: 1)) if sn_id < n_points
-              visited[sn_id] = true
-            end
-          elsif n_x_elements < min_cluster_size
-            relabel[edge.y] = relabel[n_id]
-            breadth_first_search_hierarchy(hierarchy, edge.x).each do |sn_id|
-              res.push(Node.new(x: relabel[n_id], y: sn_id, weight: density, n_elements: 1)) if sn_id < n_points
-              visited[sn_id] = true
-            end
-          elsif n_y_elements < min_cluster_size
-            relabel[edge.x] = relabel[n_id]
-            breadth_first_search_hierarchy(hierarchy, edge.y).each do |sn_id|
-              res.push(Node.new(x: relabel[n_id], y: sn_id, weight: density, n_elements: 1)) if sn_id < n_points
-              visited[sn_id] = true
-            end
-          end
-        end
-        res
-      end
-
-      def cluster_stability(tree)
-        tree.sort! { |a, b| a.weight <=> b.weight }
-
-        root = tree.map(&:x).min
-        child_max = tree.map(&:y).max
-        child_max = root if child_max < root
-        densities = Numo::DFloat.zeros(child_max + 1) + Float::INFINITY
-
-        current = tree[0].y
-        density_min = tree[0].weight
-        tree.each do |edge|
-          if edge.x == current
-            density_min = [density_min, edge.weight].min
-          else
-            densities[current] = density_min
-            current = edge.y
-            density_min = edge.weight
-          end
-        end
-
-        densities[current] = density_min if current != tree[0].y
-        densities[root] = 0.0
-
-        tree.each_with_object({}) do |edge, stab|
-          stab[edge.x] ||= 0.0
-          stab[edge.x] += (edge.weight - densities[edge.x]) * edge.n_elements
-        end
-      end
-
-      def breadth_first_search_tree(tree, root)
-        to_process = [root]
-        res = []
-        while to_process.any?
-          res.concat(to_process)
-          to_process = tree.select { |v| to_process.include?(v.x) }.map(&:y)
-        end
-        res
-      end
-
-      def flatten(tree, stabilities)
-        node_ids = stabilities.keys.sort.reverse.slice(0, stabilities.size - 1)
-
-        cluster_tree = tree.select { |edge| edge.n_elements > 1 }
-        is_cluster = node_ids.each_with_object({}) { |n_id, h| h[n_id] = true }
-
-        node_ids.each do |n_id|
-          children = cluster_tree.select { |node| node.x == n_id }.map(&:y)
-          subtree_stability = children.inject(0.0) { |sum, c_id| sum + stabilities[c_id] }
-          if subtree_stability > stabilities[n_id]
-            is_cluster[n_id] = false
-            stabilities[n_id] = subtree_stability
-          else
-            breadth_first_search_tree(cluster_tree, n_id).each do |sn_id|
-              is_cluster[sn_id] = false if sn_id != n_id
-            end
-          end
-        end
-
-        cluster_label_map = {}
-        is_cluster.select { |_k, v| v == true }.keys.uniq.sort.each_with_index { |n_idx, c_idx| cluster_label_map[n_idx] = c_idx }
-
-        parent_arr = tree.map(&:x)
-        uf = UnionFind.new(parent_arr.max + 1)
-        tree.each { |edge| uf.union(edge.x, edge.y) if cluster_label_map[edge.y].nil? }
-
-        root = parent_arr.min
-        res = Numo::Int32.zeros(root)
-        root.times do |n|
-          cluster = uf.find(n)
-          res[n] = cluster < root ? -1 : cluster_label_map[cluster] || -1
-        end
-        res
-      end
-      # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
-    end
-  end
-end

data/lib/rumale/clustering/k_means.rb

@@ -1,122 +0,0 @@
-# frozen_string_literal: true
-
-require 'rumale/base/base_estimator'
-require 'rumale/base/cluster_analyzer'
-require 'rumale/pairwise_metric'
-
-module Rumale
-  # This module consists of classes that implement cluster analysis methods.
-  module Clustering
-    # KMeans is a class that implements K-Means cluster analysis.
-    # The current implementation uses the Euclidean distance for analyzing the clusters.
-    #
-    # @example
-    #   analyzer = Rumale::Clustering::KMeans.new(n_clusters: 10, max_iter: 50)
-    #   cluster_labels = analyzer.fit_predict(samples)
-    #
-    # *Reference*
-    # - Arthur, D., and Vassilvitskii, S., "k-means++: the advantages of careful seeding," Proc. SODA'07, pp. 1027--1035, 2007.
-    class KMeans
-      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.
-      #
-      # @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 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: 50, tol: 1.0e-4, random_seed: nil)
-        check_params_numeric(n_clusters: n_clusters, max_iter: max_iter, 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[: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) -> KMeans
-      #
-      # @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)
-        init_cluster_centers(x)
-        @params[:max_iter].times do |_t|
-          cluster_labels = assign_cluster(x)
-          old_centers = @cluster_centers.dup
-          @params[:n_clusters].times do |n|
-            assigned_bits = cluster_labels.eq(n)
-            @cluster_centers[n, true] = x[assigned_bits.where, true].mean(axis: 0) if assigned_bits.count.positive?
-          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)
-        # random initialize
-        n_samples = x.shape[0]
-        sub_rng = @rng.dup
-        rand_id = Array(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/clustering/k_medoids.rb

@@ -1,141 +0,0 @@
-# frozen_string_literal: true
-
-require 'rumale/base/base_estimator'
-require 'rumale/base/cluster_analyzer'
-require 'rumale/pairwise_metric'
-
-module Rumale
-  module Clustering
-    # KMedoids is a class that implements K-Medoids cluster analysis.
-    #
-    # @example
-    #   analyzer = Rumale::Clustering::KMedoids.new(n_clusters: 10, max_iter: 50)
-    #   cluster_labels = analyzer.fit_predict(samples)
-    #
-    # *Reference*
-    # - Arthur, D., and Vassilvitskii, S., "k-means++: the advantages of careful seeding," Proc. SODA'07, pp. 1027--1035, 2007.
-    class KMedoids
-      include Base::BaseEstimator
-      include Base::ClusterAnalyzer
-
-      # Return the indices of medoids.
-      # @return [Numo::Int32] (shape: [n_clusters])
-      attr_reader :medoid_ids
-
-      # Return the random generator.
-      # @return [Random]
-      attr_reader :rng
-
-      # Create a new cluster analyzer with K-Medoids method.
-      #
-      # @param n_clusters [Integer] The number of clusters.
-      # @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 fit_transform methods expect to be given a distance matrix.
-      # @param init [String] The initialization method for centroids ('random' or 'k-means++').
-      # @param max_iter [Integer] The maximum number of iterations.
-      # @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, metric: 'euclidean', init: 'k-means++', max_iter: 50, tol: 1.0e-4, random_seed: nil)
-        check_params_numeric(n_clusters: n_clusters, max_iter: max_iter, tol: tol)
-        check_params_string(metric: metric, 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[:metric] = metric == 'precomputed' ? 'precomputed' : 'euclidean'
-        @params[:init] = init == 'random' ? 'random' : 'k-means++'
-        @params[:max_iter] = max_iter
-        @params[:tol] = tol
-        @params[:random_seed] = random_seed
-        @params[:random_seed] ||= srand
-        @medoid_ids = nil
-        @cluster_centers = nil
-        @rng = Random.new(@params[:random_seed])
-      end
-
-      # Analysis clusters with given training data.
-      #
-      # @overload fit(x) -> KMedoids
-      #
-      # @param x [Numo::DFloat] (shape: [n_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_samples, n_samples]).
-      # @return [KMedoids] The learned cluster analyzer itself.
-      def fit(x, _not_used = nil)
-        x = check_convert_sample_array(x)
-        raise ArgumentError, 'Expect the input distance matrix to be square.' if @params[:metric] == 'precomputed' && x.shape[0] != x.shape[1]
-
-        # initialize some varibales.
-        distance_mat = @params[:metric] == 'precomputed' ? x : Rumale::PairwiseMetric.euclidean_distance(x)
-        init_cluster_centers(distance_mat)
-        error = distance_mat[true, @medoid_ids].mean
-        @params[:max_iter].times do |_t|
-          cluster_labels = assign_cluster(distance_mat[true, @medoid_ids])
-          @params[:n_clusters].times do |n|
-            assigned_ids = cluster_labels.eq(n).where
-            @medoid_ids[n] = assigned_ids[distance_mat[assigned_ids, assigned_ids].sum(axis: 1).min_index]
-          end
-          new_error = distance_mat[true, @medoid_ids].mean
-          break if (error - new_error).abs <= @params[:tol]
-
-          error = new_error
-        end
-        @cluster_centers = x[@medoid_ids, true].dup if @params[:metric] == 'euclidean'
-        self
-      end
-
-      # Predict cluster labels for samples.
-      #
-      # @param x [Numo::DFloat] (shape: [n_samples, n_features]) The samples to predict the cluster label.
-      #   If the metric is 'precomputed', x must be distances between samples and medoids (shape: [n_samples, n_clusters]).
-      # @return [Numo::Int32] (shape: [n_samples]) Predicted cluster label per sample.
-      def predict(x)
-        x = check_convert_sample_array(x)
-        distance_mat = @params[:metric] == 'precomputed' ? x : Rumale::PairwiseMetric.euclidean_distance(x, @cluster_centers)
-        if @params[:metric] == 'precomputed' && distance_mat.shape[1] != @medoid_ids.size
-          raise ArgumentError, 'Expect the size input matrix to be n_samples-by-n_clusters.'
-        end
-
-        assign_cluster(distance_mat)
-      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.
-      #   If the metric is 'precomputed', x must be a square distance matrix (shape: [n_samples, n_samples]).
-      # @return [Numo::Int32] (shape: [n_samples]) Predicted cluster label per sample.
-      def fit_predict(x)
-        x = check_convert_sample_array(x)
-        fit(x)
-        if @params[:metric] == 'precomputed'
-          predict(x[true, @medoid_ids])
-        else
-          predict(x)
-        end
-      end
-
-      private
-
-      def assign_cluster(distances_to_medoids)
-        distances_to_medoids.min_index(axis: 1) - Numo::Int32[*0.step(distances_to_medoids.size - 1, @params[:n_clusters])]
-      end
-
-      def init_cluster_centers(distance_mat)
-        # random initialize
-        n_samples = distance_mat.shape[0]
-        sub_rng = @rng.dup
-        @medoid_ids = Numo::Int32.asarray(Array(0...n_samples).sample(@params[:n_clusters], random: sub_rng))
-        return unless @params[:init] == 'k-means++'
-
-        # k-means++ initialize
-        (1...@params[:n_clusters]).each do |n|
-          distances = distance_mat[true, @medoid_ids[0...n]]
-          min_distances = distances.flatten[distances.min_index(axis: 1)]
-          probs = min_distances**2 / (min_distances**2).sum
-          cum_probs = probs.cumsum
-          @medoid_ids[n] = cum_probs.gt(sub_rng.rand).where.to_a.first
-        end
-      end
-    end
-  end
-end

data/lib/rumale/clustering/mini_batch_k_means.rb

@@ -1,139 +0,0 @@
-# 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 = Array(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 = Array(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