ai4r 1.12 → 2.0

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

data/lib/ai4r/classifiers/ib1.rb

@@ -1,21 +1,22 @@
+# frozen_string_literal: true
+
 # Author::    Sergio Fierens (Implementation only)
 # 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 'set'
-require File.dirname(__FILE__) + '/../data/data_set'
-require File.dirname(__FILE__) + '/../classifiers/classifier'
+require_relative '../data/data_set'
+require_relative '../classifiers/classifier'
 
 module Ai4r
   module Classifiers
-
     # = Introduction
-    # 
+    #
     # IB1 algorithm implementation.
     # IB1 is the simplest instance-based learning (IBL) algorithm.
     #
@@ -26,45 +27,126 @@ module Ai4r
     # it normalizes its attributes' ranges, processes instances
     # incrementally, and has a simple policy for tolerating missing values
     class IB1 < Classifier
-      
-      attr_reader :data_set
+      attr_reader :data_set, :min_values, :max_values
+
+      parameters_info k: 'Number of nearest neighbors to consider. Default is 1.',
+                      distance_function:
+                        'Optional custom distance metric taking two instances.',
+                      tie_break:
+                        'Strategy used when neighbors vote tie. ' \
+                        'Valid values are :first (default) and :random.',
+                      random_seed:
+                        'Seed for random tie-breaking when :tie_break is :random.'
+
+      # @return [Object]
+      def initialize
+        super()
+        @k = 1
+        @distance_function = nil
+        @tie_break = :first
+        @random_seed = nil
+        @rng = nil
+      end
 
       # Build a new IB1 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
         @min_values = Array.new(data_set.data_labels.length)
         @max_values = Array.new(data_set.data_labels.length)
         data_set.data_items.each { |data_item| update_min_max(data_item[0...-1]) }
-        return self
+        self
+      end
+
+      # Append a new instance to the internal dataset. The last element is
+      # considered the class label. Minimum and maximum values for numeric
+      # attributes are updated so that future distance calculations remain
+      # normalized.
+      # @param data_item [Object]
+      # @return [Object]
+      def add_instance(data_item)
+        @data_set << data_item
+        update_min_max(data_item[0...-1])
+        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'
+      #
+      # Evaluation does not update internal statistics, keeping the
+      # classifier state unchanged. Use +update_with_instance+ to
+      # incorporate new samples.
       def eval(data)
-        update_min_max(data)
-        min_distance = 1.0/0
-        klass = nil
-        @data_set.data_items.each do |train_item|
-          d = distance(data, train_item)
-          if d < min_distance
-            min_distance = d
-            klass = train_item.last
-          end
+        neighbors = @data_set.data_items.map do |train_item|
+          [distance(data, train_item), train_item.last]
+        end
+        neighbors.sort_by! { |d, _| d }
+        k_limit = [@k, @data_set.data_items.length].min
+        k_neighbors = neighbors.first(k_limit)
+
+        # Include any other neighbors tied with the last selected distance
+        last_distance = k_neighbors.last[0]
+        neighbors[k_limit..].to_a.each do |dist, klass|
+          break if dist > last_distance
+
+          k_neighbors << [dist, klass]
         end
-        return klass
+
+        counts = Hash.new(0)
+        k_neighbors.each { |(_dist, klass)| counts[klass] += 1 }
+        max_votes = counts.values.max
+        tied = counts.select { |_, v| v == max_votes }.keys
+
+        return tied.first if tied.length == 1
+
+        rng = @rng || (@random_seed.nil? ? Random.new : Random.new(@random_seed))
+
+        case @tie_break
+        when :random
+          tied.sample(random: rng)
+        else
+          k_neighbors.each { |(_dist, klass)| return klass if tied.include?(klass) }
+        end
+      end
+
+      # Returns an array with the +k+ nearest instances from the training set
+      # for the given +data+ item. The returned elements are the training data
+      # rows themselves, ordered from the closest to the furthest.
+      # @param data [Object]
+      # @param k [Object]
+      # @return [Object]
+      def neighbors_for(data, k_neighbors)
+        update_min_max(data)
+        @data_set.data_items
+                 .map { |train_item| [train_item, distance(data, train_item)] }
+                 .sort_by(&:last)
+                 .first(k_neighbors)
+                 .map(&:first)
+      end
+
+      # Update min/max values with the provided instance attributes. If
+      # +learn+ is true, also append the instance to the training set so the
+      # classifier learns incrementally.
+      def update_with_instance(data_item, learn: false)
+        update_min_max(data_item[0...-1])
+        @data_set << data_item if learn
+        self
       end
-      
+
       protected
 
       # We keep in the state the min and max value of each attribute,
       # to provide normalized distances between to values of a numeric attribute
+      # @param atts [Object]
+      # @return [Object]
       def update_min_max(atts)
         atts.each_with_index do |att, i|
-          if att && att.is_a?(Numeric)
+          if att.is_a?(Numeric)
             @min_values[i] = att if @min_values[i].nil? || @min_values[i] > att
             @max_values[i] = att if @max_values[i].nil? || @max_values[i] < att
           end
@@ -80,10 +162,15 @@ module Ai4r
       #  * 1 if both atts are missing
       #  * normalized numeric att value if other att value is missing and > 0.5
       #  * 1.0-normalized numeric att value if other att value is missing and < 0.5
-      def distance(a, b)
+      # @param a [Object]
+      # @param b [Object]
+      # @return [Object]
+      def distance(data_a, data_b)
+        return @distance_function.call(data_a, data_b) if @distance_function
+
         d = 0
-        a.each_with_index do |att_a, i|
-          att_b = b[i]
+        data_a.each_with_index do |att_a, i|
+          att_b = data_b[i]
           if att_a.nil?
             if att_b.is_a? Numeric
               diff = norm(att_b, i)
@@ -93,7 +180,7 @@ module Ai4r
             end
           elsif att_a.is_a? Numeric
             if att_b.is_a? Numeric
-              diff = norm(att_a, i) - norm(att_b, i);
+              diff = norm(att_a, i) - norm(att_b, i)
             else
               diff = norm(att_a, i)
               diff = 1.0 - diff if diff < 0.5
@@ -105,17 +192,20 @@ module Ai4r
           end
           d += diff * diff
         end
-        return d
+        d
       end
 
       # Returns normalized value att
       #
       # index is the index of the attribute in the instance.
+      # @param att [Object]
+      # @param index [Object]
+      # @return [Object]
       def norm(att, index)
         return 0 if @min_values[index].nil?
-        return 1.0*(att - @min_values[index]) / (@max_values[index] -@min_values[index]);
+
+        1.0 * (att - @min_values[index]) / (@max_values[index] - @min_values[index])
       end
-      
     end
   end
 end