ai4r 1.13 → 2.0

data/lib/ai4r/som/som.rb

@@ -1,19 +1,21 @@
+# frozen_string_literal: true
+
 # Author::    Thomas Kern
 # 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
 # Mozilla Foundation at http://www.mozilla.org/MPL/MPL-1.1.txt
 
-require File.dirname(__FILE__) + '/../data/parameterizable'
-require File.dirname(__FILE__) + '/layer'
-require File.dirname(__FILE__) + '/two_phase_layer'
-require File.dirname(__FILE__) + '/node'
+require_relative '../data/parameterizable'
+require 'yaml'
+require_relative 'layer'
+require_relative 'two_phase_layer'
+require_relative 'node'
 
 module Ai4r
-
   # A self-organizing map (SOM) or self-organizing feature map (SOFM) is a type
   # of artificial neural network that is trained using unsupervised learning to
   # produce a low-dimensional (typically two-dimensional), discretized
@@ -24,7 +26,6 @@ module Ai4r
   # 'Neural Networks for Applied Sciences and Engineering'
 
   module Som
-
     # = Introduction
     #
     # This is an implementation of a Kohonen Self-Organizing Maps
@@ -41,39 +42,49 @@ module Ai4r
     #
     # = Parameters
     # * dim => dimension of the input vector
-    # * number_of_nodes => is the number of nodes per row/column (square som).
+    # * rows => number of rows for the map
+    # * columns => number of columns for the map
     # * layer => instante of a layer-algorithm class
     #
     # = About the project
     # Author::    Thomas Kern
     # License::   MPL 1.1
-    # Url::       http://ai4r.org
+    # Url::       https://github.com/SergioFierens/ai4r
 
+    # Encapsulates a self-organizing map composed of interconnected nodes.
     class Som
-
       include Ai4r::Data::Parameterizable
 
-      parameters_info :nodes  => "sets the architecture of the map (nodes x nodes)",
-                      :dimension => "sets the dimension of the input",
-                      :layer => "instance of a layer, defines how the training algorithm works",
-                      :epoch => "number of finished epochs"
+      parameters_info rows: 'number of rows for the map',
+                      columns: 'number of columns for the map',
+                      nodes: 'array holding all nodes of the map',
+                      dimension: 'sets the dimension of the input',
+                      layer: 'instance of a layer, defines how the training algorithm works',
+                      epoch: 'number of finished epochs',
+                      init_weight_options: 'Hash with :range and :seed to initialize node weights'
 
-      def initialize(dim, number_of_nodes, layer)
+      def initialize(dim, rows, columns, layer, init_weight_options = { range: 0..1, seed: nil })
         @layer = layer
         @dimension = dim
-        @number_of_nodes = number_of_nodes
-        @nodes = Array.new(number_of_nodes * number_of_nodes)
+        @rows = rows
+        @columns = columns
+        @nodes = Array.new(rows * columns)
         @epoch = 0
         @cache = {}
+        opts = { range: 0..1, random_seed: nil, seed: nil }.merge(init_weight_options)
+        opts[:random_seed] = opts[:random_seed] || opts[:seed]
+        @init_weight_options = opts
       end
 
       # finds the best matching unit (bmu) of a certain input in all the @nodes
       # returns an array of length 2 => [node, distance] (distance is of eucledian type, not
       # a neighborhood distance)
+      # @param input [Object]
+      # @return [Object]
       def find_bmu(input)
         bmu = @nodes.first
         dist = bmu.distance_to_input input
-        @nodes[1..-1].each do |node|
+        @nodes[1..].each do |node|
           tmp_dist = node.distance_to_input(input)
           if tmp_dist <= dist
             dist = tmp_dist
@@ -84,6 +95,11 @@ module Ai4r
       end
 
       # adjusts all nodes within a certain radius to the bmu
