ai4r 1.13 → 2.0

data/examples/transformer/decode_classifier_example.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require_relative '../../lib/ai4r/neural_network/transformer'
+require_relative '../../lib/ai4r/classifiers/logistic_regression'
+require_relative '../../lib/ai4r/data/data_set'
+
+# Tiny dataset of greetings (label 0) and farewells (label 1)
+sentences = [
+  %w[hello there],
+  %w[how are you],
+  %w[good morning],
+  %w[nice to meet you],
+  %w[goodbye],
+  %w[see you later],
+  %w[have a nice day],
+  %w[take care]
+]
+labels = [0, 0, 0, 0, 1, 1, 1, 1]
+
+# Build vocabulary
+vocab = {}
+next_id = 0
+sentences.each do |tokens|
+  tokens.each do |t|
+    unless vocab.key?(t)
+      vocab[t] = next_id
+      next_id += 1
+    end
+  end
+end
+
+vocab_size = vocab.length
+max_len = sentences.map(&:length).max
+
+transformer = Ai4r::NeuralNetwork::Transformer.new(
+  vocab_size: vocab_size,
+  max_len: max_len,
+  architecture: :decoder
+)
+embed_dim = transformer.embed_dim
+
+# Encode each sentence and average embeddings
+items = []
+sentences.each_with_index do |tokens, idx|
+  ids = tokens.map { |t| vocab[t] }
+  vecs = transformer.eval(ids)
+  avg = Array.new(embed_dim, 0.0)
+  vecs.each do |v|
+    v.each_index { |i| avg[i] += v[i] }
+  end
+  avg.map! { |v| v / vecs.length }
+  items << (avg + [labels[idx]])
+end
+
+labels_names = (0...embed_dim).map { |i| "x#{i}" } + ['class']
+set = Ai4r::Data::DataSet.new(data_items: items, data_labels: labels_names)
+
+classifier = Ai4r::Classifiers::LogisticRegression.new
+classifier.set_parameters(lr: 0.5, iterations: 500).build(set)
+
+# Classify a short greeting
+sample = %w[hello]
+ids = sample.map { |t| vocab[t] }
+vecs = transformer.eval(ids)
+avg = Array.new(embed_dim, 0.0)
+vecs.each { |v| v.each_index { |i| avg[i] += v[i] } }
+avg.map! { |v| v / vecs.length }
+puts "Prediction: #{classifier.eval(avg)} (0=greeting, 1=farewell)"

data/examples/transformer/deterministic_example.rb

@@ -0,0 +1,10 @@
+require_relative '../../lib/ai4r/neural_network/transformer'
+
+# Demonstrates deterministic initialization using the :seed parameter.
+model_a = Ai4r::NeuralNetwork::Transformer.new(vocab_size: 5, max_len: 3, seed: 42)
+model_b = Ai4r::NeuralNetwork::Transformer.new(vocab_size: 5, max_len: 3, seed: 42)
+
+output_a = model_a.eval([0, 1, 2])
+output_b = model_b.eval([0, 1, 2])
+
+puts "Outputs identical? #{output_a == output_b}"

data/examples/transformer/seq2seq_example.rb

@@ -0,0 +1,16 @@
+require_relative '../../lib/ai4r/neural_network/transformer'
+
+# Simple demo of the seq2seq architecture.
+# The model returns random vectors but shows how
+# to provide encoder and decoder inputs.
+model = Ai4r::NeuralNetwork::Transformer.new(
+  vocab_size: 10,
+  max_len: 5,
+  architecture: :seq2seq
+)
+
+encoder_input = [1, 2, 3]
+decoder_input = [4, 5]
+
+output = model.eval(encoder_input, decoder_input)
+puts "Output length: #{output.length}"

data/lib/ai4r/classifiers/classifier.rb

@@ -1,62 +1,70 @@
+# frozen_string_literal: true
+
 # Author::    Sergio Fierens
 # License::   MPL 1.1
 # Project::   ai4r
-# Url::       http://ai4r.org
+# Url::       https://github.com/SergioFierens/ai4r
 #
-# You can redistribute it and/or modify it under the terms of 
-# the Mozilla Public License version 1.1  as published by the 
+# You can redistribute it and/or modify it under the terms of
+# the Mozilla Public License version 1.1  as published by the
 # Mozilla Foundation at http://www.mozilla.org/MPL/MPL-1.1.txt
