machine_learning_workbench 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 07202eab431a1fcddeb2f8c9cc669a3f63fa762d
-  data.tar.gz: 64c17b81b9a8476e664a40fb64c1faec3e8fb807
+  metadata.gz: 8107a7a0b51fc50d183e08c6ef60e43bd96d4ea1
+  data.tar.gz: 82f7af0fd0938433d749696122e9ddc588f49aa0
 SHA512:
-  metadata.gz: 24acec6a1948299718e10b93a8d22e983212af0bb255deb78e3e60ab7d118316b2c6561d59c23508098fe67b14d1edb6e539ab4b1e28d5e0fd44e85618ecc43d
-  data.tar.gz: 4123e04bb2eb291fb71accfe9041cab5dd474b9a302d3e26a589dd34f96491d3cddeedbde50024bb7deca62cedbd9b5161d98b43dc2e016ab8bcf8ea03eb9316
+  metadata.gz: 07a342404b87066ab60217ad7e2bde8cbf89d23bb7d49b504a280ce1142456a70eb24b44b6f6c76b4a4f10dfddf219acd8c7f37e85e7f91548b24771752a798c
+  data.tar.gz: bc99aec41e7f9365d47068e69398462e04bcc8dd38dda090ba46e00d27a1e5485bf96a6d55f270c1ffcd6fe8d93223c52014d479634f8e0d48673ebe2eb00bb6

data/README.md