+      # @param input [Object]
+      # @param bmu [Object]
+      # @param radius [Object]
+      # @param learning_rate [Object]
+      # @return [Object]
       def adjust_nodes(input, bmu, radius, learning_rate)
         @nodes.each do |node|
           dist = node.distance_to_node(bmu[0])
@@ -91,30 +107,43 @@ module Ai4r
 
           influence = @layer.influence_decay dist, radius
           node.weights.each_with_index do |weight, index|
-            node.weights[index] +=  influence * learning_rate * (input[index] - weight)
+            node.weights[index] += influence * learning_rate * (input[index] - weight)
           end
         end
       end
 
       # main method for the som. trains the map with the passed data vector
       # calls train_step as long as train_step returns false
-      def train(data)
-        while !train_step(data)
+      # @param data [Object]
+      # @param error_threshold [Object]
+      # @return [Object]
+      def train(data, error_threshold: nil)
+        errors = []
+        while @epoch < @layer.epochs
+          error = train_step(data, error_threshold: error_threshold)
+          errors << error
+          yield error if block_given?
         end
+        errors
       end
 
       # calculates the global distance error for all data entries
+      # @param data [Object]
+      # @return [Object]
       def global_error(data)
-        data.inject(0) {|sum,entry| sum + find_bmu(entry)[1]**2 }
-       end
+        data.inject(0) { |sum, entry| sum + (find_bmu(entry)[1]**2) }
+      end
 
-      # trains the map with the data as long as the @epoch is smaller than the epoch-value of
-      # @layer
-      # returns true if @epoch is greater than the fixed epoch-value in @layer, otherwise false
-      # 1 is added to @epoch at each method call
-      # the radius and learning rate is decreased at each method call/epoch as well
-      def train_step(data)
-        return true if @epoch >= @layer.epochs
+      # Train the map for one epoch using +data+.
+      # Returns the computed +global_error+ for that epoch. If a block is
+      # provided, the error is yielded instead of returned.
+      # Training stops early when +error_threshold+ is defined and the computed
+      # error falls below it.
+      # @param data [Object]
+      # @param error_threshold [Object]
+      # @return [Object]
+      def train_step(data, error_threshold: nil)
+        return nil if @epoch >= @layer.epochs
 
         radius = @layer.radius_decay @epoch
         learning_rate = @layer.learning_rate_decay @epoch
@@ -124,32 +153,120 @@ module Ai4r
         end
 
         @epoch += 1
-        false
+        error = global_error(data)
+        @epoch = @layer.epochs if error_threshold && error <= error_threshold
+        yield error if block_given?
+        error
       end
 
-      # returns the node at position (x,y) in the square map
+      # returns the node at position (x,y) in the map
+      # @param x [Object]
+      # @param y [Object]
+      # @return [Object]
       def get_node(x, y)
-        raise(Exception.new) if check_param_for_som(x,y)
-        @nodes[y + x * @number_of_nodes]
+        raise ArgumentError, "invalid node coordinates (#{x}, #{y})" if check_param_for_som(x, y)
+
+        @nodes[y + (x * @columns)]
       end
 
-      # intitiates the map by creating (@number_of_nodes * @number_of_nodes) nodes
+      # intitiates the map by creating (@rows * @columns) nodes
+      # @return [Object]
       def initiate_map
-        @nodes.each_with_index do |node, i|
-          @nodes[i] = Node.create i, @number_of_nodes, @dimension
+        seed = @init_weight_options[:random_seed]
+        rng = seed.nil? ? Random.new : Random.new(seed)
+        @nodes.each_index do |i|
+          options = @init_weight_options.merge(distance_metric: @layer.distance_metric, rng: rng)
+          @nodes[i] = Node.create i, @rows, @columns, @dimension, options
         end
       end
 
