rumale-manifold 0.28.0 → 0.29.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '018cc8a819b686d66641f8b66e0ffeb13a7f5351ab58cc7f7b2ee79bfe0d06c6'
-  data.tar.gz: 8e53624cc56092803808adba9a5614eb7ac451b2b83ad9a5966d1fea9a694cd4
+  metadata.gz: 8d9fa70278c2f220eca36209fa6a29b33733826e1bacd26bfc96b6f84f2a93ff
+  data.tar.gz: e21890d3e97490958e5c43793d70de271c43f43386b91ecbe50703160a6305ce
 SHA512:
-  metadata.gz: 67e828ffa83b84a7bb0cd9c910ea4f696ab94f245afa008ff94caa615cfc4e25ea4b057e52602a4e0953728f8720a70953d295935e13450dbdd44e5ee56e6be4
-  data.tar.gz: 91d0247aa5e1366f0740cc6a86343591abfc8a555df023983c16794d2d746635bbbe4a5074cb34d8b2e41e2e689aac26632ad46d8271e375201981eb07d1a830
+  metadata.gz: 23d964b84ff080aada02bcab0a5aec0707023cc28318e6ea4eb49ecf656cb5cf2c5261c1a7493e1e4624039a347e3bb4f343ef82e0d8c88f73385fe9f6616980
+  data.tar.gz: c2c32e786fd0b57ad0b7a2ff9987b551bfc61c90bfc0dfbfb39450350fbe075815e6fc9179a0ad1dfcd8f9142af39b4f829b5f04586bf2c5b109600d25710c13

data/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2022-2023 Atsushi Tatsuma
+Copyright (c) 2022-2024 Atsushi Tatsuma
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without

