rumale 0.23.3 → 0.24.0

data/lib/rumale/clustering/power_iteration.rb

@@ -1,127 +0,0 @@
-# frozen_string_literal: true
-
-require 'rumale/base/base_estimator'
-require 'rumale/base/cluster_analyzer'
-require 'rumale/pairwise_metric'
-
-module Rumale
-  module Clustering
-    # PowerIteration is a class that implements power iteration clustering.
-    #
-    # @example
-    #   analyzer = Rumale::Clustering::PowerIteration.new(n_clusters: 10, gamma: 8.0, max_iter: 1000)
-    #   cluster_labels = analyzer.fit_predict(samples)
-    #
-    # *Reference*
-    # - Lin, F., and Cohen, W W., "Power Iteration Clustering," Proc. ICML'10, pp. 655--662, 2010.
-    class PowerIteration
-      include Base::BaseEstimator
-      include Base::ClusterAnalyzer
-
-      # Return the data in embedded space.
-      # @return [Numo::DFloat] (shape: [n_samples])
-      attr_reader :embedding
-
-      # Return the cluster labels.
-      # @return [Numo::Int32] (shape: [n_samples])
-      attr_reader :labels
-
-      # Return the number of iterations run for optimization
-      # @return [Integer]
-      attr_reader :n_iter
-
-      # Create a new cluster analyzer with power iteration clustering.
-      #
-      # @param n_clusters [Integer] The number of clusters.
-      # @param affinity [String] The representation of affinity matrix ('rbf' or 'precomputed').
-      # @param gamma [Float] The parameter of rbf kernel, if nil it is 1 / n_features.
-      #   If affinity = 'precomputed', this parameter is ignored.
-      # @param init [String] The initialization method for centroids of K-Means clustering ('random' or 'k-means++').
-      # @param max_iter [Integer] The maximum number of iterations.
-      # @param tol [Float] The tolerance of termination criterion.
-      # @param eps [Float] A small value close to zero to avoid zero division error.
-      # @param random_seed [Integer] The seed value using to initialize the random generator.
-      def initialize(n_clusters: 8, affinity: 'rbf', gamma: nil, init: 'k-means++', max_iter: 1000, tol: 1.0e-8, eps: 1.0e-5, random_seed: nil)
-        check_params_numeric(n_clusters: n_clusters, max_iter: max_iter, tol: tol, eps: eps)
-        check_params_numeric_or_nil(gamma: gamma, random_seed: random_seed)
-        check_params_string(affinity: affinity, init: init)
-        check_params_positive(n_clusters: n_clusters, max_iter: max_iter, tol: tol, eps: eps)
-        @params = {}
-        @params[:n_clusters] = n_clusters
-        @params[:affinity] = affinity
-        @params[:gamma] = gamma
-        @params[:init] = init == 'random' ? 'random' : 'k-means++'
-        @params[:max_iter] = max_iter
-        @params[:tol] = tol
-        @params[:eps] = eps
-        @params[:random_seed] = random_seed
-        @params[:random_seed] ||= srand
-        @embedding = nil
-        @labels = nil
-        @n_iter = nil
-      end
-
-      # Analysis clusters with given training data.
-      #
-      # @overload fit(x) -> PowerIteration
-      #
-      # @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 affinity matrix (shape: [n_samples, n_samples]).
-      # @return [PowerIteration] The learned cluster analyzer itself.
-      def fit(x, _y = nil)
-        x = check_convert_sample_array(x)
-        raise ArgumentError, 'Expect the input affinity matrix to be square.' if @params[:affinity] == '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 training data to be used for cluster analysis.
-      #   If the metric is 'precomputed', x must be a square affinity 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 affinity matrix to be square.' if @params[:affinity] == 'precomputed' && x.shape[0] != x.shape[1]
-
-        affinity_mat = @params[:metric] == 'precomputed' ? x : Rumale::PairwiseMetric.rbf_kernel(x, nil, @params[:gamma])
-        @embedding, @n_iter = embedded_space(affinity_mat, @params[:max_iter], @params[:tol].fdiv(affinity_mat.shape[0]))
-        @labels = line_kmeans_clustering(@embedding)
-      end
-
-      private
-
-      def embedded_space(affinity_mat, max_iter, tol)
-        affinity_mat[affinity_mat.diag_indices] = 0.0
-
-        degrees = affinity_mat.sum(axis: 1)
-        normalized_affinity_mat = (1.0 / degrees).diag.dot(affinity_mat)
-
-        iters = 0
-        embedded_line = degrees / degrees.sum
-        n_samples = embedded_line.shape[0]
-        error = Numo::DFloat.ones(n_samples)
-        max_iter.times do |t|
-          iters = t + 1
-          new_embedded_line = normalized_affinity_mat.dot(embedded_line)
-          new_embedded_line /= new_embedded_line.abs.sum
-          new_error = (new_embedded_line - embedded_line).abs
-          break if (new_error - error).abs.max <= tol
-
-          embedded_line = new_embedded_line
-          error = new_error
-        end
-
-        [embedded_line, iters]
-      end
-
-      def line_kmeans_clustering(vec)
-        Rumale::Clustering::KMeans.new(
-          n_clusters: @params[:n_clusters], init: @params[:init],
-          max_iter: @params[:max_iter], tol: @params[:tol], random_seed: @params[:random_seed]
-        ).fit_predict(vec.expand_dims(1))
-      end
-    end
-  end
-end