+      # Serialize this SOM to a Ruby Hash.  The resulting structure includes
+      # map dimensions, layer parameters and all node weights.
+      # @return [Object]
+      def to_h
+        {
+          'rows' => @rows,
+          'columns' => @columns,
+          'dimension' => @dimension,
+          'epoch' => @epoch,
+          'layer' => {
+            'class' => @layer.class.name,
+            'parameters' => @layer.get_parameters,
+            'initial_learning_rate' => @layer.instance_variable_get('@initial_learning_rate')
+          },
+          'nodes' => @nodes.map(&:weights)
+        }
+      end
+
+      # Build a new SOM instance from the Hash generated by +to_h+.
+      # @param hash [Object]
+      # @return [Object]
+      def self.from_h(hash)
+        layer_class = Object.const_get(hash['layer']['class'])
+        raw_params = hash['layer']['parameters'] || {}
+        params = {}
+        raw_params.each do |k, v|
+          params[k.to_s] = v
+        end
+        ilr = hash['layer']['initial_learning_rate']
+
+        layer = if layer_class == TwoPhaseLayer
+                  layer_class.new(
+                    params['nodes'],
+                    ilr || 0.9,
+                    params['epochs'],
+                    0,
+                    0.1,
+                    0
+                  )
+                else
+                  layer_class.new(
+                    params['nodes'],
+                    params['radius'],
+                    params['epochs'],
+                    ilr || 0.7
+                  )
+                end
+        layer.set_parameters(params) if layer.respond_to?(:set_parameters)
+
+        som = Som.new(hash['dimension'], hash['rows'], hash['columns'], layer)
+        som.epoch = hash['epoch']
+        som.nodes = hash['nodes'].each_with_index.map do |weights, i|
+          node = Node.new
+          node.id = i
+          node.x = i % hash['columns']
+          node.y = (i / hash['columns'].to_f).to_i
+          node.weights = weights.dup
+          node.instantiated_weight = weights.dup
+          node
+        end
+        som
+      end
+
+      # Save this SOM to a YAML file.
+      # @param path [Object]
+      # @return [Object]
+      def save_yaml(path)
+        File.write(path, YAML.dump(to_h))
+      end
+
+      # Load a SOM from a YAML file created by +save_yaml+.
+      # @param path [Object]
+      # @return [Object]
+      def self.load_yaml(path)
+        from_h(YAML.load_file(path))
+      end
+
       private
 
       # checks whether or not there is a node in the map at the coordinates (x,y).
       # x is the row, y the column indicator
+      # @param x [Object]
+      # @param y [Object]
+      # @return [Object]
       def check_param_for_som(x, y)
-        y > @number_of_nodes - 1 || x > @number_of_nodes - 1  || x < 0 || y < 0
+        y > @columns - 1 || x > @rows - 1 || x.negative? || y.negative?
       end
-
     end
-
   end
-
 end

data/lib/ai4r/som/two_phase_layer.rb

@@ -1,19 +1,19 @@
+# frozen_string_literal: true
+
 # Author::    Thomas Kern
 # 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
 # Mozilla Foundation at http://www.mozilla.org/MPL/MPL-1.1.txt
 
-require File.dirname(__FILE__) + '/../data/parameterizable'
-require File.dirname(__FILE__) + '/layer'
+require_relative '../data/parameterizable'
+require_relative 'layer'
 
 module Ai4r
-
   module Som
-
     # responsible for the implementation of the algorithm's decays, extends the class Layer.
     # currently overrides the radius and learning rate decay methods of Layer.
     # Has two phases, phase one has a decay in both the learning rate and the radius. The number
@@ -31,11 +31,12 @@ module Ai4r
     # * phase_one_learning_rate  => sets the learning rate for phase one
     # * phase_two_learning_rate  => sets the learning rate for phase two
 
+    # Layer that trains in two distinct phases with different learning rates.
     class TwoPhaseLayer < Layer
