rumale-decomposition 0.28.1 → 0.29.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aeae1f02b5c8e25473327db4cacc3c60e68fe430d3908a1c63c5225d11550979
-  data.tar.gz: be0180f9bd0596bfa84b4f14621a1793badae6f290abc8216677fe923aa478cd
+  metadata.gz: 84715613fb41ef3b6961b9280f6750fc831daa161ddee4e3666ab906e0670599
+  data.tar.gz: c3079e09e5ca5b011d8067457eb89a451b8fd0819a8f996630018a1b4cac41e7
 SHA512:
-  metadata.gz: ea0aa55f3f1980b70e81394a80da289c39d26a4d688b27af8ffbb4f0edf03a3e278be33312eae8262a6dbdac60800c98f54ccf4901dde175288b33defe794e3c
-  data.tar.gz: b1882c08b9a13018dc7de6d56af43720bc06199cfaf530543d3d5e3d37aa20bb1e5843dc605589167d16593fdaf2863791d7c560d45d2940cdc044863e2e145d
+  metadata.gz: 8568f69c7acdf8ccc2c14ba6c9281e1ba145bcd400bf80ef9cbbdedd12f337455614170b1c5eff94c45ae8453ba00fb515deaad4a1ca0a56576a023264006f31
+  data.tar.gz: de013d05ad22b323d03e3eecac12edff941c3ecf9ad02e21a2302ee75cd6574cd06ccb1612d15bf758315191960065098212f70f8ea6980a26417dee3ef6090d

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/decomposition/sparse_pca.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+require 'rumale/base/estimator'
+require 'rumale/base/transformer'
+require 'rumale/utils'
+require 'rumale/validation'
+
+module Rumale
+  module Decomposition
+    # SparsePCA is a class that implements Sparse Principal Component Analysis.
+    #
+    # @example
+    #   require 'numo/tiny_linalg'
+    #   Numo::Linalg = Numo::TinyLinalg
+    #
+    #   require 'rumale/decomposition/sparse_pca'
+    #
+    #   decomposer = Rumale::Decomposition::SparsePCA.new(n_components: 2, reg_param: 0.1)
+    #   representaion = decomposer.fit_transform(samples)
+    #   sparse_components = decomposer.components
+    #
+    # *Reference*
+    # - Macky, L., "Deflation Methods for Sparse PCA," Advances in NIPS'08, pp. 1017--1024, 2008.
+    # - Hein, M. and Bühler, T., "An Inverse Power Method for Nonlinear Eigenproblems with Applications in 1-Spectral Clustering and Sparse PCA," Advances in NIPS'10, pp. 847--855, 2010.
+    class SparsePCA < ::Rumale::Base::Estimator
+      include ::Rumale::Base::Transformer
+
+      # Returns the principal components.
+      # @return [Numo::DFloat] (shape: [n_components, n_features])
+      attr_reader :components
+
+      # Returns the mean vector.
+      # @return [Numo::DFloat] (shape: [n_features])
+      attr_reader :mean
+
+      # Return the random generator.
+      # @return [Random]
+      attr_reader :rng
+
+      # Create a new transformer with Sparse PCA.
+      #
+      # @param n_components [Integer] The number of principal components.
+      # @param reg_param [Float] The regularization parameter (interval: [0, 1]).
+      # @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_components: 2, reg_param: 0.001, max_iter: 1000, tol: 1e-6, random_seed: nil)
+        super()
+
+        warn('reg_param should be in the interval [0, 1].') unless (0..1).cover?(reg_param)
+
+        @params = {
+          n_components: n_components,
+          reg_param: reg_param,
+          max_iter: max_iter,
+          tol: tol,
+          random_seed: random_seed || srand
+        }
+        @rng = Random.new(@params[:random_seed])
+      end
+
+      # Fit the model with given training data.
+      #
+      # @overload fit(x) -> SparsePCA
+      #   @param x [Numo::DFloat] (shape: [n_samples, n_features]) The training data to be used for fitting the model.
+      #   @return [SparsePCA] The learned transformer itself.
+      def fit(x, _y = nil)
+        x = ::Rumale::Validation.check_convert_sample_array(x)
+
+        # initialize some variables.
+        @components = Numo::DFloat.zeros(@params[:n_components], x.shape[1])
+
+        # centering.
+        @mean = x.mean(axis: 0)
+        centered_x = x - @mean
+
+        # optimization.
+        partial_fit(centered_x)
+
+        @components = @components[0, true].dup if @params[:n_components] == 1
+
+        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)
+        x = ::Rumale::Validation.check_convert_sample_array(x)
+
+        fit(x).transform(x)
+      end
+
+      # Transform the given data with the learned model.
+      #
+      # @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)
+
+        (x - @mean).dot(@components.transpose)
+      end
+
+      private
+
+      def partial_fit(x)
+        sub_rng = @rng.dup
+        n_samples, n_features = x.shape
+        cov_mat = x.transpose.dot(x) / n_samples
+        prj_mat = Numo::DFloat.eye(n_features)
+        @params[:n_components].times do |i|
+          f = ::Rumale::Utils.rand_normal(n_features, sub_rng)
+          xf = x.dot(f)
+          norm_xf = norm(xf, 2)
+          coeff = coeff_numerator(f).fdiv(norm_xf)
+          mu = cov_mat.dot(f) / norm_xf
+          @params[:max_iter].times do |_t|
+            g = sign(mu) * Numo::DFloat.maximum(coeff * mu.abs - @params[:reg_param], 0)
+            f = g / norm(x.dot(g), 2)
+            mu = cov_mat.dot(f) / norm(x.dot(f), 2)
+            coeff_new = coeff_numerator(f)
+
+            break if (coeff - coeff_new).abs.fdiv(coeff) < @params[:tol]
+
+            coeff = coeff_new
+          end
+
+          # deflation
+          q = prj_mat.dot(f)
+          qqt = Numo::DFloat.eye(n_features) - q.outer(q)
+          x = x.dot(qqt)
+          cov_mat = qqt.dot(cov_mat).dot(qqt)
+          prj_mat = prj_mat.dot(qqt)
+          f /= norm(f, 2)
+
+          @components[i, true] = f.dup
+        end
+      end
+
+      def coeff_numerator(f)
+        (1 - @params[:reg_param]) * norm(f, 2) + @params[:reg_param] * norm(f, 1)
+      end
+
+      def sign(v)
+        r = Numo::DFloat.zeros(v.size)
+        r[v.lt(0)] = -1
+        r[v.gt(0)] = 1
+        r
+      end
+
+      def norm(v, ord)
+        nrm = if defined?(Numo::Linalg)
+                Numo::Linalg.norm(v, ord)
+              elsif ord == 2
+                Math.sqrt(v.dot(v))
+              else
+                v.abs.sum
+              end
+        nrm.zero? ? 1.0 : nrm
+      end
+    end
+  end
+end

