rumale-clustering 0.25.0 → 0.26.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6ee5c0e4616d465c45562131bc0b0fd2c88b7e0725c45e9ef2864c271fec9f50
-  data.tar.gz: c8261c272928d2cdf2ae7c1938373c899b10dc15ee5bdd3cc6e28b0ca32a7040
+  metadata.gz: d4bd3dd2f04f44e145f7ebe90154dfd9e2970485c58cd68af82abd0f744e78c0
+  data.tar.gz: 9af9eafaa42f596f75c09a13b6da658bf7ceb69af657a22bc50f6c58b7a2eb05
 SHA512:
-  metadata.gz: 67d2413b7f74868c63df550611f753fb37bf1bab6b5c8ceaf024193083d5b767b38ffabee22b260ce18dfeac417f9c4ccd659a93f5f092db0070d388911a540a
-  data.tar.gz: 5f89ecc7ae05d4c990bf90eba3e7a805b4c176c6217ac668690491d3c429ef5a3d028edbd307306cc65c0abd1b06b7b42436c01b4b6ac8d2ecdfd97099f84fab
+  metadata.gz: 2bcbe3e94d4ae65507fb6253b68264dcc42ed455a7150d7096ea71d4d838dae2de2ba2b7991e06b258b16e28f701f5c350b5e26a7c06f43a0b08d6e0145c5cb1
+  data.tar.gz: c08a182fd31b16aaad51186c4dfe3457e5ea7d5f9b956a966ead434a036d9817189cd3e5ee7be824a04c06baf60771423f9ef23c0488aceb1705dfde7aaeb8a4

data/lib/rumale/clustering/mean_shift.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require 'rumale/base/estimator'
+require 'rumale/base/cluster_analyzer'
+require 'rumale/pairwise_metric'
+require 'rumale/validation'
+
+module Rumale
+  module Clustering
+    # MeanShift is a class that implements mean-shift clustering with flat kernel.
+    #
+    # @example
+    #   require 'rumale/clustering/mean_shift'
+    #
+    #   analyzer = Rumale::Clustering::MeanShift.new(bandwidth: 1.5)
+    #   cluster_labels = analyzer.fit_predict(samples)
+    #
+    # *Reference*
+    # - Carreira-Perpinan, M A., "A review of mean-shift algorithms for clustering," arXiv:1503.00687v1.
+    # - Sheikh, Y A., Khan, E A., and Kanade, T., "Mode-seeking by Medoidshifts," Proc. ICCV'07, pp. 1--8, 2007.
+    # - Vedaldi, A., and Soatto, S., "Quick Shift and Kernel Methods for Mode Seeking," Proc. ECCV'08, pp. 705--718, 2008.
+    class MeanShift < Rumale::Base::Estimator
+      include Rumale::Base::ClusterAnalyzer
+
+      # Return the centroids.
+      # @return [Numo::DFloat] (shape: [n_clusters, n_features])
+      attr_reader :cluster_centers
+
+      # Create a new cluster analyzer with mean-shift algorithm.
+      #
+      # @param bandwidth [Float] The bandwidth parameter of flat kernel.
+      # @param max_iter [Integer] The maximum number of iterations.
+      # @param tol [Float] The tolerance of termination criterion
+      def initialize(bandwidth: 1.0, max_iter: 500, tol: 1e-4)
+        super()
+        @params = {
+          bandwidth: bandwidth,
+          max_iter: max_iter,
+          tol: tol
+        }
+      end
+
+      # Analysis clusters with given training data.
+      #
+      # @overload fit(x) -> MeanShift
+      #   @param x [Numo::DFloat] (shape: [n_samples, n_features]) The training data to be used for cluster analysis.
+      #   @return [MeanShift] The learned cluster analyzer itself.
+      def fit(x, _y = nil)
+        x = Rumale::Validation.check_convert_sample_array(x)
+
+        z = x.dup
+        @params[:max_iter].times do
+          distance_mat = Rumale::PairwiseMetric.euclidean_distance(x, z)
+          kernel_mat = Numo::DFloat.cast(distance_mat.le(@params[:bandwidth]))
+          sum_kernel = kernel_mat.sum(axis: 0)
+          weight_mat = kernel_mat.dot((1 / sum_kernel).diag)
+          updated = weight_mat.transpose.dot(x)
+          break if (z - updated).abs.sum(axis: 1).max <= @params[:tol]
+
+          z = updated
+        end
+
+        @cluster_centers = connect_components(z)
+
+        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)
+        n_clusters = @cluster_centers.shape[0]
+        distance_mat = Rumale::PairwiseMetric.squared_error(x, @cluster_centers)
+        distance_mat.min_index(axis: 1) - Numo::Int32[*0.step(distance_mat.size - 1, n_clusters)]
+      end
+
+      def connect_components(z)
+        centers = []
+        n_samples = z.shape[0]
+
+        n_samples.times do |idx|
+          assigned = false
+          centers.each do |cluster_vec|
+            dist = Math.sqrt(((z[idx, true] - cluster_vec)**2).sum.abs)
+            if dist <= @params[:bandwidth]
+              assigned = true
+              break
+            end
+          end
+          centers << z[idx, true].dup unless assigned
+        end
+
+        Numo::DFloat.asarray(centers)
+      end
+    end
+  end
+end

data/lib/rumale/clustering/version.rb

@@ -5,6 +5,6 @@ module Rumale
   # This module consists of classes that implement cluster analysis methods.
   module Clustering
     # @!visibility private
-    VERSION = '0.25.0'
+    VERSION = '0.26.0'
   end
 end

data/lib/rumale/clustering.rb

@@ -7,6 +7,7 @@ require_relative 'clustering/gaussian_mixture'
 require_relative 'clustering/hdbscan'
 require_relative 'clustering/k_means'
 require_relative 'clustering/k_medoids'
+require_relative 'clustering/mean_shift'
 require_relative 'clustering/mini_batch_k_means'
 require_relative 'clustering/power_iteration'
 require_relative 'clustering/single_linkage'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rumale-clustering
 version: !ruby/object:Gem::Version
-  version: 0.25.0
+  version: 0.26.0
 platform: ruby
 authors:
 - yoshoku
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-01-18 00:00:00.000000000 Z
+date: 2023-02-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: numo-narray
@@ -30,14 +30,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.25.0
+        version: 0.26.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.25.0
+        version: 0.26.0
 description: |
   Rumale::Clustering provides cluster analysis algorithms,
   such as K-Means, Gaussian Mixture Model, DBSCAN, and Spectral Clustering,
@@ -56,6 +56,7 @@ files:
 - lib/rumale/clustering/hdbscan.rb
 - lib/rumale/clustering/k_means.rb
 - lib/rumale/clustering/k_medoids.rb
+- lib/rumale/clustering/mean_shift.rb
 - lib/rumale/clustering/mini_batch_k_means.rb
 - lib/rumale/clustering/power_iteration.rb
 - lib/rumale/clustering/single_linkage.rb