-
+      # @return [Object]
       def initialize(nodes, learning_rate = 0.9, phase_one = 150, phase_two = 100,
-              phase_one_learning_rate = 0.1, phase_two_learning_rate = 0)
-        super nodes, nodes, phase_one + phase_two, learning_rate
+                     phase_one_learning_rate = 0.1, phase_two_learning_rate = 0, options = {})
+        super(nodes, nodes, phase_one + phase_two, learning_rate, options)
         @phase_one = phase_one
         @phase_two = phase_two
         @lr = @initial_learning_rate
@@ -43,24 +44,21 @@ module Ai4r
         @phase_one_learning_rate = phase_one_learning_rate
         @phase_two_learning_rate = phase_two_learning_rate
 
-        @radius_reduction = @phase_one / (nodes/2.0 - 1) + 1
-        @delta_lr = (@lr - @phase_one_learning_rate)/ @phase_one
+        @radius_reduction = (@phase_one / ((nodes / 2.0) - 1)) + 1
+        @delta_lr = (@lr - @phase_one_learning_rate) / @phase_one
         @radius = (nodes / 2.0).to_i
       end
 
       # two different values will be returned, depending on the phase
       # in phase one, the radius will incrementially reduced by 1 every @radius_reduction time
       # in phase two, the radius is fixed to 1
+      # @param epoch [Object]
+      # @return [Object]
       def radius_decay(epoch)
-        if epoch > @phase_one
-          return 1
-        else
-          if (epoch % @radius_reduction) == 0
-            @radius -= 1
-          end
-          @radius
-        end
+        return 1 if epoch > @phase_one
 
+        @radius -= 1 if (epoch % @radius_reduction).zero?
+        @radius
       end
 
       # two different values will be returned, depending on the phase
@@ -69,22 +67,20 @@ module Ai4r
       # the decay value of the learning rate) is reset as well
       # in  phase two, the newly reset delta_lr rate will be used to incrementially reduce the
       # learning rate
+      # @param epoch [Object]
+      # @return [Object]
       def learning_rate_decay(epoch)
         if epoch < @phase_one
           @lr -= @delta_lr
-          return @lr
+          @lr
         elsif epoch == @phase_one
           @lr = @phase_one_learning_rate
-          @delta_lr = (@phase_one_learning_rate - @phase_two_learning_rate)/@phase_two
-          return @lr
+          @delta_lr = (@phase_one_learning_rate - @phase_two_learning_rate) / @phase_two
+          @lr
         else
           @lr -= @delta_lr
         end
       end
-
     end
-
   end
-
 end
-

data/lib/ai4r/version.rb

@@ -0,0 +1,3 @@
+module Ai4r
+  VERSION = '2.0'.freeze
+end

data/lib/ai4r.rb

@@ -1,35 +1,64 @@
+# frozen_string_literal: true
+
+require_relative 'ai4r/version'
+
 # Data
-require File.dirname(__FILE__) +  "/ai4r/data/data_set"
-require File.dirname(__FILE__) +  "/ai4r/data/statistics"
-require File.dirname(__FILE__) +  "/ai4r/data/proximity"
-require File.dirname(__FILE__) +  "/ai4r/data/parameterizable"
+require_relative 'ai4r/data/data_set'
+require_relative 'ai4r/data/statistics'
+require_relative 'ai4r/data/proximity'
+require_relative 'ai4r/data/parameterizable'
+
 # Clusterers