data/lib/rumale/manifold/hessian_eigenmaps.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+require 'rumale/base/estimator'
+require 'rumale/base/transformer'
+require 'rumale/pairwise_metric'
+require 'rumale/validation'
+
+module Rumale
+  module Manifold
+    # HessianEigenmaps is a class that implements Hessian Eigenmaps.
+    #
+    # @example
+    #   require 'numo/linalg/autoloader'
+    #   require 'rumale/manifold/hessian_eigenmaps'
+    #
+    #   hem = Rumale::Manifold::HessianEigenmaps.new(n_components: 2, n_neighbors: 15)
+    #   z = hem.fit_transform(x)
+    #
+    # *Reference*
+    # - Donoho, D. L., and Grimes, C., "Hessian eigenmaps: Locally linear embedding techniques for high-dimensional data," Proc. Natl. Acad. Sci. USA, vol. 100, no. 10, pp. 5591--5596, 2003.
+    class HessianEigenmaps < Rumale::Base::Estimator
+      include Rumale::Base::Transformer
+
+      # Return the data in representation space.
+      # @return [Numo::DFloat] (shape: [n_samples, n_components])
+      attr_reader :embedding
+
+      # Create a new transformer with Hessian Eigenmaps.
+      #
+      # @param n_components [Integer] The number of dimensions on representation space.
+      # @param n_neighbors [Integer] The number of nearest neighbors for k-nearest neighbor graph construction.
+      # @param reg_param [Float] The reguralization parameter for local gram matrix in transform method.
+      def initialize(n_neighbors: 5, n_components: 2, reg_param: 1e-6)
+        super()
+        @params = {
+          n_neighbors: n_neighbors,
+          n_components: n_components,
+          reg_param: reg_param
+        }
+      end
+
+      # Fit the model with given training data.
+      #
+      # @overload fit(x) -> HessianEigenmaps
+      #   @param x [Numo::DFloat] (shape: [n_samples, n_features]) The training data to be used for fitting the model.
+      #   @return [HessianEigenmaps] The learned transformer itself.
+      def fit(x, _y = nil) # rubocop:disable Metrics/AbcSize
+        raise 'HessianEigenmaps#fit requires Numo::Linalg but that is not loaded' unless enable_linalg?(warning: false)
+
+        x = Rumale::Validation.check_convert_sample_array(x)
+
+        n_samples = x.shape[0]
+        distance_mat = Rumale::PairwiseMetric.squared_error(x)
+        neighbor_ids = neighbor_ids(distance_mat, @params[:n_neighbors], true)
+
+        tri_n_components = @params[:n_components] * (@params[:n_components] + 1) / 2
+        hessian_mat = Numo::DFloat.zeros(n_samples * tri_n_components, n_samples)
+        ones = Numo::DFloat.ones(@params[:n_neighbors], 1)
+        n_samples.times do |i|
+          tan_coords = tangent_coordinates(x[neighbor_ids[i, true], true])
+          xi = Numo::DFloat.zeros(@params[:n_neighbors], tri_n_components)
+          @params[:n_components].times do |m|
+            offset = Array.new(m + 1) { |v| v }.sum
+            (@params[:n_components] - m).times do |n|
+              xi[true, m * @params[:n_components] - offset + n] = tan_coords[true, m] * tan_coords[true, m + n]
+            end
+          end
+
+          xt, = Numo::Linalg.qr(Numo::DFloat.hstack([ones, tan_coords, xi]))
+          pii = xt[true, (@params[:n_components] + 1)..-1]
+          tri_n_components.times do |j|
+            pj_sum = pii[true, j].sum
+            normalizer = pj_sum <= 1e-8 ? 1 : 1.fdiv(pj_sum)
+            hessian_mat[i * tri_n_components + j, neighbor_ids[i, true]] = pii[true, j] * normalizer
+          end
+        end
+
+        kernel_mat = hessian_mat.transpose.dot(hessian_mat)
+        _, eig_vecs = Numo::Linalg.eigh(kernel_mat, vals_range: 1...(1 + @params[:n_components]))
+
+        @embedding = @params[:n_components] == 1 ? eig_vecs[true, 0].dup : eig_vecs.dup
+        @x_train = x.dup
+
+        self
+      end
+
+      # Fit the model with training data, and then transform them with the learned model.
+      #
+      # @overload fit_transform(x) -> Numo::DFloat
+      #   @param x [Numo::DFloat] (shape: [n_samples, n_features]) The training data to be used for fitting the model.
+      #   @return [Numo::DFloat] (shape: [n_samples, n_components]) The transformed data
+      def fit_transform(x, _y = nil)
+        unless enable_linalg?(warning: false)
+          raise 'HessianEigenmaps#fit_transform requires Numo::Linalg but that is not loaded'
+        end
+
+        fit(x)
+
+        @embedding.dup
+      end
+
+      # Transform the given data with the learned model.
+      # For out-of-sample data embedding, the same method as Locally Linear Embedding is used.
+      #
+      # @param x [Numo::DFloat] (shape: [n_samples, n_features]) The data to be transformed with the learned model.
+      # @return [Numo::DFloat] (shape: [n_samples, n_components]) The transformed data.
+      def transform(x)
+        x = Rumale::Validation.check_convert_sample_array(x)
+
+        n_samples = x.shape[0]
+        tol = @params[:reg_param].fdiv(@params[:n_neighbors])
+        distance_mat = Rumale::PairwiseMetric.squared_error(x, @x_train)
+        neighbor_ids = neighbor_ids(distance_mat, @params[:n_neighbors], false)
+        weight_mat = Numo::DFloat.zeros(n_samples, @x_train.shape[0])
+
+        n_samples.times do |n|
+          x_local = @x_train[neighbor_ids[n, true], true] - x[n, true]
+          gram_mat = x_local.dot(x_local.transpose)
+          gram_mat += tol * weight_mat.trace * Numo::DFloat.eye(@params[:n_neighbors])
+          weights = Numo::Linalg.solve(gram_mat, Numo::DFloat.ones(@params[:n_neighbors]))
+          weights /= weights.sum + 1e-8
+          weight_mat[n, neighbor_ids[n, true]] = weights
+        end
+
+        weight_mat.dot(@embedding)
+      end
+
+      private
+
+      def neighbor_ids(distance_mat, n_neighbors, contain_self)
+        n_samples = distance_mat.shape[0]
+        neighbor_ids = Numo::Int32.zeros(n_samples, n_neighbors)
+        if contain_self
+          n_samples.times { |n| neighbor_ids[n, true] = (distance_mat[n, true].sort_index.to_a - [n])[0...n_neighbors] }
+        else
+          n_samples.times { |n| neighbor_ids[n, true] = distance_mat[n, true].sort_index.to_a[0...n_neighbors] }
+        end
+        neighbor_ids
+      end
+
+      def tangent_coordinates(x)
+        m = x.mean(axis: 0)
+        cx = x - m
+        cov_mat = cx.transpose.dot(cx)
+        n_features = x.shape[1]
+        _, evecs = Numo::Linalg.eigh(cov_mat, vals_range: (n_features - @params[:n_components])...n_features)
+        cx.dot(evecs.reverse(1))
+      end
+    end
+  end
+end