data/lib/rumale/clustering/single_linkage.rb

@@ -1,203 +0,0 @@
-# frozen_string_literal: true
-
-require 'rumale/base/base_estimator'
-require 'rumale/base/cluster_analyzer'
-require 'rumale/pairwise_metric'
-
-module Rumale
-  module Clustering
-    # SingleLinkage is a class that implements hierarchical cluster analysis with single linakge method.
-    # This class is used internally for HDBSCAN.
-    #
-    # @example
-    #   analyzer = Rumale::Clustering::SingleLinkage.new(n_clusters: 2)
-    #   cluster_labels = analyzer.fit_predict(samples)
-    #
-    # *Reference*
-    # - Mullner, D., "Modern hierarchical, agglomerative clustering algorithms," arXiv:1109.2378, 2011.
-    class SingleLinkage
-      include Base::BaseEstimator
-      include Base::ClusterAnalyzer
-
-      # Return the cluster labels.
-      # @return [Numo::Int32] (shape: [n_samples])
-      attr_reader :labels
-
-      # Return the hierarchical structure.
-      # @return [Array<SingleLinkage::Node>] (shape: [n_samples - 1])
-      attr_reader :hierarchy
-
-      # Create a new cluster analyzer with single linkage algorithm.
-      #
-      # @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.
-      def initialize(n_clusters: 2, metric: 'euclidean')
-        check_params_numeric(n_clusters: n_clusters)
-        check_params_string(metric: metric)
-        @params = {}
-        @params[:n_clusters] = n_clusters
-        @params[:metric] = metric == 'precomputed' ? 'precomputed' : 'euclidean'
-        @labels = nil
-        @hierarchy = nil
-      end
-
-      # Analysis clusters with given training data.
-      #
-      # @overload fit(x) -> SingleLinkage
-      #
-      # @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 [SingleLinkage] 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.zeros(2 * n - 1) - 1
-          @size = Numo::Int32.hstack([Numo::Int32.ones(n), Numo::Int32.zeros(n - 1)])
-          @next_label = n
-        end
-
-        # @!visibility private
-        def union(x, y)
-          size = @size[x] + @size[y]
-          @parent[x] = @next_label
-          @parent[y] = @next_label
-          @size[@next_label] = size
-          @next_label += 1
-          size
-        end
-
-        # @!visibility private
-        def find(x)
-          p = x
-          x = @parent[x] while @parent[x] != -1
-          while @parent[p] != x
-            p = @parent[p]
-            @parent[p] = x
-          end
-          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)
-        mst = minimum_spanning_tree(distance_mat)
-        @hierarchy = single_linkage_hierarchy(mst)
-        flatten(@hierarchy, @params[:n_clusters])
-      end
-
-      def minimum_spanning_tree(complete_graph)
-        n_samples = complete_graph.shape[0]
-        n_edges = n_samples - 1
-        curr_weights = Numo::DFloat.zeros(n_samples) + Float::INFINITY
-        curr_labels = Numo::Int32.new(n_samples).seq
-        next_node = 0
-        mst = Array.new(n_edges) do
-          curr_node = next_node
-          target = curr_labels.ne(curr_node)
-          curr_labels = curr_labels[target]
-          curr_weights = Numo::DFloat.minimum(curr_weights[target], complete_graph[curr_node, curr_labels])
-          next_node = curr_labels[curr_weights.min_index]
-          weight = curr_weights.min
-          Node.new(x: curr_node, y: next_node, weight: weight)
-        end
-        mst.sort! { |a, b| a.weight <=> b.weight }
-      end
-
-      def single_linkage_hierarchy(mst)
-        n_edges = mst.size
-        n_nodes = n_edges + 1
-        uf = UnionFind.new(n_nodes)
-        Array.new(n_edges) do |n|
-          x_root = uf.find(mst[n].x)
-          y_root = uf.find(mst[n].y)
-          x_root, y_root = [y_root, x_root] unless x_root < y_root
-          weight = mst[n].weight
-          n_samples = uf.union(x_root, y_root)
-          Node.new(x: x_root, y: y_root, weight: weight, n_elements: n_samples)
-        end
-      end
-
-      def descedent_ids(hierarchy_, start_node)
-        n_samples = hierarchy_.size + 1
-        return [start_node] if start_node < n_samples
-
-        res = []
-        indices = [start_node]
-        n_indices = 1
-        while n_indices.positive?
-          idx = indices.pop
-          if idx < n_samples
-            res.push(idx)
-            n_indices -= 1
-          else
-            indices.push(hierarchy_[idx - n_samples].x)
-            indices.push(hierarchy_[idx - n_samples].y)
-            n_indices += 1
-          end
-        end
-        res
-      end
-
-      def flatten(hierarchy_, n_clusters)
-        n_samples = hierarchy_.size + 1
-        return Numo::Int32.zeros(n_samples) if n_clusters < 2
-
-        nodes = [-([hierarchy_[-1].x, hierarchy_[-1].y].max + 1)]
-        (n_clusters - 1).times do
-          children = hierarchy_[-nodes[0] - n_samples]
-          nodes.push(-children.x)
-          nodes.push(-children.y)
-          nodes.sort!.shift
-        end
-        res = Numo::Int32.zeros(n_samples)
-        nodes.each_with_index { |sid, cluster_id| res[descedent_ids(hierarchy_, -sid)] = cluster_id }
-        res
-      end
-    end
-  end
-end