-require File.dirname(__FILE__) +  "/ai4r/clusterers/clusterer"
-require File.dirname(__FILE__) +  "/ai4r/clusterers/k_means"
-require File.dirname(__FILE__) +  "/ai4r/clusterers/bisecting_k_means"
-require File.dirname(__FILE__) +  "/ai4r/clusterers/single_linkage"
-require File.dirname(__FILE__) +  "/ai4r/clusterers/complete_linkage"
-require File.dirname(__FILE__) +  "/ai4r/clusterers/average_linkage"
-require File.dirname(__FILE__) +  "/ai4r/clusterers/weighted_average_linkage"
-require File.dirname(__FILE__) +  "/ai4r/clusterers/centroid_linkage"
-require File.dirname(__FILE__) +  "/ai4r/clusterers/median_linkage"
-require File.dirname(__FILE__) +  "/ai4r/clusterers/ward_linkage"
-require File.dirname(__FILE__) +  "/ai4r/clusterers/ward_linkage_hierarchical"
-require File.dirname(__FILE__) +  "/ai4r/clusterers/diana"
+require_relative 'ai4r/clusterers/clusterer'
+require_relative 'ai4r/clusterers/k_means'
+require_relative 'ai4r/clusterers/bisecting_k_means'
+require_relative 'ai4r/clusterers/single_linkage'
+require_relative 'ai4r/clusterers/complete_linkage'
+require_relative 'ai4r/clusterers/average_linkage'
+require_relative 'ai4r/clusterers/weighted_average_linkage'
+require_relative 'ai4r/clusterers/centroid_linkage'
+require_relative 'ai4r/clusterers/median_linkage'
+require_relative 'ai4r/clusterers/ward_linkage'
+require_relative 'ai4r/clusterers/ward_linkage_hierarchical'
+require_relative 'ai4r/clusterers/diana'
+require_relative 'ai4r/clusterers/dbscan'
+
 # Classifiers
-require File.dirname(__FILE__) +  "/ai4r/classifiers/classifier"
-require File.dirname(__FILE__) +  "/ai4r/classifiers/id3"
-require File.dirname(__FILE__) +  "/ai4r/classifiers/prism"
-require File.dirname(__FILE__) +  "/ai4r/classifiers/one_r"
-require File.dirname(__FILE__) +  "/ai4r/classifiers/zero_r"
-require File.dirname(__FILE__) +  "/ai4r/classifiers/hyperpipes"
-require File.dirname(__FILE__) +  "/ai4r/classifiers/naive_bayes"
-require File.dirname(__FILE__) +  "/ai4r/classifiers/ib1"
+require_relative 'ai4r/classifiers/classifier'
+require_relative 'ai4r/classifiers/id3'
+require_relative 'ai4r/classifiers/multilayer_perceptron'
+require_relative 'ai4r/classifiers/prism'
+require_relative 'ai4r/classifiers/one_r'
+require_relative 'ai4r/classifiers/zero_r'
+require_relative 'ai4r/classifiers/hyperpipes'
+require_relative 'ai4r/classifiers/naive_bayes'
+require_relative 'ai4r/classifiers/ib1'
+require_relative 'ai4r/classifiers/random_forest'
+require_relative 'ai4r/classifiers/gradient_boosting'
+require_relative 'ai4r/classifiers/support_vector_machine'
+
 # Neural networks
-require File.dirname(__FILE__) +  "/ai4r/neural_network/backpropagation"
-require File.dirname(__FILE__) +  "/ai4r/neural_network/hopfield"
+require_relative 'ai4r/neural_network/backpropagation'
+require_relative 'ai4r/neural_network/hopfield'
+require_relative 'ai4r/neural_network/transformer'
+
 # Genetic Algorithms
-require File.dirname(__FILE__) +  "/ai4r/genetic_algorithm/genetic_algorithm"
+require_relative 'ai4r/genetic_algorithm/genetic_algorithm'
+
+# Reinforcement Learning
+require_relative 'ai4r/reinforcement/q_learning'
+require_relative 'ai4r/reinforcement/policy_iteration'
+
+# Search
+require_relative 'ai4r/search/bfs'
+require_relative 'ai4r/search/dfs'
+require_relative 'ai4r/search/mcts'
+require_relative 'ai4r/search'
+
+# Hidden Markov Models
+require_relative 'ai4r/hmm/hidden_markov_model'
+
 # SOM
-require File.dirname(__FILE__) +  "/ai4r/som/som"
+require_relative 'ai4r/som/som'
 
+# Search Algorithms