@@ -48,3 +48,14 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/[USERN
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## References
+
+Please feel free to contribute to this list (see `Contributing` above).
+
+- NES stands for Natural Evolution Strategies. Check its [Wikipedia page](https://en.wikipedia.org/wiki/Natural_evolution_strategy) for more info.
+- CMA-ES stands for Covariance Matrix Adaptation Evolution Strategy. Check its [Wikipedia page](https://en.wikipedia.org/wiki/CMA-ES) for more info.
+- UL-ELR stands for Unsupervised Learning plus Evolutionary Reinforcement Learning, from the paper _"Intrinsically Motivated Neuroevolution for Vision-Based Reinforcement Learning" (ICDL2011)_. Check [here](https://exascale.info/members/giuseppe-cuccu/) for citation reference and pdf.
+- BD-NES stands for Block Diagonal Natural Evolution Strategies, from the homonymous paper _"Block Diagonal Natural Evolution Strategies" (PPSN2012)_. Check [here](https://exascale.info/members/giuseppe-cuccu/) for citation reference and pdf.
+- **Online VQ** stands for Online Vector Quantization, from the paper _"Intrinsically Motivated Neuroevolution for Vision-Based Reinforcement Learning" (ICDL2011)_. Check [here](https://exascale.info/members/giuseppe-cuccu/) for citation reference and pdf.
+

data/examples/image_compression.rb

@@ -0,0 +1,35 @@
+require 'rmagick'
+require 'machine_learning_workbench'
+VectorQuantization = MachineLearningWorkbench::Compressor::VectorQuantization
+Img = MachineLearningWorkbench::Tools::Imaging
+Norm = MachineLearningWorkbench::Tools::Normalization
+
+ncentrs = 1
+image_files = Dir[ENV['HOME']+'/jaffe/KA.HA*.png']
+raise "Download the JAFFE dataset in your home dir" if image_files&.empty?
+# ... and convert the `.tiff` in `.png`: `mogrify -format png jaffe/*.tiff`
+centr_range = [-1, 1]
+orig_shape = [256, 256]
+img_range = [0, 2**16-1]
+
+puts "Loading images"
+images = image_files.map do |fname|
+  nmat = Img.nmat_from_png fname, flat: true, dtype: :float64
+  ret = Norm.feature_scaling nmat, from: img_range, to: centr_range
+end
+
+puts "Initializing VQ"
+vq = VectorQuantization.new ncentrs: ncentrs,
+  dims: images.first.shape, lrate: 0.3,
+  dtype: images.first.dtype, vrange: centr_range
+
+puts "Training"
+vq.train images, debug: true
+
+puts "Done!"
+begin
+  vq.centrs.map { |c| Img.display c, shape: orig_shape }
+  require 'pry'; binding.pry
+ensure
+  MachineLearningWorkbench::Tools::Execution.kill_forks
+end

data/lib/machine_learning_workbench/compressor/online_vector_quantization.rb

@@ -0,0 +1,27 @@
+module MachineLearningWorkbench::Compressor
+  # Online Vector Quantization: VQ with per-centroid decaying learning rates.
+  # Optimized for online training.
+  class OnlineVectorQuantization < VectorQuantization
+
+    attr_reader :min_lrate, :ntrains
+
+    def initialize min_lrate: 0.01, **opts
+      super **opts.merge({lrate: nil})
+      @min_lrate = min_lrate
+      @ntrains = [0]*ncentrs
+    end
+
+    # Decaying per-centroid learning rate.
+    # @param centr_idx [Integer] index of the centroid
+    # @param lower_bound [Float] minimum learning rate
+    def lrate centr_idx, lower_bound: min_lrate
+      [1/ntrains[centr_idx], lower_bound].max
+    end
+
+    # Train on one image
+    # @return [Integer] index of trained centroid
+    def train_one *args, **opts
+      super.tap { |trg_idx| ntrains[trg_idx] += 1 }
+    end
+  end
+end

data/lib/machine_learning_workbench/compressor/vector_quantization.rb

@@ -1,4 +1,6 @@
 module MachineLearningWorkbench::Compressor
+
+  # Standard Vector Quantization
   class VectorQuantization
     attr_reader :ncentrs, :centrs, :dims, :vrange, :dtype, :lrate, :rng
     Verification = MachineLearningWorkbench::Tools::Verification
@@ -7,68 +9,92 @@ module MachineLearningWorkbench::Compressor
       @rng = Random.new rseed
       @ncentrs = ncentrs
       @dtype = dtype
-      @dims = dims
+      @dims = Array(dims)
       @lrate = lrate
       @vrange = case vrange
-      when Array
-        raise ArgumentError, "vrange size not 2: #{vrange}" unless vrange.size == 2
-        vrange.map &method(:Float)
-      when Range
-        [vrange.first, vrange.last].map &method(:Float)
-      else
-        raise ArgumentError, "vrange: unrecognized type: #{vrange.class}"
+        when Array
+          raise ArgumentError, "vrange size not 2: #{vrange}" unless vrange.size == 2
+          vrange.map &method(:Float)
+        when Range then [vrange.first, vrange.last].map &method(:Float)
+        else raise ArgumentError, "vrange: unrecognized type: #{vrange.class}"
       end
       @centrs = ncentrs.times.map { new_centr }
     end
 
     # Creates a new (random) centroid
     def new_centr
-      NMatrix.new(dims, dtype: dtype) { rng.rand Range.new *vrange }
+      # TODO: this is too slow, find another way to use the rng
+      # NMatrix.new(dims, dtype: dtype) { rng.rand Range.new *vrange }
+      NMatrix.random dims, dtype: dtype
     end
 
-    # Computes similarities between image and all centroids
-    def similarities img
-      raise NotImplementedError if img.shape.size > 1
-      # centrs.map { |c| c.dot(img).first }
-      require 'parallel'
-      Parallel.map(centrs) { |c| c.dot(img).first }
+    # Computes similarities between vector and all centroids
+    def similarities vec
+      raise NotImplementedError if vec.shape.size > 1
+      centrs.map { |c| c.dot(vec).first }
+      # require 'parallel'
+      # Parallel.map(centrs) { |c| c.dot(vec).first }
     end
-    # The list of similarities also constitutes the encoding of the image
-    alias encode similarities
 
-    # Returns index and similitude of most similar centroid to image
-    def most_similar_centr img
-      simils = similarities img
+    # Encode a vector
+    def encode vec, type: :most_similar
+      simils = similarities vec
+      case type
+      when :most_similar
+        simils.index simils.max
+      when :ensemble
+        simils
+      when :ensemble_norm
+        tot = simils.reduce(:+)
+        simils.map { |s| s/tot }
+      else raise ArgumentError, "unrecognized encode type: #{type}"
+      end
+    end
+
+    # Reconstruct vector from its code (encoding)
+    def reconstruction code, type: :most_similar
+      case type
+      when :most_similar
+        centrs[code]
+      when :ensemble
+        tot = code.reduce :+
+        centrs.zip(code).map { |centr, contr| centr*contr/tot }.reduce :+
+      when :ensemble_norm
+        centrs.zip(code).map { |centr, contr| centr*contr }.reduce :+
+      else raise ArgumentError, "unrecognized reconstruction type: #{type}"
+      end
+    end
+
+    # Returns index and similitude of most similar centroid to vector
+    def most_similar_centr vec
+      simils = similarities vec
       max_simil = simils.max
       max_idx = simils.index max_simil
       [max_idx, max_simil]
     end
 
-    # Reconstruct image as its most similar centroid
-    def reconstruction img
-      centrs[most_similar_centr(img).first]
-    end
-
-    # Per-pixel errors in reconstructing image
-    def reconstr_error img
-      reconstruction(img) - img
+    # Per-pixel errors in reconstructing vector
+    def reconstr_error vec
+      reconstruction(vec) - vec
     end
 
-    # Train on one image
-    def train_one img, simils: nil
-      trg_idx, _simil = simils || most_similar_centr(img)
-      centrs[trg_idx] = centrs[trg_idx] * (1-lrate) + img * lrate
+    # Train on one vector
+    # @param vec [NMatrix]
+    # @return [Integer] index of trained centroid
+    def train_one vec, simils: nil
+      trg_idx, _simil = simils || most_similar_centr(vec)
+      centrs[trg_idx] = centrs[trg_idx] * (1-lrate) + vec * lrate
       Verification.in_range! centrs[trg_idx], vrange
-      centrs[trg_idx]
+      trg_idx
     end
 
-    # Train on image list
-    def train img_lst, debug: false
+    # Train on vector list
+    def train vec_lst, debug: false
       # Two ways here:
-      # - Batch: canonical, centrs updated with each img
+      # - Batch: canonical, centrs updated with each vec
       # - Parallel: could be parallel either on simils or on training (?)
       # Unsure on the correctness of either Parallel, let's stick with Batch
-      img_lst.each { |img| train_one img; print '.' if debug }
+      vec_lst.each { |vec| train_one vec; print '.' if debug }
     end
   end
 end

data/lib/machine_learning_workbench/optimizer/natural_evolution_strategies/base.rb

@@ -2,7 +2,7 @@
 module MachineLearningWorkbench::Optimizer::NaturalEvolutionStrategies
   # Natural Evolution Strategies base class
   class Base
-    attr_reader :ndims, :mu, :sigma, :opt_type, :obj_fn, :parallel_fit, :id, :rng, :last_fits, :best
+    attr_reader :ndims, :mu, :sigma, :opt_type, :obj_fn, :parallel_fit, :id, :rng, :last_fits, :best, :rescale_popsize, :rescale_lrate
 
     # NES object initialization
     # @param ndims [Integer] number of parameters to optimize
@@ -11,15 +11,16 @@ module MachineLearningWorkbench::Optimizer::NaturalEvolutionStrategies
     # @param rseed [Integer] allow for deterministic execution on rseed provided
     # @param mu_init [Numeric] values to initalize the distribution's mean
     # @param sigma_init [Numeric] values to initialize the distribution's covariance
-    # @param parallel_fit [boolean] whether the `obj_fn` should be passed all the individuals 
+    # @param parallel_fit [boolean] whether the `obj_fn` should be passed all the individuals
     #   together. In the canonical case the fitness function always scores a single individual;
     #   in practical cases though it is easier to delegate the scoring parallelization to the
     #   external fitness function. Turning this to `true` will make the algorithm pass _an
     #   Array_ of individuals to the fitness function, rather than a single instance.
-    def initialize ndims, obj_fn, opt_type, rseed: nil, mu_init: 0, sigma_init: 1, parallel_fit: false
+    def initialize ndims, obj_fn, opt_type, rseed: nil, mu_init: 0, sigma_init: 1, parallel_fit: false, rescale_popsize: 1, rescale_lrate: 1
       raise ArgumentError unless [:min, :max].include? opt_type
       raise ArgumentError unless obj_fn.respond_to? :call
       @ndims, @opt_type, @obj_fn, @parallel_fit = ndims, opt_type, obj_fn, parallel_fit
+      @rescale_popsize, @rescale_lrate = rescale_popsize, rescale_lrate
       @id = NMatrix.identity(ndims, dtype: :float64)
       rseed ||= Random.new_seed
       # puts "NES rseed: #{s}"  # currently disabled
@@ -40,11 +41,11 @@ module MachineLearningWorkbench::Optimizer::NaturalEvolutionStrategies
 
     # Memoized automatic magic numbers
     # NOTE: Doubling popsize and halving lrate often helps
-    def utils;   @utilities ||= cmaes_utilities   end
+    def utils;   @utilities ||= cmaes_utilities end
     # (see #utils)
-    def popsize; @popsize   ||= cmaes_popsize * 2 end
+    def popsize; @popsize   ||= cmaes_popsize * rescale_popsize end
     # (see #utils)
-    def lrate;   @lrate     ||= cmaes_lrate       end
+    def lrate;   @lrate     ||= cmaes_lrate * rescale_lrate end
 
     # Magic numbers from CMA-ES (TODO: add proper citation)
     # @return [NMatrix] scale-invariant utilities
@@ -116,4 +117,4 @@ module MachineLearningWorkbench::Optimizer::NaturalEvolutionStrategies
       end
     end
   end
-end
+end

data/lib/machine_learning_workbench/tools/normalization.rb

@@ -4,7 +4,7 @@ module MachineLearningWorkbench::Tools
       from ||= nmat.minmax
       old_min, old_max = from
       new_min, new_max = to
-      res = (nmat-old_min)*(new_max-new_min)/(old_max-old_min)+new_min
+      (nmat-old_min)*(new_max-new_min)/(old_max-old_min)+new_min
     end
 
     # @param per_column [bool] wheather to compute stats per-column or matrix-wise
@@ -16,7 +16,7 @@ module MachineLearningWorkbench::Tools
       stddevs.map! { |v| v.zero? ? 1 : v }
       mean_mat = means.repeat nmat.rows, 0
       stddev_mat = stddevs.repeat nmat.rows, 0
-      ret = (nmat - mean_mat) / stddev_mat
+      (nmat - mean_mat) / stddev_mat
     end
   end
 end

data/machine_learning_workbench.gemspec

@@ -5,32 +5,46 @@ $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 Gem::Specification.new do |spec|
   spec.name          = "machine_learning_workbench"
   spec.version       = `git describe`
-  spec.authors       = ["Giuseppe Cuccu"]
-  spec.email         = ["giuseppe.cuccu@gmail.com"]
+  spec.author        = "Giuseppe Cuccu"
+  spec.email         = "giuseppe.cuccu@gmail.com"
 
-  spec.summary       = %q{Workbench for practical machine learning in Ruby.}
-  spec.description   = %q{This workbench holds a collection of machine learning methods in Ruby. Rather than specializing on a single task or method, this gem aims at providing an encompassing framework for any machine learning application.}
+  spec.summary       = %q[Workbench for practical machine learning in Ruby.]
+  spec.description   = %q[\
+    This workbench holds a collection of machine learning
+    methods in Ruby. Rather than specializing on a single task or method, this
+    gem aims at providing an encompassing framework for any machine learning
+    application.].gsub('  ', '')
   spec.homepage      = "https://github.com/giuse/machine_learning_workbench"
   spec.license       = "MIT"
+  spec.post_install_message = %Q[\
+    Thanks for installing the machine learning workbench!
+    It is still a work in progress, feel free to open an issue or drop me an email
+    and start a discussion if you are using this gem. Cheers!
+  ].gsub('  ', '')
 
-  spec.files         = `git ls-files -z`.split("\x0").reject do |f|
-    f.match(%r{^(test|spec|features)/})
-  end
-  spec.bindir        = "exe"
-  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
-  spec.require_paths = ["lib"]
+  spec.files = `git ls-files -z`.split("\x0").reject { |f| f.start_with? "spec" }
 
-  spec.add_dependency "nmatrix-atlas", "~> 0.2"
+  # spec.bindir        = "exe"
+  # spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+  spec.required_ruby_version = '>= 2.4.0'
 
+  # Install
   spec.add_development_dependency "bundler", "~> 1.16"
   spec.add_development_dependency "rake", "~> 10.0"
+
+  # Test
   spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency "rmagick"  # only used for one example
+
+  # Debug
   spec.add_development_dependency "pry", "~> 0.10"
   spec.add_development_dependency "pry-nav", "~> 0.2"
   spec.add_development_dependency "pry-rescue", "~> 1.4"
   spec.add_development_dependency "pry-stack_explorer", "~> 0.4"
 
-  # currently under trial
-  spec.add_development_dependency "rmagick"
-  spec.add_development_dependency "parallel"
+  # Run
+  spec.requirements << "libatlas-base-dev"  # library for following dependency
+  spec.add_dependency "nmatrix-atlas", "~> 0.2"
+  spec.add_dependency "parallel", "~> 1.12"
 end

metadata

@@ -1,29 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: machine_learning_workbench
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.0
 platform: ruby
 authors:
 - Giuseppe Cuccu
 autorequire: 
-bindir: exe
+bindir: bin
 cert_chain: []
-date: 2018-03-06 00:00:00.000000000 Z
+date: 2018-03-14 00:00:00.000000000 Z
 dependencies:
-- !ruby/object:Gem::Dependency
-  name: nmatrix-atlas
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.2'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.2'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -66,6 +52,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rmagick
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: pry
   requirement: !ruby/object:Gem::Requirement
@@ -123,38 +123,40 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0.4'
 - !ruby/object:Gem::Dependency
-  name: rmagick
+  name: nmatrix-atlas
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
+        version: '0.2'
+  type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '0.2'
 - !ruby/object:Gem::Dependency
   name: parallel
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
+        version: '1.12'
+  type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
-description: This workbench holds a collection of machine learning methods in Ruby.
-  Rather than specializing on a single task or method, this gem aims at providing
-  an encompassing framework for any machine learning application.
-email:
-- giuseppe.cuccu@gmail.com
+        version: '1.12'
+description: |-
+  \
+  This workbench holds a collection of machine learning
+  methods in Ruby. Rather than specializing on a single task or method, this
+  gem aims at providing an encompassing framework for any machine learning
+  application.
+email: giuseppe.cuccu@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -169,9 +171,11 @@ files:
 - Rakefile
 - bin/console
 - bin/setup
+- examples/image_compression.rb
 - examples/neuroevolution.rb
 - lib/machine_learning_workbench.rb
 - lib/machine_learning_workbench/compressor.rb
+- lib/machine_learning_workbench/compressor/online_vector_quantization.rb
 - lib/machine_learning_workbench/compressor/vector_quantization.rb
 - lib/machine_learning_workbench/monkey.rb
 - lib/machine_learning_workbench/neural_network.rb
@@ -195,7 +199,10 @@ homepage: https://github.com/giuse/machine_learning_workbench
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
+post_install_message: |
+  Thanks for installing the machine learning workbench!
+  It is still a work in progress, feel free to open an issue or drop me an email
+  and start a discussion if you are using this gem. Cheers!
 rdoc_options: []
 require_paths:
 - lib
@@ -203,15 +210,16 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 2.4.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
-requirements: []
+requirements:
+- libatlas-base-dev
 rubyforge_project: 
-rubygems_version: 2.6.11
+rubygems_version: 2.6.13
 signing_key: 
 specification_version: 4
 summary: Workbench for practical machine learning in Ruby.