data/lib/rumale/clustering/snn.rb

@@ -1,76 +0,0 @@
-# frozen_string_literal: true
-
-require 'rumale/pairwise_metric'
-require 'rumale/clustering/dbscan'
-
-module Rumale
-  module Clustering
-    # SNN is a class that implements Shared Nearest Neighbor cluster analysis.
-    # The SNN method is a variation of DBSCAN that uses similarity based on k-nearest neighbors as a metric.
-    #
-    # @example
-    #   analyzer = Rumale::Clustering::SNN.new(n_neighbros: 10, eps: 5, min_samples: 5)
-    #   cluster_labels = analyzer.fit_predict(samples)
-    #
-    # *Reference*
-    # - Ertoz, L., Steinbach, M., and Kumar, V., "Finding Clusters of Different Sizes, Shapes, and Densities in Noisy, High Dimensional Data," Proc. SDM'03, pp. 47--58, 2003.
-    # - Houle, M E., Kriegel, H-P., Kroger, P., Schubert, E., and Zimek, A., "Can Shared-Neighbor Distances Defeat the Curse of Dimensionality?," Proc. SSDBM'10, pp. 482--500, 2010.
-    class SNN < DBSCAN
-      # Create a new cluster analyzer with Shared Neareset Neighbor method.
-      #
-      # @param n_neighbors [Integer] The number of neighbors to be used for finding k-nearest neighbors.
-      # @param eps [Integer] The threshold value for finding connected components based on similarity.
-      # @param min_samples [Integer] The number of neighbor samples to be used for the criterion whether a point is a core point.
-      # @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(n_neighbors: 10, eps: 5, min_samples: 5, metric: 'euclidean')
-        check_params_numeric(n_neighbors: n_neighbors, min_samples: min_samples)
-        check_params_string(metric: metric)
-        @params = {}
-        @params[:n_neighbors] = n_neighbors
-        @params[:eps] = eps
-        @params[:min_samples] = min_samples
-        @params[:metric] = metric == 'precomputed' ? 'precomputed' : 'euclidean'
-        @core_sample_ids = nil
-        @labels = nil
-      end
-
-      # Analysis clusters with given training data.
-      #
-      # @overload fit(x) -> SNN
-      #   @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 [SNN] The learned cluster analyzer itself.
-      def fit(x, _y = nil)
-        super
-      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) # rubocop:disable Lint/UselessMethodDefinition
-        super
-      end
-
-      private
-
-      def calc_pairwise_metrics(x)
-        distance_mat = @params[:metric] == 'precomputed' ? x : Rumale::PairwiseMetric.euclidean_distance(x)
-        n_samples = distance_mat.shape[0]
-        adjacency_mat = Numo::DFloat.zeros(n_samples, n_samples)
-        n_samples.times do |n|
-          neighbor_ids = distance_mat[n, true].sort_index[0...@params[:n_neighbors]]
-          adjacency_mat[n, neighbor_ids] = 1
-        end
-        adjacency_mat.dot(adjacency_mat.transpose)
-      end
-
-      def region_query(similarity_arr)
-        similarity_arr.gt(@params[:eps]).where.to_a
-      end
-    end
-  end
-end