- 
-require File.dirname(__FILE__) + '/../data/parameterizable' 
- 
+
+require_relative '../data/parameterizable'
+
 module Ai4r
   module Classifiers
-  
     # This class defines a common API for classifiers.
     # All methods in this class must be implemented in subclasses.
     class Classifier
+      include Ai4r::Data::Parameterizable
 
-      include Ai4r::Data::Parameterizable  
-    
       # Build a new classifier, using data examples found in data_set.
       # The last attribute of each item is considered as the
       # item class.
+      # @param data_set [Object]
+      # @return [Object]
       def build(data_set)
         raise NotImplementedError
       end
-      
+
       # You can evaluate new data, predicting its class.
       # e.g.
       #   classifier.eval(['New York',  '<30', 'F'])  # => 'Y'
+      # @param data [Object]
+      # @return [Object]
       def eval(data)
         raise NotImplementedError
       end
-      
+
       # This method returns the generated rules in ruby code.
       # e.g.
-      #   
+      #
       #   classifier.get_rules
       #     # =>  if age_range=='<30' then marketing_target='Y'
       #           elsif age_range=='[30-50)' and city=='Chicago' then marketing_target='Y'
       #           elsif age_range=='[30-50)' and city=='New York' then marketing_target='N'
       #           elsif age_range=='[50-80]' then marketing_target='N'
       #           elsif age_range=='>80' then marketing_target='Y'
-      #           else raise 'There was not enough information during training to do a proper induction for this data element' end
+      #           else
+      #             raise 'There was not enough information during training to do a '
+      #                   'proper induction for this data element'
+      #           end
       #
-      # It is a nice way to inspect induction results, and also to execute them:  
+      # It is a nice way to inspect induction results, and also to execute them:
       #     age_range = '<30'
       #     city='New York'
       #     marketing_target = nil
-      #     eval classifier.get_rules   
+      #     eval classifier.get_rules
       #     puts marketing_target
       #       # =>  'Y'
       #
       # Note, however, that not all classifiers are able to produce rules.
       # This method is not implemented in such classifiers.
+      # @return [Object]
       def get_rules
         raise NotImplementedError
       end
-      
+      # rubocop:enable Naming/AccessorMethodName
     end
   end
 end

data/lib/ai4r/classifiers/gradient_boosting.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+# Author::    OpenAI ChatGPT
+# License::   MPL 1.1
+# Project::   ai4r
+#
+# Very small gradient boosting implementation for regression using
+# simple linear regression as base learner.
+
+require_relative 'simple_linear_regression'
+require_relative '../data/data_set'
+require_relative '../classifiers/classifier'
+
+module Ai4r
+  module Classifiers
+    # Gradient boosting regressor using simple linear regression base learners.
+    class GradientBoosting < Classifier
+      parameters_info n_estimators: 'Number of boosting iterations. Default 10.',
+                      learning_rate: 'Shrinkage parameter for each learner. Default 0.1.'
+
+      attr_reader :initial_value, :learners
+
+      def initialize
+        super()
+        @n_estimators = 10
+        @learning_rate = 0.1
+      end
+
+      def build(data_set)
+        data_set.check_not_empty
+        @learners = []
+        targets = data_set.data_items.map(&:last)
+        @initial_value = targets.sum.to_f / targets.length
+        predictions = Array.new(targets.length, @initial_value)
+        @n_estimators.times do
+          residuals = targets.zip(predictions).map { |y, f| y - f }
+          items = data_set.data_items.each_with_index.map do |item, idx|
+            item[0...-1] + [residuals[idx]]
+          end
+          ds = Ai4r::Data::DataSet.new(data_items: items, data_labels: data_set.data_labels)
+          learner = SimpleLinearRegression.new.build(ds)
+          @learners << learner
+          pred = items.map { |it| learner.eval(it[0...-1]) }
+          predictions = predictions.zip(pred).map { |f, p| f + (@learning_rate * p) }
+        end
+        self
+      end
+      # rubocop:enable Metrics/AbcSize
+
+      def eval(data)
+        value = @initial_value
+        @learners.each do |learner|
+          value += @learning_rate * learner.eval(data)
+        end
+        value
+      end
+
+      def get_rules
+        'GradientBoosting does not support rule extraction.'
+      end
+      # rubocop:enable Naming/AccessorMethodName
+    end
+  end
+end