data/lib/rumale/manifold/local_tangent_space_alignment.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+require 'rumale/base/estimator'
+require 'rumale/base/transformer'
+require 'rumale/pairwise_metric'
+require 'rumale/validation'
+
+module Rumale
+  module Manifold
+    # LocalTangentSpaceAlignment is a class that implements Local Tangent Space Alignment.
+    #
+    # @example
+    #   require 'numo/linalg/autoloader'
+    #   require 'rumale/manifold/local_tangent_space_alignment'
+    #
+    #   lem = Rumale::Manifold::LocalTangentSpaceAlignment.new(n_components: 2, n_neighbors: 15)
+    #   z = lem.fit_transform(x)
+    #
+    # *Reference*
+    # - Zhang, A., and Zha, H., "Principal Manifolds and Nonlinear Diemnsion Reduction via Local Tangent Space Alignment," SIAM Journal on Scientific Computing, vol. 26, iss. 1, pp. 313-338, 2004.
+    class LocalTangentSpaceAlignment < Rumale::Base::Estimator
+      include Rumale::Base::Transformer
+
+      # Return the data in representation space.
+      # @return [Numo::DFloat] (shape: [n_samples, n_components])
+      attr_reader :embedding
+
+      # Create a new transformer with Local Tangent Space Alignment.
+      #
+      # @param n_components [Integer] The number of dimensions on representation space.
+      # @param n_neighbors [Integer] The number of nearest neighbors for finding k-nearest neighbors
+      # @param reg_param [Float] The reguralization parameter for local gram matrix in transform method.
+      def initialize(n_components: 2, n_neighbors: 10, reg_param: 1e-3)
+        super()
+        @params = {
+          n_components: n_components,
+          n_neighbors: [1, n_neighbors].max,
+          reg_param: reg_param
+        }
+      end
+
+      # Fit the model with given training data.
+      #
+      # @overload fit(x) -> LocalTangentSpaceAlignment
+      #   @param x [Numo::DFloat] (shape: [n_samples, n_features]) The training data to be used for fitting the model.
+      #   @return [LocalTangentSpaceAlignment] The learned transformer itself.
+      def fit(x, _y = nil)
+        unless enable_linalg?(warning: false)
+          raise 'LocalTangentSpaceAlignment#fit requires Numo::Linalg but that is not loaded'
+        end
+
+        x = Rumale::Validation.check_convert_sample_array(x)
+
+        n_samples = x.shape[0]
+        distance_mat = Rumale::PairwiseMetric.squared_error(x)
+        neighbor_ids = neighbor_ids(distance_mat, @params[:n_neighbors], true)
+
+        affinity_mat = Numo::DFloat.zeros(n_samples, n_samples)
+        x_tangent = Numo::DFloat.zeros(@params[:n_neighbors], @params[:n_components] + 1)
+        x_tangent[true, 0] = 1.fdiv(Math.sqrt(@params[:n_neighbors]))
+
+        n_samples.times do |n|
+          x_local = x[neighbor_ids[n, true], true]
+          x_tangent[true, 1...] = right_singular_vectors(x_local, @params[:n_components])
+          weight_mat = x_tangent.dot(x_tangent.transpose)
+          neighbor_ids[n, true].each_with_index do |m, i|
+            affinity_mat[m, neighbor_ids[n, true]] -= weight_mat[i, true]
+            affinity_mat[m, m] += 1
+          end
+        end
+
+        kernel_mat = 0.5 * (affinity_mat.transpose + affinity_mat)
+        _, eig_vecs = Numo::Linalg.eigh(kernel_mat, vals_range: 1...(1 + @params[:n_components]))
+
+        @embedding = @params[:n_components] == 1 ? eig_vecs[true, 0].dup : eig_vecs.dup
+        @x_train = x.dup
+
+        self
+      end
+
+      # Fit the model with training data, and then transform them with the learned model.
+      #
+      # @overload fit_transform(x) -> Numo::DFloat
+      #   @param x [Numo::DFloat] (shape: [n_samples, n_features]) The training data to be used for fitting the model.
+      #   @return [Numo::DFloat] (shape: [n_samples, n_components]) The transformed data
+      def fit_transform(x, _y = nil)
+        unless enable_linalg?(warning: false)
+          raise 'LocalTangentSpaceAlignment#fit_transform requires Numo::Linalg but that is not loaded'
+        end
+
+        fit(x).transform(x)
+      end
+
+      # Transform the given data with the learned model.
+      # For out-of-sample data embedding, the same method as Locally Linear Embedding is used.
+      #
+      # @param x [Numo::DFloat] (shape: [n_samples, n_features]) The data to be transformed with the learned model.
+      # @return [Numo::DFloat] (shape: [n_samples, n_components]) The transformed data.
+      def transform(x)
+        x = Rumale::Validation.check_convert_sample_array(x)
+
+        n_samples = x.shape[0]
+        tol = @params[:reg_param].fdiv(@params[:n_neighbors])
+        distance_mat = Rumale::PairwiseMetric.squared_error(x, @x_train)
+        neighbor_ids = neighbor_ids(distance_mat, @params[:n_neighbors], false)
+        weight_mat = Numo::DFloat.zeros(n_samples, @x_train.shape[0])
+
+        n_samples.times do |n|
+          x_local = @x_train[neighbor_ids[n, true], true] - x[n, true]
+          gram_mat = x_local.dot(x_local.transpose)
+          gram_mat += tol * weight_mat.trace * Numo::DFloat.eye(@params[:n_neighbors])
+          weights = Numo::Linalg.solve(gram_mat, Numo::DFloat.ones(@params[:n_neighbors]))
+          weights /= weights.sum + 1e-8
+          weight_mat[n, neighbor_ids[n, true]] = weights
+        end
+
+        weight_mat.dot(@embedding)
+      end
+
+      private
+
+      def neighbor_ids(distance_mat, n_neighbors, contain_self)
+        n_samples = distance_mat.shape[0]
+        neighbor_ids = Numo::Int32.zeros(n_samples, n_neighbors)
+        if contain_self
+          n_samples.times { |n| neighbor_ids[n, true] = (distance_mat[n, true].sort_index.to_a - [n])[0...n_neighbors] }
+        else
+          n_samples.times { |n| neighbor_ids[n, true] = distance_mat[n, true].sort_index.to_a[0...n_neighbors] }
+        end
+        neighbor_ids
+      end
+
+      def right_singular_vectors(x_local, n_singulars)
+        n_samples = x_local.shape[0]
+        x_local -= x_local.mean(0)
+        gram_mat = x_local.dot(x_local.transpose)
+        _, evecs = Numo::Linalg.eigh(gram_mat, vals_range: (n_samples - n_singulars)...n_samples)
+        evecs.reverse(1).dup
+      end
+    end
+  end
+end