data/lib/rumale/clustering/spectral_clustering.rb

@@ -1,115 +0,0 @@
-# frozen_string_literal: true
-
-require 'rumale/base/base_estimator'
-require 'rumale/base/cluster_analyzer'
-require 'rumale/pairwise_metric'
-require 'rumale/preprocessing/l2_normalizer'
-
-module Rumale
-  module Clustering
-    # SpectralClustering is a class that implements the normalized spectral clustering.
-    #
-    # @example
-    #   require 'numo/linalg/autoloader'
-    #
-    #   analyzer = Rumale::Clustering::SpectralClustering.new(n_clusters: 10, gamma: 8.0)
-    #   cluster_labels = analyzer.fit_predict(samples)
-    #
-    # *Reference*
-    # - Ng, A Y., Jordan, M I., and Weiss, Y., "On Spectral Clustering: Analyssi and an algorithm," Proc. NIPS'01, pp. 849--856, 2001.
-    # - von Luxburg, U., "A tutorial on spectral clustering," Statistics and Computing, Vol. 17 (4), pp. 395--416, 2007.
-    class SpectralClustering
-      include Base::BaseEstimator
-      include Base::ClusterAnalyzer
-
-      # Return the data in embedded space.
-      # @return [Numo::DFloat] (shape: [n_samples, n_clusters])
-      attr_reader :embedding
-
-      # Return the cluster labels.
-      # @return [Numo::Int32] (shape: [n_samples])
-      attr_reader :labels
-
-      # Create a new cluster analyzer with normalized spectral clustering.
-      #
-      # @param n_clusters [Integer] The number of clusters.
-      # @param affinity [String] The representation of affinity matrix ('rbf' or 'precomputed').
-      #   If affinity = 'rbf', the class performs the normalized spectral clustering with the fully connected graph weighted by rbf kernel.
-      # @param gamma [Float] The parameter of rbf kernel, if nil it is 1 / n_features.
-      #   If affinity = 'precomputed', this parameter is ignored.
-      # @param init [String] The initialization method for centroids of K-Means clustering ('random' or 'k-means++').
-      # @param max_iter [Integer] The maximum number of iterations for K-Means clustering.
-      # @param tol [Float] The tolerance of termination criterion for K-Means clustering.
-      # @param random_seed [Integer] The seed value using to initialize the random generator.
-      def initialize(n_clusters: 2, affinity: 'rbf', gamma: nil, init: 'k-means++', max_iter: 10, tol: 1.0e-8, random_seed: nil)
-        check_params_numeric(n_clusters: n_clusters, max_iter: max_iter, tol: tol)
-        check_params_numeric_or_nil(gamma: gamma, random_seed: random_seed)
-        check_params_string(affinity: affinity, init: init)
-        check_params_positive(n_clusters: n_clusters, max_iter: max_iter, tol: tol)
-        @params = {}
-        @params[:n_clusters] = n_clusters
-        @params[:affinity] = affinity
-        @params[:gamma] = gamma
-        @params[:init] = init == 'random' ? 'random' : 'k-means++'
-        @params[:max_iter] = max_iter
-        @params[:tol] = tol
-        @params[:random_seed] = random_seed
-        @params[:random_seed] ||= srand
-        @embedding = nil
-        @labels = nil
-      end
-
-      # Analysis clusters with given training data.
-      # To execute this method, Numo::Linalg must be loaded.
-      #
-      # @overload fit(x) -> SpectralClustering
-      #   @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 affinity matrix (shape: [n_samples, n_samples]).
-      # @return [SpectralClustering] The learned cluster analyzer itself.
-      def fit(x, _y = nil)
-        x = check_convert_sample_array(x)
-        raise ArgumentError, 'Expect the input affinity matrix to be square.' if @params[:affinity] == 'precomputed' && x.shape[0] != x.shape[1]
-        raise 'SpectralClustering#fit requires Numo::Linalg but that is not loaded.' unless enable_linalg?
-
-        fit_predict(x)
-        self
-      end
-
-      # Analysis clusters and assign samples to clusters.
-      # To execute this method, Numo::Linalg must be loaded.
-      #
-      # @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 affinity 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 affinity matrix to be square.' if @params[:affinity] == 'precomputed' && x.shape[0] != x.shape[1]
-        raise 'SpectralClustering#fit_predict requires Numo::Linalg but that is not loaded.' unless enable_linalg?
-
-        affinity_mat = @params[:metric] == 'precomputed' ? x : Rumale::PairwiseMetric.rbf_kernel(x, nil, @params[:gamma])
-        @embedding = embedded_space(affinity_mat, @params[:n_clusters])
-        normalized_embedding = Rumale::Preprocessing::L2Normalizer.new.fit_transform(@embedding)
-        @labels = kmeans_clustering(normalized_embedding)
-      end
-
-      private
-
-      def embedded_space(affinity_mat, n_clusters)
-        affinity_mat[affinity_mat.diag_indices] = 0.0
-        degrees = 1.0 / Numo::NMath.sqrt(affinity_mat.sum(axis: 1))
-        laplacian_mat = degrees.diag.dot(affinity_mat).dot(degrees.diag)
-
-        n_samples = affinity_mat.shape[0]
-        _, eig_vecs = Numo::Linalg.eigh(laplacian_mat, vals_range: (n_samples - n_clusters)...n_samples)
-        eig_vecs.reverse(1).dup
-      end
-
-      def kmeans_clustering(x)
-        Rumale::Clustering::KMeans.new(
-          n_clusters: @params[:n_clusters], init: @params[:init],
-          max_iter: @params[:max_iter], tol: @params[:tol], random_seed: @params[:random_seed]
-        ).fit_predict(x)
-      end
-    end
-  end
-end