data/lib/ai4r/classifiers/hyperpipes.rb

@@ -1,118 +1,194 @@
+# frozen_string_literal: true
+
 # Author::    Sergio Fierens (Implementation only)
 # License::   MPL 1.1
 # Project::   ai4r
-# Url::       http://www.ai4r.org/
+# Url::       https://github.com/SergioFierens/ai4r
 #
-# You can redistribute it and/or modify it under the terms of 
-# the Mozilla Public License version 1.1  as published by the 
+# You can redistribute it and/or modify it under the terms of
+# the Mozilla Public License version 1.1  as published by the
 # Mozilla Foundation at http://www.mozilla.org/MPL/MPL-1.1.txt
 
 require 'set'
-require File.dirname(__FILE__) + '/../data/data_set'
-require File.dirname(__FILE__) + '/../classifiers/classifier'
+require_relative '../data/data_set'
+require_relative '../classifiers/classifier'
+require_relative '../classifiers/votes'
 
 module Ai4r
+  # Collection of classifier algorithms.
   module Classifiers
-
     include Ai4r::Data
-    
+
     # = Introduction
-    # 
-    # A fast classifier algorithm, created by Lucio de Souza Coelho 
+    #
+    # A fast classifier algorithm, created by Lucio de Souza Coelho
     # and Len Trigg.
     class Hyperpipes < Classifier
-      
       attr_reader :data_set, :pipes
 
+      parameters_info tie_break:
+                        'Strategy used when more than one class has the same maximal vote. ' \
+                        'Valid values are :last (default) and :random.',
+                      margin: 'Numeric margin added to the bounds of numeric attributes.',
+                      random_seed: 'Seed for random tie-breaking when tie_break is :random.'
+
+      # @return [Object]
+      def initialize
+        super()
+        @tie_break = :last
+        @margin = 0
+        @random_seed = nil
+        @rng = nil
+      end
+
       # Build a new Hyperpipes classifier. You must provide a DataSet instance
-      # as parameter. The last attribute of each item is considered as 
+      # as parameter. The last attribute of each item is considered as
       # the item class.
+      # @param data_set [Object]
+      # @return [Object]
       def build(data_set)
         data_set.check_not_empty
         @data_set = data_set
         @domains = data_set.build_domains
-        
+
         @pipes = {}
-        @domains.last.each {|cat| @pipes[cat] = build_pipe(@data_set)}
-        @data_set.data_items.each {|item| update_pipe(@pipes[item.last], item) }
-        
-        return self
+        @domains.last.each { |cat| @pipes[cat] = build_pipe(@data_set) }
+        @data_set.data_items.each { |item| update_pipe(@pipes[item.last], item) }
+
+        self
       end
-      
+
       # You can evaluate new data, predicting its class.
       # e.g.
-      #   classifier.eval(['New York',  '<30', 'F'])  # => 'Y'      
+      #   classifier.eval(['New York',  '<30', 'F'])  # => 'Y'
+      # Tie resolution is controlled by +tie_break+ parameter.
+      # @param data [Object]
+      # @return [Object]
       def eval(data)
-        votes = Hash.new {0}
+        votes = Votes.new
         @pipes.each do |category, pipe|
           pipe.each_with_index do |bounds, i|
             if data[i].is_a? Numeric
-              votes[category]+=1 if data[i]>=bounds[:min] && data[i]<=bounds[:max]
-            else
-              votes[category]+=1 if bounds[data[i]]
+              votes.increment_category(category) if data[i].between?(bounds[:min], bounds[:max])
+            elsif bounds[data[i]]
+              votes.increment_category(category)
             end
           end
         end
-        return votes.to_a.max {|x, y| x.last <=> y.last}.first
+        rng = @rng || (@random_seed.nil? ? Random.new : Random.new(@random_seed))
+        votes.get_winner(@tie_break, rng: rng)
       end
-      
+      # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+
       # This method returns the generated rules in ruby code.
       # e.g.
-      #   
+      #
       #   classifier.get_rules
       #     # =>  if age_range == '<30' then marketing_target = 'Y'
       #           elsif age_range == '[30-50)' then marketing_target = 'N'
       #           elsif age_range == '[50-80]' then marketing_target = 'N'
       #           end
       #
-      # It is a nice way to inspect induction results, and also to execute them:  
+      # It is a nice way to inspect induction results, and also to execute them:
       #     marketing_target = nil