data/lib/rumale/manifold/locally_linear_embedding.rb

@@ -7,7 +7,7 @@ require 'rumale/validation'
 
 module Rumale
   module Manifold
-    # LocallyLinearEmbedding is a class that implements Loccaly Linear Embedding.
+    # LocallyLinearEmbedding is a class that implements Locally Linear Embedding.
     #
     # @example
     #   require 'numo/linalg/autoloader'

data/lib/rumale/manifold/version.rb

@@ -5,6 +5,6 @@ module Rumale
   # Module for data embedding algorithms.
   module Manifold
     # @!visibility private
-    VERSION = '0.28.0'
+    VERSION = '0.29.0'
   end
 end

data/lib/rumale/manifold.rb

@@ -4,6 +4,8 @@ require 'numo/narray'
 
 require_relative 'manifold/laplacian_eigenmaps'
 require_relative 'manifold/locally_linear_embedding'
+require_relative 'manifold/hessian_eigenmaps'
+require_relative 'manifold/local_tangent_space_alignment'
 require_relative 'manifold/mds'
 require_relative 'manifold/tsne'
 require_relative 'manifold/version'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rumale-manifold
 version: !ruby/object:Gem::Version
-  version: 0.28.0
+  version: 0.29.0
 platform: ruby
 authors:
 - yoshoku
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-11-12 00:00:00.000000000 Z
+date: 2024-03-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: numo-narray
@@ -30,31 +30,32 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.28.0
+        version: 0.29.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.28.0
+        version: 0.29.0
 - !ruby/object:Gem::Dependency
   name: rumale-decomposition
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.28.0
+        version: 0.29.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.28.0
+        version: 0.29.0
 description: |
   Rumale::Manifold provides data embedding algorithms,
-  such as Multi-dimensional Scaling and t-distributed Stochastic Neighbor Embedding,
+  such as Multi-dimensional Scaling, Locally Linear Embedding, Laplacian Eigenmaps, Hessian Eigenmaps,
+  and t-distributed Stochastic Neighbor Embedding,
   with Rumale interface.
 email:
 - yoshoku@outlook.com
@@ -65,7 +66,9 @@ files:
 - LICENSE.txt
 - README.md
 - lib/rumale/manifold.rb
+- lib/rumale/manifold/hessian_eigenmaps.rb
 - lib/rumale/manifold/laplacian_eigenmaps.rb
+- lib/rumale/manifold/local_tangent_space_alignment.rb
 - lib/rumale/manifold/locally_linear_embedding.rb
 - lib/rumale/manifold/mds.rb
 - lib/rumale/manifold/tsne.rb
@@ -93,7 +96,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.20
+rubygems_version: 3.5.7
 signing_key:
 specification_version: 4
 summary: Rumale::Manifold provides data embedding algorithms with Rumale interface.