nametrainer 0.2.1 → 0.2.2

data/README.md

@@ -65,15 +65,13 @@ Install with `gem install nametrainer`.
 
 You will also have to install Qt bindings for Ruby:
 
--   On Windows, the `qtbindings` gem should get you up and running.
-
 -   On Linux, install the appropriate package for your distribution,
-    e. g. `qt4-ruby` on Ubuntu.
-
-    You can also compile the bindings using the `qtbindings` gem
+    or compile the bindings using the `qtbindings` gem
     (see the [qtbindings README](https://github.com/ryanmelt/qtbindings#readme)
     for instructions).
 
+-   On Windows, the `qtbindings` gem should get you up and running.
+
 Acknowledgements
 ----------------
 

data/Rakefile

@@ -1,6 +1,6 @@
 # Rakefile for the nametrainer program.
 #
-# Copyright (C) 2012 Marcus Stollsteimer
+# Copyright (C) 2012-2013 Marcus Stollsteimer
 
 require 'rake/testtask'
 

data/bin/nametrainer

@@ -1,4 +1,4 @@
-#!/usr/bin/ruby -w
+#!/usr/bin/env ruby
 
 require 'nametrainer'
 
@@ -10,7 +10,7 @@ module Nametrainer
 
   # Prints an error message, then exits with +code+
   # (<tt>:general</tt> or <tt>:usage</tt>).
-  def self.fail(message, code = :general) #
+  def self.fail(message, code = :general)
     warn "#{PROGNAME}: #{message}"
     exit ERRORCODE[code]
   end

data/lib/nametrainer.rb

@@ -16,7 +16,7 @@
 #
 # == Author
 #
-# Copyright (C) 2012 Marcus Stollsteimer
+# Copyright (C) 2012-2013 Marcus Stollsteimer
 #
 # License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
 
@@ -30,9 +30,11 @@ rescue LoadError => e
 end
 
 require 'nametrainer/gui'  unless Nametrainer::QT_LOAD_ERROR
-require 'nametrainer/person'
 require 'nametrainer/collection'
+require 'nametrainer/collectionloader'
 require 'nametrainer/optionparser'
+require 'nametrainer/person'
+require 'nametrainer/rng'
 require 'nametrainer/statistics'
 require 'nametrainer/version'
 

data/lib/nametrainer/collection.rb

@@ -1,69 +1,61 @@
-require 'set'
 require 'yaml'
+require 'forwardable'
 
-require 'nametrainer/person'
+require 'nametrainer/rng'
 
 module Nametrainer
 
-  # A Class for a collection of persons, each with a name,
+  # A class for a collection of persons, each with a name,
   # a corresponding (image) file, and a score.
-  # A collection is an array of instances of the Person class.
   #
-  # Open a collection with
-  #   collection = Collection.new(directory, extensions)
-  #
-  # For each file with an extension from the +extensions+ array a Person
-  # instance is created, using the file name as the person's name
-  # (extension is removed, underscore is converted to space)
-  # or the content of a corresponding `txt' file, and the file name as
-  # the +image+ attribute.
+  # Create a Collection instance with
+  #   collection = CollectionLoader.load(
+  #                  :directory  => directory,
+  #                  :extensions => extensions
+  #                )
   #
   # You can get a random person from a collection with
   #   person = collection.sample
   #
   # Persons with a lower score are chosen more often
   # than persons with a higher score.
-  class Collection < Array
+  class Collection
+
+    extend Forwardable
+    def_delegators :@collection,
+                   :size, :empty?, :[], :last, :index, :shuffle, :map, :each
+
+    include Enumerable
 
     SCORE_FILE = 'nametrainer.dat'
 
-    # Creates a Collection instance.
-    # It searches in +directory+ for files with the given
-    # file extensions (also in upper case) and populates
-    # the collection with corresponding Person instances.
+    # Creates a Collection instance. Expects an argument hash with:
     #
-    # +directory+ - collection directory
-    # +extension+ - array of file extensions
-    def initialize(directory, extensions)
-      super()
-      @directory = directory
-      @extensions = extensions.to_set
-      @extensions.merge extensions.map {|i| i.upcase }
-      self.concat self.class.load(@directory, @extensions.to_a)
+    # +:persons+   - array of Person instances
+    # +:directory+ - collection directory
+    # +:rng+       - random number generator, defaults to RNG
+    def initialize(args)
+      @collection = args[:persons]
+      @directory  = args[:directory]
+      @rng        = args[:rng] || RNG.new(:size => @collection.size, :weighting_factor => 6)
     end
 
     # Returns an array of all names.
     def names
-      all_names = Array.new
-      self.each {|person| all_names << person.name }
-
-      all_names
+      map {|person| person.name }
     end
 
     # Returns a hash with the score of all persons (name => score).
     def scores
-      all_scores = {}
-      self.each {|person| all_scores[person.name] = person.score }
-
-      all_scores
+      Hash[map {|person| [person.name, person.score] }]
     end
 
     # Sets the score of some or all persons.
     #
     # +new_scores+ - hash with (name => score) values
     def set_scores(new_scores)
-      self.each do |person|
-        person.score = new_scores[person.name]  unless new_scores[person.name].nil?
+      each do |person|
+        person.score = new_scores[person.name]  if new_scores[person.name]
       end
     end
 
@@ -80,78 +72,26 @@ module Nametrainer
       File.open(filename, 'w') {|f| f.write(scores.to_yaml) }
     end
 
+    # Delete score file.
+    def delete_scores
+      filename = File.expand_path("#{@directory}/#{SCORE_FILE}")
+      File.delete(filename)
+    end
+
     # Returns a random element, preferring persons with a smaller score.
     def sample
-      self.shuffle.sort[weighted_random_index]  # shuffle first, so that elements with equal scores get mixed up
+      shuffle.sort[@rng.rand]  # shuffle first to mix up elements with equal scores
     end
 
-    # Returns the successor of the specified element.
-    # The successor of the last element is the first element.
+    # Returns the successor of the specified element, if possible,
+    # or the first element.
     #
     # +element+ - element whose successor should be returned
     def successor(element)
-      index = self.index(element)
-      return nil  if index.nil?
-
-      (index == self.size - 1) ? self[0] : self[index + 1]
-    end
-
-    private
-
-    # Returns a random index (obsolete).
-    def random_index
-      rand(self.size)
-    end
+      element_index = index(element)
+      return first  unless element_index
 
-    # Returns a random index, preferring smaller indices.
-    def weighted_random_index
-      indices = indices_urn(:size => self.size, :weighting_factor => 6)
-
-      indices[rand(indices.size)]
-    end
-
-    # Returns an array of all indices from 0 to :size - 1, where lower indices are
-    # more frequent than higher indices. Index 0 will be about :weighting_factor
-    # times more probable then the highest index.
-    def indices_urn(options)
-      size = options[:size]
-      weighting_factor = options[:weighting_factor]
-      urn = Array.new
-      # repeatedly add partial ranges of indices to urn
-      1.upto(weighting_factor) do |i|
-        count = (i.to_f/weighting_factor * size).ceil
-        urn += (0...count).to_a
-      end
-
-      urn
-    end
-
-    # class methods
-
-    # Load a collection. Returns an array of Person instances.
-    def self.load(directory, extensions)
-      extension_list = extensions.join(',')
-      files = Dir.glob("#{directory}/*.{#{extension_list}}").sort
-      result = Array.new
-      files.each do |file|
-        name = get_name(file, extensions)
-        result << Person.new(name, file)
-      end
-
-      result
-    end
-
-    # Get name from corresponding `txt' file or
-    # from file name (remove extension, convert underscores).
-    def self.get_name(file, extensions)
-      name = file.dup
-      extensions.each {|ext| name.gsub!(/\.#{ext}\Z/, '') }  # remove file extension
-      begin
-        info_file = "#{name}.txt"
-        File.read(info_file).chomp
-      rescue
-        File.basename(name).tr('_', ' ')
-      end
+      self[element_index + 1] || first
     end
   end
 end

data/lib/nametrainer/collectionloader.rb

@@ -0,0 +1,55 @@
+require 'set'
+
+require 'nametrainer/person'
+require 'nametrainer/collection'
+
+module Nametrainer
+
+  # CollectionLoader.load loads a collection from a directory
+  # and returns a Collection instance.
+  #
+  # It searches in the directory for files with the given
+  # file extensions (ignoring case) and for each file creates
+  # a Person instance, using the file name as the person's +name+
+  # (extension is removed, underscore is converted to space)
+  # or the content of a corresponding `txt' file,
+  # and the file name as the +image+ attribute.
+  module CollectionLoader
+
+    # Loads a collection. Expects an argument hash with:
+    #
+    # +:directory+        - collection directory
+    # +:extensions+       - array of file extensions
+    # +:collection_class+ - defaults to Collection
+    # +:person_class+     - defaults to Person
+    #
+    # Returns a Collection instance.
+    def self.load(args)
+      directory  = args[:directory]
+      extensions = args[:extensions]
+      collection_class = args[:collection_class] || Collection
+      person_class = args[:person_class] || Person
+
+      pattern = extensions.map {|ext| ext.downcase }.uniq.join('|')
+      valid_extensions = /\.(#{pattern})\Z/i
+      files = Dir.glob("#{directory}/*").grep(valid_extensions)
+      persons = files.sort.map {|file| person_class.new(get_name(file), file) }
+
+      collection_class.new(:persons => persons, :directory => directory)
+    end
+
+    private
+
+    # Get name from corresponding `txt' file or
+    # from file name (remove extension, convert underscores).
+    def self.get_name(file)
+      name = file.gsub(/#{File.extname(file)}\Z/, '')
+      begin
+        info_file = "#{name}.txt"
+        File.read(info_file).chomp
+      rescue
+        File.basename(name).tr('_', ' ')
+      end
+    end
+  end
+end

data/lib/nametrainer/gui.rb

@@ -39,7 +39,7 @@ module Nametrainer
       show
 
       collection_dir = options[:collection]
-      init_collection File.expand_path(collection_dir)  unless collection_dir.nil?
+      init_collection File.expand_path(collection_dir)  if collection_dir
     end
 
     # Initializes the GUI layout and functions.
@@ -127,15 +127,18 @@ module Nametrainer
     # Opens a file dialog and tries to load a collection.
     def load_collection
       collection_dir = Qt::FileDialog.get_existing_directory self, 'Load Collection'
-      return  if collection_dir.nil?
-      init_collection File.expand_path(collection_dir)
+      init_collection File.expand_path(collection_dir)  if collection_dir
     end
 
     # Tries to load a collection (does not change anything if load fails).
     #
     # +collection_dir+ - path to collection
     def init_collection(collection_dir)
-      collection = Nametrainer::Collection.new(collection_dir, Nametrainer::FILE_EXTENSIONS)
+      args = {
+        :directory  => collection_dir,
+        :extensions => Nametrainer::FILE_EXTENSIONS
+      }
+      collection = Nametrainer::CollectionLoader.load(args)
       if collection.nil? or collection.empty?
         Qt::MessageBox.warning self, 'Error', Nametrainer.collection_empty_message
         return
@@ -236,7 +239,7 @@ module Nametrainer
     def choose_person
       @name_label.set_text ''
       if @ordered_checkbox.is_checked
-        @person = @person.nil? ? @collection[0] : @collection.successor(@person)
+        @person = @collection.successor(@person)
       else
         @person = @collection.sample
       end
@@ -248,7 +251,7 @@ module Nametrainer
 
     # Repaints the image when the application window is resized.
     def resizeEvent(event)
-      return  if @image.null? || @image.nil?
+      return  if (@image.nil? || @image.null?)
       scaledSize = @image.size.scale(@image_label.size, Qt::KeepAspectRatio)
       show_image  if scaledSize != @image_label.pixmap.size
     end

data/lib/nametrainer/rng.rb

@@ -0,0 +1,63 @@
+module Nametrainer
+
+  # A random number generator.
+  #
+  # Get a random index from 0 to (size - 1), where smaller indices
+  # are preferred, with
+  #
+  #   rng = RNG.new(:size => size, :weighting_factor => 6)
+  #   rng.rand
+  #
+  # Index 0 will be :weighting_factor times more probable
+  # than the highest index.
+  class RNG
+
+    def initialize(args)
+      @size = args[:size]
+      @weighting_factor = args[:weighting_factor]
+
+      @limits = normalized_limits
+    end
+
+    #--
+    # Weighted random numbers in the range from 0 to (size - 1).
+    #
+    # Divide the range [0;1) into intervals with size depending
+    # on the desired weight. Choose a (evenly distributed)
+    # random number and return the number that corresponds to
+    # the interval within it lies.
+    #++
+    def rand
+      x = Kernel.rand
+      interval = @limits.find_index {|limit| x < limit }
+
+      interval || (@size - 1)
+    end
+
+    private
+
+    # Returns a list of weighting factors from @weighting_factor to 1.
+    def weighting_factors
+      delta = (@weighting_factor - 1).to_f / (@size - 1)
+
+      Array.new(@size) {|index| @weighting_factor - index * delta}
+    end
+
+    # Returns a list of upper limits for all intervals.
+    def raw_limits
+      limits = weighting_factors.dup
+      1.upto(@size - 1) do |index|
+        limits[index] = limits[index-1] + limits[index]
+      end
+
+      limits
+    end
+
+    # Returns a list of upper limits normalized to the range [0;1).
+    def normalized_limits
+      max = raw_limits.last
+
+      raw_limits.map {|limit| limit.to_f / max }
+    end
+  end
+end

data/lib/nametrainer/version.rb

@@ -1,11 +1,11 @@
 module Nametrainer
 
   PROGNAME = 'nametrainer'
-  VERSION  = '0.2.1'
-  DATE     = '2012-10-03'
+  VERSION  = '0.2.2'
+  DATE     = '2013-01-04'
   HOMEPAGE = 'https://github.com/stomar/nametrainer/'
 
-  COPYRIGHT = "Copyright (C) 2012 Marcus Stollsteimer.\n" +
+  COPYRIGHT = "Copyright (C) 2012-2013 Marcus Stollsteimer.\n" +
               "License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>.\n" +
               "This is free software: you are free to change and redistribute it.\n" +
               "There is NO WARRANTY, to the extent permitted by law."

data/test/test_collection.rb

@@ -2,14 +2,18 @@ require 'minitest/spec'
 require 'minitest/autorun'
 
 require 'nametrainer/collection'
+require 'nametrainer/collectionloader'
 
-SRCPATH = File.dirname(__FILE__)
+SRCPATH = File.dirname(__FILE__)  unless defined?(SRCPATH)
 
 describe Nametrainer::Collection do
 
   before do
-    extensions = %w{png jpg}
-    @collection = Nametrainer::Collection.new("#{SRCPATH}/collection", extensions)
+    args = {
+      :directory  => "#{SRCPATH}/collection",
+      :extensions => %w{png jpg}
+    }
+    @collection = Nametrainer::CollectionLoader.load(args)
     @sample_scores = {
       'Albert Einstein' => 3,
       'Paul Dirac' => 1,
@@ -41,12 +45,13 @@ describe Nametrainer::Collection do
     @collection.scores.must_equal @sample_scores
   end
 
-  it 'can save the scores to a file and load them again' do
+  it 'can save the scores to a file and load them again and delete them' do
     @collection.set_scores(@sample_scores)
     @collection.export_scores
     @collection.first.score = nil
     @collection.import_scores
     @collection.scores.must_equal @sample_scores
+    @collection.delete_scores
   end
 
   it 'can get sorted by the scores' do
@@ -66,30 +71,6 @@ describe Nametrainer::Collection do
     @collection.successor(p1).name.must_equal p2.name
     @collection.successor(p2).name.must_equal p3.name
     @collection.successor(p3).name.must_equal p1.name
-  end
-
-  it 'can increase the score for a specified person' do
-    person = @collection.last
-    person.score.must_equal 0
-    person.increase_score
-    @collection.last.score.must_equal 1
-  end
-
-  # private methods
-  it 'can return a weighted index list' do
-    expected = [0, 0, 0, 0, 1, 1, 1, 1, 2, 2, 2, 2,
-                3, 3, 3, 4, 4, 4, 5, 5, 5,
-                6, 6, 7, 7, 8, 8,
-                9, 10, 11]
-    indices = @collection.send(:indices_urn, :size => 12, :weighting_factor => 4)
-    indices.sort.must_equal expected
-  end
-
-  it 'returns random indices in the correct range' do
-    samples = 100
-    indices = Array.new(samples) { @collection.send(:weighted_random_index) }
-    indices.size.must_equal samples
-    indices.sort.first.must_be :>=, 0
-    indices.sort.last.must_be :<, @collection.size
+    @collection.successor(nil).name.must_equal p1.name
   end
 end

data/test/test_collectionloader.rb

@@ -0,0 +1,26 @@
+require 'minitest/spec'
+require 'minitest/autorun'
+
+require 'nametrainer/collectionloader'
+
+SRCPATH = File.dirname(__FILE__)  unless defined?(SRCPATH)
+
+describe Nametrainer::CollectionLoader do
+
+  before do
+    args = {
+      :directory  => "#{SRCPATH}/collection",
+      :extensions => %w{png JPG}
+    }
+    @collection = Nametrainer::CollectionLoader.load(args)
+  end
+
+  it 'returns a Collection instance' do
+    @collection.class.must_equal Nametrainer::Collection
+    @collection.first.class.must_equal Nametrainer::Person
+  end
+
+  it 'returns a collection with the correct size' do
+    @collection.size.must_equal 3
+  end
+end

data/test/test_rng.rb

@@ -0,0 +1,37 @@
+require 'minitest/spec'
+require 'minitest/autorun'
+
+require 'nametrainer/rng'
+
+describe Nametrainer::RNG do
+
+  before do
+    @size = 7
+    @rng = Nametrainer::RNG.new(:size => @size, :weighting_factor => 4)
+  end
+
+  it 'returns random indices in the correct range' do
+    samples = 100
+    indices = Array.new(samples) { @rng.rand }
+    indices.size.must_equal samples
+    indices.sort.first.must_be :>=, 0
+    indices.sort.last.must_be :<, @size
+  end
+
+  it 'returns random indices with the expected frequency' do
+    samples = 100000
+    indices = Array.new(samples) { @rng.rand }
+
+    frequency = Hash.new {|h, k| h[k] = 0 }
+    indices.each do |index|
+      frequency[index] += 1
+    end
+    relative_frequency = frequency.sort.map {|ind, freq| freq.to_f/samples }
+
+    expected = [4.0/17.5, 3.5/17.5, 3.0/17.5, 2.5/17.5,
+                2.0/17.5, 1.5/17.5, 1.0/17.5]
+    relative_frequency.each_with_index do |freq, index|
+      freq.must_be_within_epsilon expected[index], 0.05
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: nametrainer
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.2.2
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-10-03 00:00:00.000000000 Z
+date: 2013-01-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
-  requirement: &80165180 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,15 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *80165180
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: minitest
-  requirement: &80164650 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,7 +37,12 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *80164650
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 description: nametrainer is a name learning trainer using the Qt GUI toolkit. It will
   assist you in learning people's names from a collection of images.
 email: sto.mar@web.de
@@ -55,12 +65,16 @@ files:
 - demo_collection/Werner_Heisenberg.png
 - demo_collection/Albert_Einstein.png
 - lib/nametrainer/optionparser.rb
+- lib/nametrainer/collectionloader.rb
 - lib/nametrainer/gui.rb
 - lib/nametrainer/version.rb
+- lib/nametrainer/rng.rb
 - lib/nametrainer/person.rb
 - lib/nametrainer/collection.rb
 - lib/nametrainer/statistics.rb
 - lib/nametrainer.rb
+- test/test_rng.rb
+- test/test_collectionloader.rb
 - test/test_person.rb
 - test/test_statistics.rb
 - test/test_collection.rb
@@ -70,7 +84,6 @@ files:
 - test/collection/001.txt
 - test/collection/Max_Born.png
 - test/collection/002.JPG
-- test/collection/nametrainer.dat
 homepage: https://github.com/stomar/nametrainer/
 licenses:
 - GPL-3
@@ -94,11 +107,13 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements:
 - the Qt toolkit and Qt bindings for Ruby
 rubyforge_project: nametrainer
-rubygems_version: 1.8.11
+rubygems_version: 1.8.24
 signing_key: 
 specification_version: 3
 summary: nametrainer is a name learning trainer using the Qt GUI toolkit.
 test_files:
+- test/test_rng.rb
+- test/test_collectionloader.rb
 - test/test_person.rb
 - test/test_statistics.rb
 - test/test_collection.rb

data/test/collection/nametrainer.dat

@@ -1,4 +0,0 @@
---- 
-Paul Dirac: 1
-Max Born: 2
-Albert Einstein: 3