-      #     eval classifier.get_rules   
+      #     eval classifier.get_rules
       #     puts marketing_target
       #       # =>  'Y'
+      # @return [Object]
+      # rubocop:disable Metrics/AbcSize
       def get_rules
         rules = []
-        rules << "votes = Hash.new {0}"
+        rules << 'votes = Votes.new'
         data = @data_set.data_items.first
-        labels = @data_set.data_labels.collect {|l| l.to_s}
+        labels = @data_set.data_labels.collect(&:to_s)
         @pipes.each do |category, pipe|
           pipe.each_with_index do |bounds, i|
-            rule = "votes['#{category}'] += 1 "
-            if data[i].is_a? Numeric
-              rule += "if #{labels[i]} >= #{bounds[:min]} && #{labels[i]} <= #{bounds[:max]}"
+            rule = "votes.increment_category('#{category}') "
+            rule += if data[i].is_a? Numeric
+                      "if #{labels[i]} >= #{bounds[:min]} && #{labels[i]} <= #{bounds[:max]}"
+                    else
+                      "if #{bounds.inspect}[#{labels[i]}]"
+                    end
+            rules << rule
+          end
+        end
+        rules << "#{labels.last} = votes.get_winner(:#{@tie_break})"
+        rules.join("\n")
+      end
+      # rubocop:enable Metrics/AbcSize
+      # rubocop:enable Naming/AccessorMethodName
+
+      # Return a summary representation of all pipes.
+      #
+      # The returned hash maps each category to another hash where the keys are
+      # attribute labels and the values are either numeric ranges
+      # `[min, max]` (including the optional margin) or a Set of nominal values.
+      #
+      #   classifier.pipes_summary
+      #     # => { "Y" => { "city" => #{Set['New York', 'Chicago']},
+      #                    "age" => [18, 85],
+      #                    "gender" => #{Set['M', 'F']} },
+      #          "N" => { ... } }
+      #
+      # The optional +margin+ parameter expands numeric bounds by the given
+      # fraction.  A value of 0.1 would enlarge each range by 10%.
+      # @param margin [Object]
+      # @return [Object]
+      # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+      def pipes_summary(margin: 0)
+        raise 'Model not built yet' unless @data_set && @pipes
+
+        labels = @data_set.data_labels[0...-1]
+        summary = {}
+        @pipes.each do |category, pipe|
+          attr_summary = {}
+          pipe.each_with_index do |bounds, i|
+            if bounds.is_a?(Hash) && bounds.key?(:min) && bounds.key?(:max)
+              min = bounds[:min]
+              max = bounds[:max]
+              range_margin = (max - min) * margin
+              attr_summary[labels[i]] = [min - range_margin, max + range_margin]
             else
-              rule += "if #{bounds.inspect}[#{labels[i]}]"
+              attr_summary[labels[i]] = bounds.select { |_k, v| v }.keys.to_set
             end
-            rules << rule
           end
+          summary[category] = attr_summary
         end
-        rules << "#{labels.last} = votes.to_a.max {|x, y| x.last <=> y.last}.first"
-        return rules.join("\n")
+        summary
       end
-      
+      # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+
       protected
 
+      # @param data_set [Object]
+      # @return [Object]
       def build_pipe(data_set)
         data_set.data_items.first[0...-1].collect do |att|
           if att.is_a? Numeric
-            {:min=>1.0/0, :max=>-1.0/0}
+            { min: Float::INFINITY, max: -Float::INFINITY }
           else
             Hash.new(false)
           end
         end
       end
-      
+
+      # @param pipe [Object]
+      # @param data_item [Object]
+      # @return [Object]
+      # rubocop:disable Metrics/AbcSize
       def update_pipe(pipe, data_item)
         data_item[0...-1].each_with_index do |att, i|
           if att.is_a? Numeric
-            pipe[i][:min] = att if att < pipe[i][:min]
-            pipe[i][:max] = att if att > pipe[i][:max]
+            min_val = att - @margin
+            max_val = att + @margin
+            pipe[i][:min] = min_val if min_val < pipe[i][:min]
+            pipe[i][:max] = max_val if max_val > pipe[i][:max]
           else
             pipe[i][att] = true
-          end  
+          end
         end
       end
-      
+      # rubocop:enable Metrics/AbcSize
     end
   end
 end