rumale-clustering 0.24.0

data/lib/rumale/clustering/hdbscan.rb

@@ -0,0 +1,289 @@
+# frozen_string_literal: true
+
+require 'rumale/base/estimator'
+require 'rumale/base/cluster_analyzer'
+require 'rumale/pairwise_metric'
+require 'rumale/validation'
+require 'rumale/clustering/single_linkage'
+
+module Rumale
+  module Clustering
+    # HDBSCAN is a class that implements HDBSCAN cluster analysis.
+    #
+    # @example
+    #   require 'rumale/clustering/hdbscan'
+    #
+    #   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 < ::Rumale::Base::Estimator # rubocop:disable Metrics/ClassLength
+      include ::Rumale::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')
+        super()
+        @params = {
+          min_samples: min_samples,
+          min_cluster_size: min_cluster_size || min_samples,
+          metric: (metric == 'precomputed' ? 'precomputed' : 'euclidean')
+        }
+      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 = ::Rumale::Validation.check_convert_sample_array(x)
+        raise ArgumentError, 'the input distance matrix should be square' if check_invalid_array_shape(x)
+
+        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 = ::Rumale::Validation.check_convert_sample_array(x)
+        raise ArgumentError, 'the input distance matrix should be square' if check_invalid_array_shape(x)
+
+        distance_mat = @params[:metric] == 'precomputed' ? x : ::Rumale::PairwiseMetric.euclidean_distance(x)
+        @labels = partial_fit(distance_mat)
+      end
+
+      private
+
+      def check_invalid_array_shape(x)
+        @params[:metric] == 'precomputed' && x.shape[0] != x.shape[1]
+      end
+
+      # @!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
+
+          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
+
+          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)
+          x == other.x && y == other.y && weight == other.weight && n_elements == other.n_elements
+        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
+
+        selected_node_ids = is_cluster.select { |_k, v| v == true }.keys.uniq.sort
+        cluster_label_map = selected_node_ids.each_with_object({}).with_index { |(n_idx, h), c_idx| h[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

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require 'rumale/base/estimator'
+require 'rumale/base/cluster_analyzer'
+require 'rumale/pairwise_metric'
+require 'rumale/validation'
+
+module Rumale
+  module Clustering
+    # KMeans is a class that implements K-Means cluster analysis.
+    # The current implementation uses the Euclidean distance for analyzing the clusters.
+    #
+    # @example
+    #   require 'rumale/clustering/k_means'
+    #
+    #   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 < ::Rumale::Base::Estimator
+      include ::Rumale::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)
+        super()
+        @params = {
+          n_clusters: n_clusters,
+          init: (init == 'random' ? 'random' : 'k-means++'),
+          max_iter: max_iter,
+          tol: tol,
+          random_seed: (random_seed || srand)
+        }
+        @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 = ::Rumale::Validation.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 = ::Rumale::Validation.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 = ::Rumale::Validation.check_convert_sample_array(x)
+
+        fit(x).predict(x)
+      end
+
+      private
+
+      def assign_cluster(x)
+        distance_matrix = ::Rumale::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 = ::Rumale::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

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require 'rumale/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
+    #   require 'rumale/clustering/k_medoids'
+    #
+    #   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 < ::Rumale::Base::Estimator
+      include ::Rumale::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)
+        super()
+        @params = {
+          n_clusters: n_clusters,
+          metric: (metric == 'precomputed' ? 'precomputed' : 'euclidean'),
+          init: (init == 'random' ? 'random' : 'k-means++'),
+          max_iter: max_iter,
+          tol: tol,
+          random_seed: (random_seed || srand)
+        }
+        @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, _y = nil)
+        x = ::Rumale::Validation.check_convert_sample_array(x)
+        raise ArgumentError, 'the input distance matrix should be square' if check_invalid_array_shape(x)
+
+        # 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 = ::Rumale::Validation.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, 'the shape of input matrix should 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 = ::Rumale::Validation.check_convert_sample_array(x)
+        raise ArgumentError, 'the input distance matrix should be square' if check_invalid_array_shape(x)
+
+        fit(x)
+        if @params[:metric] == 'precomputed'
+          predict(x[true, @medoid_ids])
+        else
+          predict(x)
+        end
+      end
+
+      private
+
+      def check_invalid_array_shape(x)
+        @params[:metric] == 'precomputed' && x.shape[0] != x.shape[1]
+      end
+
+      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

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require 'rumale/base/estimator'
+require 'rumale/base/cluster_analyzer'
+require 'rumale/pairwise_metric'
+require 'rumale/validation'
+
+module Rumale
+  module Clustering
+    # MniBatchKMeans is a class that implements K-Means cluster analysis
+    # with mini-batch stochastic gradient descent (SGD).
+    #
+    # @example
+    #   require 'rumale/clustering/mini_batch_k_means'
+    #
+    #   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 < ::Rumale::Base::Estimator
+      include ::Rumale::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)
+        super()
+        @params = {
+          n_clusters: n_clusters,
+          init: (init == 'random' ? 'random' : 'k-means++'),
+          max_iter: max_iter,
+          batch_size: batch_size,
+          tol: tol,
+          random_seed: (random_seed || srand)
+        }
+        @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 = ::Rumale::Validation.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 = ::Rumale::Validation.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 = ::Rumale::Validation.check_convert_sample_array(x)
+
+        fit(x).predict(x)
+      end
+
+      private
+
+      def assign_cluster(x)
+        distance_matrix = ::Rumale::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 = ::Rumale::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