data/lib/rumale/decomposition/version.rb

@@ -5,6 +5,6 @@ module Rumale
   # Module for matrix decomposition algorithms.
   module Decomposition
     # @!visibility private
-    VERSION = '0.28.1'
+    VERSION = '0.29.0'
   end
 end

data/lib/rumale/decomposition.rb

@@ -6,4 +6,5 @@ require_relative 'decomposition/factor_analysis'
 require_relative 'decomposition/fast_ica'
 require_relative 'decomposition/nmf'
 require_relative 'decomposition/pca'
+require_relative 'decomposition/sparse_pca'
 require_relative 'decomposition/version'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rumale-decomposition
 version: !ruby/object:Gem::Version
-  version: 0.28.1
+  version: 0.29.0
 platform: ruby
 authors:
 - yoshoku
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-12-24 00:00:00.000000000 Z
+date: 2024-03-30 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.28.1
+        version: 0.29.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.28.1
+        version: 0.29.0
 description: |
   Rumale::Decomposition provides matrix decomposition algorithms,
   such as Principal Component Analysis, Non-negative Matrix Factorization, Factor Analysis, and Independent Component Analysis,
@@ -55,6 +55,7 @@ files:
 - lib/rumale/decomposition/fast_ica.rb
 - lib/rumale/decomposition/nmf.rb
 - lib/rumale/decomposition/pca.rb
+- lib/rumale/decomposition/sparse_pca.rb
 - lib/rumale/decomposition/version.rb
 homepage: https://github.com/yoshoku/rumale
 licenses:
@@ -80,7 +81,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.22
+rubygems_version: 3.5.7
 signing_key:
 specification_version: 4
 summary: Rumale::Decomposition provides matrix decomposition algorithms with Rumale