rumale-feature_extraction 0.24.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7927d78c3c8294fdaba1f509c5bfa0d3d5960d5813cba42aaa5c2765317064dd
+  data.tar.gz: 43422862894245c61da3b8973a3991cccf80d87f901fbab635077a00fe7670d8
+SHA512:
+  metadata.gz: 9127e6789c784861dc6302cbd69b6abc6afc841e8ba22ef0e4b1b42cd0a575433fe79e37c3797eee632560cf7d0a7585aee1e2a28ee7d1df8ae770c5be2f587f
+  data.tar.gz: a0455a7c16fc510d2428d9476e22d883bb1377779552daba8243ce20bdd332df69be4f3143aa1d4abe2bc4b319210c06872ff6239a25565fa13da82298113b13

data/LICENSE.txt

@@ -0,0 +1,27 @@
+Copyright (c) 2022 Atsushi Tatsuma
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+* Neither the name of the copyright holder nor the names of its
+  contributors may be used to endorse or promote products derived from
+  this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,34 @@
+# Rumale::FeatureExtraction
+
+[![Gem Version](https://badge.fury.io/rb/rumale-feature_extraction.svg)](https://badge.fury.io/rb/rumale-feature_extraction)
+[![BSD 3-Clause License](https://img.shields.io/badge/License-BSD%203--Clause-orange.svg)](https://github.com/yoshoku/rumale/blob/main/rumale-feature_extraction/LICENSE.txt)
+[![Documentation](https://img.shields.io/badge/api-reference-blue.svg)](https://yoshoku.github.io/rumale/doc/Rumale/FeatureExtraction.html)
+
+Rumale is a machine learning library in Ruby.
+Rumale::FeatureExtraction provides feature extraction methods,
+such as TF-IDF and feature hashing,
+with Rumale interface.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'rumale-feature_extraction'
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install rumale-feature_extraction
+
+## Documentation
+
+- [Rumale API Documentation - FeatureExtraction](https://yoshoku.github.io/rumale/doc/Rumale/FeatureExtraction.html)
+
+## License
+
+The gem is available as open source under the terms of the [BSD-3-Clause License](https://opensource.org/licenses/BSD-3-Clause).

data/lib/rumale/feature_extraction/feature_hasher.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require 'mmh3'
+
+require 'rumale/base/estimator'
+require 'rumale/base/transformer'
+
+module Rumale
+  module FeatureExtraction
+    # Encode array of feature-value hash to vectors with feature hashing (hashing trick).
+    # This encoder turns array of mappings (Array<Hash>) with pairs of feature names and values into Numo::NArray.
+    # This encoder employs signed 32-bit Murmurhash3 as the hash function.
+    #
+    # @example
+    #   require 'rumale/feature_extraction/feature_hasher'
+    #
+    #   encoder = Rumale::FeatureExtraction::FeatureHasher.new(n_features: 10)
+    #   x = encoder.transform([
+    #     { dog: 1, cat: 2, elephant: 4 },
+    #     { dog: 2, run: 5 }
+    #   ])
+    #
+    #   # > pp x
+    #   # Numo::DFloat#shape=[2,10]
+    #   # [[0, 0, -4, -1, 0, 0, 0, 0, 0, 2],
+    #   #  [0, 0, 0, -2, -5, 0, 0, 0, 0, 0]]
+    class FeatureHasher < ::Rumale::Base::Estimator
+      include ::Rumale::Base::Transformer
+
+      # Create a new encoder for converting array of hash consisting of feature names and values to vectors
+      # with feature hashing algorith.
+      #
+      # @param n_features [Integer] The number of features of encoded samples.
+      # @param alternate_sign [Boolean] The flag indicating whether to reflect the sign of the hash value to the feature value.
+      def initialize(n_features: 1024, alternate_sign: true)
+        super()
+        @params = {
+          n_features: n_features,
+          alternate_sign: alternate_sign
+        }
+      end
+
+      # This method does not do anything. The encoder does not require training.
+      #
+      # @overload fit(x) -> FeatureHasher
+      #   @param x [Array<Hash>] (shape: [n_samples]) The array of hash consisting of feature names and values.
+      #   @return [FeatureHasher]
+      def fit(_x = nil, _y = nil)
+        self
+      end
+
+      # Encode given the array of feature-value hash.
+      # This method has the same output as the transform method
+      # because the encoder does not require training.
+      #
+      # @overload fit_transform(x) -> Numo::DFloat
+      #   @param x [Array<Hash>] (shape: [n_samples]) The array of hash consisting of feature names and values.
+      #   @return [Numo::DFloat] (shape: [n_samples, n_features]) The encoded sample array.
+      def fit_transform(x, _y = nil)
+        fit(x).transform(x)
+      end
+
+      # Encode given the array of feature-value hash.
+      #
+      # @param x [Array<Hash>] (shape: [n_samples]) The array of hash consisting of feature names and values.
+      # @return [Numo::DFloat] (shape: [n_samples, n_features]) The encoded sample array.
+      def transform(x)
+        x = [x] unless x.is_a?(Array)
+        n_samples = x.size
+
+        z = Numo::DFloat.zeros(n_samples, n_features)
+
+        x.each_with_index do |f, i|
+          f.each do |k, v|
+            k = "#{k}=#{v}" if v.is_a?(String)
+            val = v.is_a?(String) ? 1 : v
+            next if val.zero?
+
+            h = Mmh3.hash32(k)
+            fid = h.abs % n_features
+            val *= h >= 0 ? 1 : -1 if alternate_sign?
+            z[i, fid] = val
+          end
+        end
+
+        z
+      end
+
+      private
+
+      def n_features
+        @params[:n_features]
+      end
+
+      def alternate_sign?
+        @params[:alternate_sign]
+      end
+    end
+  end
+end

data/lib/rumale/feature_extraction/hash_vectorizer.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+require 'rumale/base/estimator'
+require 'rumale/base/transformer'
+
+module Rumale
+  module FeatureExtraction
+    # Encode array of feature-value hash to vectors.
+    # This encoder turns array of mappings (Array<Hash>) with pairs of feature names and values into Numo::NArray.
+    #
+    # @example
+    #   require 'rumale/feature_extraction/hash_vectorizer'
+    #
+    #   encoder = Rumale::FeatureExtraction::HashVectorizer.new
+    #   x = encoder.fit_transform([
+    #     { foo: 1, bar: 2 },
+    #     { foo: 3, baz: 1 }
+    #   ])
+    #
+    #   # > pp x
+    #   # Numo::DFloat#shape=[2,3]
+    #   # [[2, 0, 1],
+    #   #  [0, 1, 3]]
+    #
+    #   x = encoder.fit_transform([
+    #     { city: 'Dubai',  temperature: 33 },
+    #     { city: 'London', temperature: 12 },
+    #     { city: 'San Francisco', temperature: 18 }
+    #   ])
+    #
+    #   # > pp x
+    #   # Numo::DFloat#shape=[3,4]
+    #   # [[1, 0, 0, 33],
+    #   #  [0, 1, 0, 12],
+    #   #  [0, 0, 1, 18]]
+    #   # > pp encoder.inverse_transform(x)
+    #   # [{:city=>"Dubai", :temperature=>33.0},
+    #   #  {:city=>"London", :temperature=>12.0},
+    #   #  {:city=>"San Francisco", :temperature=>18.0}]
+    class HashVectorizer < ::Rumale::Base::Estimator
+      include ::Rumale::Base::Transformer
+
+      # Return the list of feature names.
+      # @return [Array] (size: [n_features])
+      attr_reader :feature_names
+
+      # Return the hash consisting of pairs of feature names and indices.
+      # @return [Hash] (size: [n_features])
+      attr_reader :vocabulary
+
+      # Create a new encoder for converting array of hash consisting of feature names and values to vectors.
+      #
+      # @param separator [String] The separator string used for constructing new feature names for categorical feature.
+      # @param sort [Boolean] The flag indicating whether to sort feature names.
+      def initialize(separator: '=', sort: true)
+        super()
+        @params = {
+          separator: separator,
+          sort: sort
+        }
+      end
+
+      # Fit the encoder with given training data.
+      #
+      # @overload fit(x) -> HashVectorizer
+      #   @param x [Array<Hash>] (shape: [n_samples]) The array of hash consisting of feature names and values.
+      #   @return [HashVectorizer]
+      def fit(x, _y = nil)
+        @feature_names = []
+        @vocabulary = {}
+
+        x.each do |f|
+          f.each do |k, v|
+            k = "#{k}#{separator}#{v}".to_sym if v.is_a?(String)
+            next if @vocabulary.key?(k)
+
+            @feature_names.push(k)
+            @vocabulary[k] = @vocabulary.size
+          end
+        end
+
+        if sort_feature?
+          @feature_names.sort!
+          @feature_names.each_with_index { |k, i| @vocabulary[k] = i }
+        end
+
+        self
+      end
+
+      # Fit the encoder with given training data, then return encoded data.
+      #
+      # @overload fit_transform(x) -> Numo::DFloat
+      #   @param x [Array<Hash>] (shape: [n_samples]) The array of hash consisting of feature names and values.
+      #   @return [Numo::DFloat] (shape: [n_samples, n_features]) The encoded sample array.
+      def fit_transform(x, _y = nil)
+        fit(x).transform(x)
+      end
+
+      # Encode given the array of feature-value hash.
+      #
+      # @param x [Array<Hash>] (shape: [n_samples]) The array of hash consisting of feature names and values.
+      # @return [Numo::DFloat] (shape: [n_samples, n_features]) The encoded sample array.
+      def transform(x)
+        x = [x] unless x.is_a?(Array)
+        n_samples = x.size
+        n_features = @vocabulary.size
+        z = Numo::DFloat.zeros(n_samples, n_features)
+
+        x.each_with_index do |f, i|
+          f.each do |k, v|
+            if v.is_a?(String)
+              k = "#{k}#{separator}#{v}".to_sym
+              v = 1
+            end
+            z[i, @vocabulary[k]] = v if @vocabulary.key?(k)
+          end
+        end
+
+        z
+      end
+
+      # Decode sample matirx to the array of feature-value hash.
+      #
+      # @param x [Numo::DFloat] (shape: [n_samples, n_features]) The encoded sample array.
+      # @return [Array<Hash>] The array of hash consisting of feature names and values.
+      def inverse_transform(x)
+        n_samples = x.shape[0]
+        reconst = []
+
+        n_samples.times do |i|
+          f = {}
+          x[i, true].each_with_index do |el, j|
+            feature_key_val(@feature_names[j], el).tap { |k, v| f[k.to_sym] = v } unless el.zero?
+          end
+          reconst.push(f)
+        end
+
+        reconst
+      end
+
+      private
+
+      def feature_key_val(fname, fval)
+        f = fname.to_s.split(separator)
+        f.size == 2 ? f : [fname, fval]
+      end
+
+      def separator
+        @params[:separator]
+      end
+
+      def sort_feature?
+        @params[:sort]
+      end
+    end
+  end
+end

data/lib/rumale/feature_extraction/tfidf_transformer.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require 'rumale/base/estimator'
+require 'rumale/base/transformer'
+require 'rumale/utils'
+
+module Rumale
+  module FeatureExtraction
+    # Transform sample matrix with term frequecy (tf) to a normalized tf-idf (inverse document frequency) reprensentation.
+    #
+    # @example
+    #   require 'rumale/feature_extraction/hash_vectorizer'
+    #   require 'rumale/feature_extraction/tfidf_transformer'
+    #
+    #   encoder = Rumale::FeatureExtraction::HashVectorizer.new
+    #   x = encoder.fit_transform([
+    #     { foo: 1, bar: 2 },
+    #     { foo: 3, baz: 1 }
+    #   ])
+    #
+    #   # > pp x
+    #   # Numo::DFloat#shape=[2,3]
+    #   # [[2, 0, 1],
+    #   #  [0, 1, 3]]
+    #
+    #   transformer = Rumale::FeatureExtraction::TfidfTransformer.new
+    #   x_tfidf = transformer.fit_transform(x)
+    #
+    #   # > pp x_tfidf
+    #   # Numo::DFloat#shape=[2,3]
+    #   # [[0.959056, 0, 0.283217],
+    #   #  [0, 0.491506, 0.870874]]
+    #
+    # *Reference*
+    # - Manning, C D., Raghavan, P., and Schutze, H., "Introduction to Information Retrieval," Cambridge University Press., 2008.
+    class TfidfTransformer < ::Rumale::Base::Estimator
+      include ::Rumale::Base::Transformer
+
+      # Return the vector consists of inverse document frequency.
+      # @return [Numo::DFloat] (shape: [n_features])
+      attr_reader :idf
+
+      # Create a new transfomer for converting tf vectors to tf-idf vectors.
+      #
+      # @param norm [String] The normalization method to be used ('l1', 'l2' and 'none').
+      # @param use_idf [Boolean] The flag indicating whether to use inverse document frequency weighting.
+      # @param smooth_idf [Boolean] The flag indicating whether to apply idf smoothing by log((n_samples + 1) / (df + 1)) + 1.
+      # @param sublinear_tf [Boolean] The flag indicating whether to perform subliner tf scaling by 1 + log(tf).
+      def initialize(norm: 'l2', use_idf: true, smooth_idf: false, sublinear_tf: false)
+        super()
+        @params = {
+          norm: norm,
+          use_idf: use_idf,
+          smooth_idf: smooth_idf,
+          sublinear_tf: sublinear_tf
+        }
+      end
+
+      # Calculate the inverse document frequency for weighting.
+      #
+      # @overload fit(x) -> TfidfTransformer
+      #
+      # @param x [Numo::DFloat] (shape: [n_samples, n_features]) The samples to calculate the idf values.
+      # @return [TfidfTransformer]
+      def fit(x, _y = nil)
+        return self unless @params[:use_idf]
+
+        n_samples = x.shape[0]
+        df = x.class.cast(x.gt(0.0).count(0))
+
+        if @params[:smooth_idf]
+          df += 1
+          n_samples += 1
+        end
+
+        @idf = Numo::NMath.log(n_samples / df) + 1
+
+        self
+      end
+
+      # Calculate the idf values, and then transfrom samples to the tf-idf representation.
+      #
+      # @overload fit_transform(x) -> Numo::DFloat
+      #
+      # @param x [Numo::DFloat] (shape: [n_samples, n_features]) The samples to calculate idf and be transformed to tf-idf representation.
+      # @return [Numo::DFloat] The transformed samples.
+      def fit_transform(x, _y = nil)
+        fit(x).transform(x)
+      end
+
+      # Perform transforming the given samples to the tf-idf representation.
+      #
+      # @param x [Numo::DFloat] (shape: [n_samples, n_features]) The samples to be transformed.
+      # @return [Numo::DFloat] The transformed samples.
+      def transform(x)
+        z = x.dup
+
+        z[z.ne(0)] = Numo::NMath.log(z[z.ne(0)]) + 1 if @params[:sublinear_tf]
+        z *= @idf if @params[:use_idf]
+        case @params[:norm]
+        when 'l2'
+          ::Rumale::Utils.normalize(z, 'l2')
+        when 'l1'
+          ::Rumale::Utils.normalize(z, 'l1')
+        else
+          z
+        end
+      end
+    end
+  end
+end

data/lib/rumale/feature_extraction/version.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+# Rumale is a machine learning library in Ruby.
+module Rumale
+  # This module consists of the classes that extract features from raw data.
+  module FeatureExtraction
+    # @!visibility private
+    VERSION = '0.24.0'
+  end
+end

data/lib/rumale/feature_extraction.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'numo/narray'
+
+require_relative 'feature_extraction/feature_hasher'
+require_relative 'feature_extraction/hash_vectorizer'
+require_relative 'feature_extraction/tfidf_transformer'
+require_relative 'feature_extraction/version'

metadata

@@ -0,0 +1,101 @@
+--- !ruby/object:Gem::Specification
+name: rumale-feature_extraction
+version: !ruby/object:Gem::Version
+  version: 0.24.0
+platform: ruby
+authors:
+- yoshoku
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2022-12-31 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: mmh3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: numo-narray
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.9.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.9.1
+- !ruby/object:Gem::Dependency
+  name: rumale-core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.24.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.24.0
+description: |
+  Rumale::FeatureExtraction provides feature extraction methods,
+  such as TF-IDF and feature hashing,
+  with Rumale interface.
+email:
+- yoshoku@outlook.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/rumale/feature_extraction.rb
+- lib/rumale/feature_extraction/feature_hasher.rb
+- lib/rumale/feature_extraction/hash_vectorizer.rb
+- lib/rumale/feature_extraction/tfidf_transformer.rb
+- lib/rumale/feature_extraction/version.rb
+homepage: https://github.com/yoshoku/rumale
+licenses:
+- BSD-3-Clause
+metadata:
+  homepage_uri: https://github.com/yoshoku/rumale
+  source_code_uri: https://github.com/yoshoku/rumale/tree/main/rumale-feature_extraction
+  changelog_uri: https://github.com/yoshoku/rumale/blob/main/CHANGELOG.md
+  documentation_uri: https://yoshoku.github.io/rumale/doc/
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.26
+signing_key:
+specification_version: 4
+summary: Rumale::FeatureExtraction provides feature extraction methods with Rumale
+  interface.
+test_files: []