knnball 0.0.5 → 0.0.6

data/README.md

@@ -2,10 +2,10 @@ KnnBall Instruction
 ===================
 
 KnnBall is a Ruby library that implements *Querying neareast neighbor algorithm*.
-This algorithm optimize the search of the nearest point given another point as input.
+This algorithm optimize the search of the nearest point given a point as input.
 
-It works with any number of dimension but written seems accord on the point
-that with more than 10 dimensions, brute force approach might give better results.
+It works with any number of dimension but essays seems to accord on the fact
+that with more than 10 dimensions, brute force approach will give better results.
 
 In this library, each point is associated to a value,
 this way the library acts as an index for multidimensional data like
@@ -18,23 +18,26 @@ Usage
     require 'knnball'
     
     data = [
-    	{:id => 1, :coord => [6.3299934, 52.32444]},
-    	{:id => 2, :coord => [3.34444, 53.23259]},
-    	{:id => 3, :coord => [4.22452, 53.243982]},
-    	{:id => 4, :coord => [4.2333424, 51.239994]},
+    	{:id => 1, :point => [6.3299934, 52.32444]},
+    	{:id => 2, :point => [3.34444, 53.23259]},
+    	{:id => 3, :point => [4.22452, 53.243982]},
+    	{:id => 4, :point => [4.2333424, 51.239994]},
     	# ...
     ]
 
     index = KnnBall.build(data)
     
     result = index.nearest([3.43353, 52.34355])
-    puts result # --> {:id=>2, :coord=>[3.34444, 53.23259]}
+    puts result # --> {:id=>2, :point=>[3.34444, 53.23259]}
+    
+    restults = index.nearest([3.43353, 52.34355], :limit => 3)
+    puts result # --> [{...}, {...}, {...}]
 
 Some notes about the above:
 
-*data* must is given using an array of hashes. 
+*data* is given using an array of hashes. 
 The only requirement of an Hash instance is
-to have a :coord keys containing an array of coordinate.
+to have a :point keys containing an array of coordinate.
 in the documentation one of this Hash instance will be
 called a *value* and the array of coordinates a *point*.
 Sticking to built-in data-type will allow you to easily
@@ -49,8 +52,8 @@ tree to store and retrieve the values. The nodes of the KDTree are Ball instance
 whoose class name refer to the theory of having ball containing smaller ball and so
 on. In practice, this class does not behave like a ball, but by metaphore, it may help.
 
-*KDTree#nearest* retrieve the nearest *value* of the given *point*.
-
+*KDTree#nearest* retrieve the nearest *value* of the given *point* by default or 
+the k nearest value if ':limit' optional argument is greater than 1.
 
 Roadmap
 -------

data/knnball.gemspec

@@ -4,12 +4,12 @@ Gem::Specification.new do |s|
   s.rubygems_version = '1.3.5'
 
   s.name = 'knnball'
-  s.version = '0.0.5'
-  s.date = '2011-05-23'
+  s.version = '0.0.6'
+  s.date = '2011-09-09'
   s.rubyforge_project = 'knnball'
 
-  s.summary = "K-Nearest Neighbor queries using a KDTree"
-  s.description = "Implements K-Nearest Neighbor algorithm using a KDTree in Ruby."
+  s.summary = "Multi-dimensional nearest neighbor search"
+  s.description = "Implements K-Nearest Neighbor algorithm using a KDTree in Ruby. Usefull for sorting geolocation or any other multi-dimensional data."
 
   s.authors = ["Olivier Amblet"]
   s.email = 'olivier@amblet.net'
@@ -30,10 +30,13 @@ lib/knnball.rb
 lib/knnball/ball.rb
 lib/knnball/stat.rb
 lib/knnball/kdtree.rb
+lib/knnball/result_set.rb
 test/specs/ball_spec.rb
 test/specs/data.json
 test/specs/kdtree_spec.rb
 test/specs/knnball_spec.rb
+test/specs/result_set_spec.rb
+test/specs/spec_helpers.rb
 test/units/stat_test.rb
 ]
   # = MANIFEST =

data/lib/knnball/ball.rb

@@ -22,8 +22,8 @@ module KnnBall
       unless (value.respond_to?(:include?) && value.respond_to?(:[]))
         raise ArgumentError.new("Value must at least respond to methods include? and [].")
       end
-      unless (value.include?(:coord))
-        raise ArgumentError.new("value must contains :coord key but has only #{value.keys.inspect}")
+      unless (value.include?(:point))
+        raise ArgumentError.new("value must contains :point key but has only #{value.keys.inspect}")
       end
       @value = value
       @right = right
@@ -32,12 +32,12 @@ module KnnBall
     end
     
     def center
-      value[:coord]
+      value[:point]
     end
     
     def nearest(target, min)
       result = nil
-      d = [distance(target), min[0]].min
+      d = [quick_distance(target), min[0]].min
       if d < min[0]
         min[0] = d
         result = self
@@ -80,6 +80,18 @@ module KnnBall
       Math.sqrt([center, coordinates].transpose.map {|a,b| (b - a)**2}.reduce {|d1,d2| d1 + d2})
     end
     
+    # Quickly compute a distance using Manhattan
+    def quick_distance(coordinates)
+      distance(coordinates)
+#      coordinates = coordinates.center if coordinates.respond_to?(:center)
+#      [center, coordinates].transpose.map {|a,b| (b - a)**2}.reduce {|d1,d2| d1 + d2}
+#      [center, coordinates].transpose.map {|a,b| (b - a).abs}.reduce {|d1,d2| d1 + d2}
+    end
+    
+    def count
+      1 + (left.nil? ? 0 : left.count) + (right.nil? ? 0 : right.count)
+    end
+    
     # Retrieve true if this is a leaf ball.
     #
     # A leaf ball has no sub_balls.
@@ -87,6 +99,11 @@ module KnnBall
       @left.nil? && @right.nil?
     end
     
+    # Return true if this ball has a left and a right ball
+    def complete?
+      ! (@left.nil? || @right.nil?)
+    end
+    
     # Generate an Array from this Ball.
     #
     # index 0 contains the value object,

data/lib/knnball/kdtree.rb

@@ -16,30 +16,100 @@ module KnnBall
     def initialize(root = nil)
       @root = root
     end
-    
-    def nearest(coord, &cmp_block)
+
+    # Retrieve the nearest point from the given coord array.
+    #
+    # available keys for options are :root and :limit
+    #
+    # Wikipedia tell us (excerpt from url http://en.wikipedia.org/wiki/Kd%5Ftree#Nearest%5Fneighbor%5Fsearch)
+    #
+    # Searching for a nearest neighbour in a k-d tree proceeds as follows:
+    # 1. Starting with the root node, the algorithm moves down the tree recursively, 
+    #    in the same way that it would if the search point were being inserted 
+    #    (i.e. it goes left or right depending on whether the point is less than or 
+    #    greater than the current node in the split dimension).
+    # 2. Once the algorithm reaches a leaf node, it saves that node point as the "current best"
+    # 3. The algorithm unwinds the recursion of the tree, performing the following steps at each node:
+    #    1. If the current node is closer than the current best, then it becomes the current best.
+    #    2. The algorithm checks whether there could be any points on the other side of the splitting 
+    #       plane that are closer to the search point than the current best. In concept, this is done 
+    #       by intersecting the splitting hyperplane with a hypersphere around the search point that
+    #       has a radius equal to the current nearest distance. Since the hyperplanes are all axis-aligned 
+    #       this is implemented as a simple comparison to see whether the difference between the splitting 
+    #       coordinate of the search point and current node is less than the distance (overall coordinates) from 
+    #       the search point to the current best.
+    #       1. If the hypersphere crosses the plane, there could be nearer points on the other side of the plane, 
+    #          so the algorithm must move down the other branch of the tree from the current node looking for 
+    #          closer points, following the same recursive process as the entire search.
+    #       2. If the hypersphere doesn't intersect the splitting plane, then the algorithm continues walking
+    #          up the tree, and the entire branch on the other side of that node is eliminated.
+    # 4. When the algorithm finishes this process for the root node, then the search is complete.
+    #
+    # Generally the algorithm uses squared distances for comparison to avoid computing square roots. Additionally, 
+    # it can save computation by holding the squared current best distance in a variable for comparison.
+    def nearest(coord, options = {})
       return nil if root.nil?
       return nil if coord.nil?
       
-      # Find the parent to which this coord should belongs to
-      # This will be our best first try
-      result = parent(coord)
-      smallest = result.distance(coord)
+      results = (options[:results] ? options[:results] : ResultSet.new({limit: options[:limit] || 1}))
+      root_ball = options[:root] || root
+      
+      # keep the stack while finding the leaf best match.
+      parents = []
+      
+      best_balls = []
+      in_target = []
+      
+      # Move down to best match
+      current_best = nil
+      current = root_ball
+      while current_best.nil?
+        dim = current.dimension-1
+        if(current.complete?)
+          next_ball = (coord[dim] <= current.center[dim] ? current.left : current.right)
+        elsif(current.leaf?)
+          next_ball = nil
+        else
+          next_ball = (current.left.nil? ? current.right : current.left)
+        end
+        if ( next_ball.nil? )
+          current_best = current
+        else
+          parents.push current
+          current = next_ball
+        end
+      end
       
-      # Starting back from the root, we check all rectangle that
-      # might overlap the smallest one.
-      best = [smallest]
-      better_one = root.nearest(coord, best)
-      return (better_one || result).value
+      # Move up to check split
+      parents.reverse!
+      results.add(current_best.quick_distance(coord), current_best.value)
+      parents.each do |current_node|
+        dist = current_node.quick_distance(coord)
+        if results.eligible?( dist )
+          results.add(dist, current_node.value)
+        end
+        
+        dim = current_node.dimension-1
+        if current_node.complete?
+          # retrieve the splitting node.
+          split_node = (coord[dim] <= current_node.center[dim] ? current_node.right : current_node.left)
+          best_dist = results.barrier_value
+          if( (coord[dim] - current_node.center[dim]).abs < best_dist)
+            # potential match, need to investigate subtree
+            nearest(coord, root: split_node, results: results)
+          end
+        end
+      end
+      return results.limit == 1 ? results.items.first : results.items
     end
     
     # Retrieve the parent to which this coord should belongs to
-    def parent(coord)
+    def parent_ball(coord)
       current = root
-      idx = current.dimension-1
+      d_idx = current.dimension-1
       result = nil
       while(result.nil?)
-        if(coord[idx] <= current.center[idx])
+        if(coord[d_idx] <= current.center[d_idx])
           if current.left.nil?
             result = current 
           else
@@ -52,7 +122,7 @@ module KnnBall
             current = current.right
           end
         end
-        idx = current.dimension-1
+        d_idx = current.dimension-1
       end
       return result
     end
@@ -76,6 +146,11 @@ module KnnBall
       return res
     end
     
+    # naive implementation
+    def count
+      root.count
+    end
+    
     private
     
     def each_ball(b, &proc)
@@ -87,4 +162,23 @@ module KnnBall
       return
     end
   end 
-end
+end
+
+
+__END__
+
+     ,x,
+    /   \ 
+  x      x    
+/     o   `x
+|      x´  `--x
+x       
+       
+     ,x,
+    / | \ 
+  x   | x\    
+/     |---`x----->
+|     |o | |
+x     | `x´ 
+      |  |
+      v  v

data/lib/knnball/result_set.rb

@@ -0,0 +1,57 @@
+# encoding: UTF-8
+
+# Copyright (C) 2011 Olivier Amblet <http://olivier.amblet.net>
+#
+# knnball is freely distributable under the terms of an MIT license.
+# See LICENSE or http://www.opensource.org/licenses/mit-license.php.
+
+module KnnBall
+  # This class represents a ball in the tree.
+  #
+  # The value of this ball will be its center
+  # while its radius is the distance between the center and
+  # the most far sub-ball.
+  class ResultSet
+    attr_reader :limit, :barrier_value
+    
+    def initialize(options = {})
+      @limit = options[:limit] || 10
+      @items = []
+      @barrier_value = options[:barrier_value]
+    end
+    
+    def eligible?(value)
+      @barrier_value.nil? || @items.count < limit || value < @barrier_value
+    end
+    
+    def add(value, item)
+      return false unless(eligible?(value))
+      
+      if @barrier_value.nil? || value > @barrier_value || @items.empty?
+        @barrier_value = value
+        @items.push [value, item]
+      else
+        idx = 0
+        begin 
+          while(value > @items[idx][0])
+            idx = idx + 1
+          end
+        rescue
+          raise "ArrayOutOfBound for #{value} at index #{idx} for a limit of #{limit}"
+        end
+        @items.insert idx, [value, item]
+      end
+      
+      if @items.count > limit
+        @items.pop
+      end
+      
+      @barrier_value = @items.last[0]
+      return true
+    end
+    
+    def items
+      @items.map {|i| i[1]}
+    end
+  end
+end

data/lib/knnball.rb

@@ -14,22 +14,23 @@ module KnnBall
   autoload :Ball, 'knnball/ball'
   autoload :Stat, 'knnball/stat'
   autoload :KDTree, 'knnball/kdtree'
+  autoload :ResultSet, 'knnball/result_set'
   
   # Retrieve a new BallTree given an array of input values.
   #
   # Each data entry in the array is a Hash containing
-  # keys :value and :coord, an array of position (one per dimension)
-  # [ {:value => 1, :coord => [1.23, 2.34, -1.23, -22.3]}, 
-  # {:value => 2, :coord => [-2.33, 4.2, 1.23, 332.2]} ]
+  # keys :value and :point, an array of position (one per dimension)
+  # [ {:value => 1, :point => [1.23, 2.34, -1.23, -22.3]}, 
+  # {:value => 2, :point => [-2.33, 4.2, 1.23, 332.2]} ]
   #
-  # @param data an array of Hash containing :value and :coord key
+  # @param data an array of Hash containing :value and :point key
   #
   # @see KnnBall::KDTree#initialize
   def self.build(data)
     if(data.nil? || data.empty?)
       raise ArgumentError.new("data argument must be a not empty Array")
     end
-    max_dimension = data.first[:coord].size
+    max_dimension = data.first[:point].size
     kdtree = KDTree.new(max_dimension)
     kdtree.root = generate(data, max_dimension)
     return kdtree
@@ -51,7 +52,7 @@ module KnnBall
     # and that every point on the right are of greater value
     # than the median. They are not more sorted than that.
     median_idx = Stat.median_index(data)
-    value = Stat.median!(data) {|v1, v2| v1[:coord][actual_dimension-1] <=> v2[:coord][actual_dimension-1]}
+    value = Stat.median!(data) {|v1, v2| v1[:point][actual_dimension-1] <=> v2[:point][actual_dimension-1]}
     ball = Ball.new(value)
     
     actual_dimension = (max_dimension == actual_dimension ? 1 : actual_dimension)

data/test/specs/ball_spec.rb

@@ -17,7 +17,7 @@ module KnnBall
           
     describe "Leaf balls" do
       before :each do
-        @value = {:id => 1, :coord => [1,2,3]}
+        @value = {:id => 1, :point => [1,2,3]}
         @ball = Ball.new(@value)
       end
       
@@ -26,7 +26,7 @@ module KnnBall
       end
       
       it "must have a center equals to the value location" do
-        @ball.center.must_equal @value[:coord]
+        @ball.center.must_equal @value[:point]
       end
       
       it "must convert itself to an Array instance" do
@@ -40,8 +40,8 @@ module KnnBall
     
     describe "Standard Balls" do
       before :each do
-        @value = {:id => 1, :coord => [1,2,3]}
-        @ball = Ball.new(@value, 1, Ball.new({:id => 3, :coord => [-1, -2, -3]}), Ball.new({:id => 2, :coord => [2, 3, 4]}))
+        @value = {:id => 1, :point => [1,2,3]}
+        @ball = Ball.new(@value, 1, Ball.new({:id => 3, :point => [-1, -2, -3]}), Ball.new({:id => 2, :point => [2, 3, 4]}))
       end
       
       it "wont be a leaf" do
@@ -49,35 +49,35 @@ module KnnBall
       end
       
       it "must_be_centered_at_the_ball_value_location" do
-        @ball.center.must_equal @value[:coord]
+        @ball.center.must_equal @value[:point]
       end
       
       it "must convert itself to an Array instance" do
         @ball.to_a.must_equal([
           @value, 
-          [{:id => 3, :coord => [-1, -2, -3]}, nil, nil],
-          [{:id => 2, :coord => [2, 3, 4]}, nil, nil]
+          [{:id => 3, :point => [-1, -2, -3]}, nil, nil],
+          [{:id => 2, :point => [2, 3, 4]}, nil, nil]
         ])
       end
       
       it "must convert itself to a Hash instance" do
         @ball.to_h.must_equal({:value => @value, 
-          :left => {:value => {:id => 3, :coord => [-1, -2, -3]}, :left => nil, :right => nil}, 
-          :right => {:value => {:id => 2, :coord => [2, 3, 4]}, :left => nil, :right => nil}
+          :left => {:value => {:id => 3, :point => [-1, -2, -3]}, :left => nil, :right => nil}, 
+          :right => {:value => {:id => 2, :point => [2, 3, 4]}, :left => nil, :right => nil}
         })
       end
     end
     
     describe "Ball with sub-balls" do
       before :each do
-        @value = {:id => 1, :coord => [1,2,3]}
+        @value = {:id => 1, :point => [1,2,3]}
         @leaf_1 = Ball.new(@value)
-        @leaf_2 = Ball.new({:id => 2, :coord => [2, 3, 4]})
-        @leaf_3 = Ball.new({:id => 3, :coord => [-1, -2 , -5]})
-        @leaf_4 = Ball.new({:id => 4, :coord => [-3, -2, -2]})
-        @sub_ball_1 = Ball.new({:id => 5, :coord => [1.4, 2, 2.5]}, 1, @leaf_1, @leaf_2)
-        @sub_ball_2 = Ball.new({:id => 6, :coord => [-2, -1.9, -3]}, 1, @leaf_3, @leaf_4)
-        @ball = Ball.new({:id => 7, :coord => [0, 0, 0]}, 1, @sub_ball_1, @sub_ball_2)
+        @leaf_2 = Ball.new({:id => 2, :point => [2, 3, 4]})
+        @leaf_3 = Ball.new({:id => 3, :point => [-1, -2 , -5]})
+        @leaf_4 = Ball.new({:id => 4, :point => [-3, -2, -2]})
+        @sub_ball_1 = Ball.new({:id => 5, :point => [1.4, 2, 2.5]}, 1, @leaf_1, @leaf_2)
+        @sub_ball_2 = Ball.new({:id => 6, :point => [-2, -1.9, -3]}, 1, @leaf_3, @leaf_4)
+        @ball = Ball.new({:id => 7, :point => [0, 0, 0]}, 1, @sub_ball_1, @sub_ball_2)
       end
       
       it "must be centered at (0,0,0)" do
@@ -92,8 +92,8 @@ module KnnBall
       end
       
       it "retrieve the correct distance" do
-        b1 = Ball.new({:id => 2, :coord => [2, 3, 4]})
-        b2 = Ball.new({:id => 3, :coord => [-1, -2 , -5]})
+        b1 = Ball.new({:id => 2, :point => [2, 3, 4]})
+        b2 = Ball.new({:id => 3, :point => [-1, -2 , -5]})
         b1.distance(b2).must_equal(Math.sqrt(115))
       end
     end

data/test/specs/data.json

@@ -1 +1 @@
-[{"id":"Dr Achermann Romeo","coord":[47.0495221,8.3079993]},{"id":"Dresse Achermann-Bieri Ursula","coord":[47.0525778,8.3052475]},{"id":"M. Ackermann Christian","coord":[46.9406862,7.3991925]},{"id":"Dr Ackermann Roland","coord":[47.3538085,7.9035746]},{"id":"Dr Adank-Sailer Gabrielle","coord":[47.1359809,7.2447156]},{"id":"Dr Aebersold Christian","coord":[47.1262539,7.2763632]},{"id":"Dresse Aebersold Gaby","coord":[47.1262539,7.2763632]},{"id":"M. Aellen Jean-Marc","coord":[46.1980464,6.1483353]},{"id":"M. Aerni Christian","coord":[46.18612,6.118075]},{"id":"Dr Akermann Felix","coord":[47.1697675,9.4766358]},{"id":"Dr Albrecht Silvia","coord":[47.1655638,7.5936764]},{"id":"M. Alder Ernst","coord":[47.6833333,8.75]},{"id":"Dr Althaus Marc-André","coord":[46.4810917,6.4571243]},{"id":"Dr Amati Francesca","coord":[46.5230847,6.640415]},{"id":"Anklin Bernard","coord":[47.3920158,8.5392456]},{"id":"Dr Bachelin Pierre","coord":[46.6668682,6.5107242]},{"id":"Dr Backes Hans-Ulrich","coord":[47.4238477,9.3686547]},{"id":"Badorff Cornel","coord":[47.4977665,8.7270143]},{"id":"Dr Bagutti Carlo","coord":[46.516054,6.608998]},{"id":"Dr Ballmer Peter Matthias","coord":[46.7617201,7.6279035]},{"id":"Dr Bandi-Ott Elisabeth","coord":[47.3839285,8.54832]},{"id":"Dr Barandun Jürg","coord":[47.3519079,8.5762373]},{"id":"Dr Barras Bernard","coord":[46.2270208,7.3533351]},{"id":"Dr Beck Thomas","coord":[46.7571286,7.6305141]},{"id":"Dr Bedat Bernard","coord":[46.2785274,6.1684023]},{"id":"M. Bekkering Anton","coord":[47.4226784,9.3184235]},{"id":"Dresse Benz Gabrielle","coord":[46.2304522,7.363867]},{"id":"M. Benz Martin","coord":[46.2304522,7.363867]},{"id":"M. Berchten Anthony","coord":[46.3873762,6.2208354]},{"id":"M. Berdoz Jean-Marc","coord":[46.2124628,6.131694]},{"id":"Mme Berdoz Nicole","coord":[46.2124628,6.131694]},{"id":"Dr Berger Hanspeter","coord":[46.684936,7.8499151]},{"id":"Dr Berghoff Ueli","coord":[47.2217408,8.6722444]},{"id":"Dr Bernasconi Cristiano","coord":[46.3601201,8.971514]},{"id":"Dr Bernhart Felix","coord":[46.9286035,7.447995]},{"id":"Dr Beuing Markus","coord":[46.4965828,9.8382621]},{"id":"Dr Beyeler Jürg","coord":[47.3805257,8.5428647]},{"id":"Dr Bianchi Michele","coord":[46.0056877,8.9407073]},{"id":"Dr Bickel Andreas","coord":[47.2287339,8.8268529]},{"id":"Dr Biedert Roland","coord":[47.1333363,7.2612937]}]
+[{"id":"Dr Achermann Romeo","point":[47.0495221,8.3079993]},{"id":"Dresse Achermann-Bieri Ursula","point":[47.0525778,8.3052475]},{"id":"M. Ackermann Christian","point":[46.9406862,7.3991925]},{"id":"Dr Ackermann Roland","point":[47.3538085,7.9035746]},{"id":"Dr Adank-Sailer Gabrielle","point":[47.1359809,7.2447156]},{"id":"Dr Aebersold Christian","point":[47.1262539,7.2763632]},{"id":"Dresse Aebersold Gaby","point":[47.1262539,7.2763632]},{"id":"M. Aellen Jean-Marc","point":[46.1980464,6.1483353]},{"id":"M. Aerni Christian","point":[46.18612,6.118075]},{"id":"Dr Akermann Felix","point":[47.1697675,9.4766358]},{"id":"Dr Albrecht Silvia","point":[47.1655638,7.5936764]},{"id":"M. Alder Ernst","point":[47.6833333,8.75]},{"id":"Dr Althaus Marc-André","point":[46.4810917,6.4571243]},{"id":"Dr Amati Francesca","point":[46.5230847,6.640415]},{"id":"Anklin Bernard","point":[47.3920158,8.5392456]},{"id":"Dr Bachelin Pierre","point":[46.6668682,6.5107242]},{"id":"Dr Backes Hans-Ulrich","point":[47.4238477,9.3686547]},{"id":"Badorff Cornel","point":[47.4977665,8.7270143]},{"id":"Dr Bagutti Carlo","point":[46.516054,6.608998]},{"id":"Dr Ballmer Peter Matthias","point":[46.7617201,7.6279035]},{"id":"Dr Bandi-Ott Elisabeth","point":[47.3839285,8.54832]},{"id":"Dr Barandun Jürg","point":[47.3519079,8.5762373]},{"id":"Dr Barras Bernard","point":[46.2270208,7.3533351]},{"id":"Dr Beck Thomas","point":[46.7571286,7.6305141]},{"id":"Dr Bedat Bernard","point":[46.2785274,6.1684023]},{"id":"M. Bekkering Anton","point":[47.4226784,9.3184235]},{"id":"Dresse Benz Gabrielle","point":[46.2304522,7.363867]},{"id":"M. Benz Martin","point":[46.2304522,7.363867]},{"id":"M. Berchten Anthony","point":[46.3873762,6.2208354]},{"id":"M. Berdoz Jean-Marc","point":[46.2124628,6.131694]},{"id":"Mme Berdoz Nicole","point":[46.2124628,6.131694]},{"id":"Dr Berger Hanspeter","point":[46.684936,7.8499151]},{"id":"Dr Berghoff Ueli","point":[47.2217408,8.6722444]},{"id":"Dr Bernasconi Cristiano","point":[46.3601201,8.971514]},{"id":"Dr Bernhart Felix","point":[46.9286035,7.447995]},{"id":"Dr Beuing Markus","point":[46.4965828,9.8382621]},{"id":"Dr Beyeler Jürg","point":[47.3805257,8.5428647]},{"id":"Dr Bianchi Michele","point":[46.0056877,8.9407073]},{"id":"Dr Bickel Andreas","point":[47.2287339,8.8268529]},{"id":"Dr Biedert Roland","point":[47.1333363,7.2612937]}]

data/test/specs/kdtree_spec.rb

@@ -9,49 +9,123 @@
 
 require 'minitest/autorun'
 require 'knnball'
-
+require_relative 'spec_helpers'
 
 module KnnBall
   
   describe KDTree do
     
+    include KnnBall::SpecHelpers
+    
     describe "building the tree" do
       it "must be an empty tree without params" do
         KDTree.new.must_be_empty
       end
       
       it "wont be an empty tree with data" do
-        KDTree.new(Ball.new({:id => 1, :coord => [1]})).wont_be_empty
+        KDTree.new(Ball.new({:id => 1, :point => [1]})).wont_be_empty
       end
     end
     
     describe "find the nearest ball" do
       before :each do
-        root = Ball.new({:id => 4, :coord => [5]}, 1,
-          Ball.new({:id => 2, :coord => [2]}, 1, Ball.new({:id => 1, :coord => [1]}), Ball.new({:id => 3, :coord => [3]})),
-          Ball.new({:id => 6, :coord => [13]}, 1, Ball.new({:id => 5, :coord => [8]}),
-            Ball.new({:id => 7, :coord => [21]}, 1, Ball.new({:id => 8, :coord => [34]})))
+        root = Ball.new(
+          {:id => 4, :point => [5]}, 1,
+          Ball.new({:id => 2, :point => [2]}, 1, 
+            Ball.new({:id => 1, :point => [1]}), Ball.new({:id => 3, :point => [3]})
+          ),
+          Ball.new({:id => 6, :point => [13]}, 1,
+            Ball.new({:id => 5, :point => [8]}),
+            Ball.new({:id => 7, :point => [21]}, 1, nil, Ball.new({:id => 8, :point => [34]}))
+          )
         )
         @ball_tree =   KDTree.new(root)
       end
       
       it "return a matching location" do
         @ball_tree.nearest([3])[:id].must_equal(3)
+        @ball_tree.nearest([35])[:id].must_equal(8)
+        @ball_tree.nearest([5])[:id].must_equal(4)
+        @ball_tree.nearest([2])[:id].must_equal(2)
       end
     end
     
     describe "find the parent for coordinates" do
       before :each do
-        @root = Ball.new({:id => 4, :coord => [5, 7]}, 1,
-          Ball.new({:id => 2, :coord => [3, 4]}, 1, Ball.new({:id => 1, :coord => [2, 2]}), Ball.new({:id => 3, :coord => [4, 8]})),
-          Ball.new({:id => 6, :coord => [13, 4]}, 1, Ball.new({:id => 5, :coord => [8, 1]}),
-            Ball.new({:id => 7, :coord => [21, 6]}, 1, Ball.new({:id => 8, :coord => [34, 5]})))
+        @root = Ball.new({:id => 4, :point => [5, 7]}, 1,
+          Ball.new({:id => 2, :point => [3, 4]}, 1, Ball.new({:id => 1, :point => [2, 2]}), Ball.new({:id => 3, :point => [4, 8]})),
+          Ball.new({:id => 6, :point => [13, 4]}, 1, Ball.new({:id => 5, :point => [8, 1]}),
+            Ball.new({:id => 7, :point => [21, 6]}, 1, Ball.new({:id => 8, :point => [34, 5]})))
         )
         @ball_tree =   KDTree.new(@root)
       end
       
       it "return the nearest parent" do
-        @ball_tree.parent([13.2, 4.5]).value[:id].must_equal(8)
+        @ball_tree.parent_ball([13.2, 4.5]).value[:id].must_equal(8)
+      end
+    end
+    
+    describe "find the best nearest ball" do
+      points = [
+        {:id => 1, :point => [2, 2]},
+        {:id => 2, :point => [3, 4]},
+        {:id => 3, :point => [4, 8]},
+        {:id => 4, :point => [5, 7]},
+        {:id => 5, :point => [8, 1]},
+        {:id => 6, :point => [13, 4]},
+        {:id => 7, :point => [21, 6]},
+        {:id => 8, :point => [34, 5]},
+      ]
+      
+      before do
+        @root = Ball.new({:id => 4, :point => [5, 7]}, 1,
+          Ball.new({:id => 2, :point => [3, 4]}, 1,
+            Ball.new({:id => 1, :point => [2, 2]}), Ball.new({:id => 3, :point => [4, 8]})
+          ),
+          Ball.new({:id => 6, :point => [13, 4]}, 1, 
+            Ball.new({:id => 5, :point => [8, 1]}),
+            Ball.new({:id => 7, :point => [21, 6]}, 1, 
+              nil, 
+              Ball.new({:id => 8, :point => [34, 5]})
+            )
+          )
+        )
+        @tree =   KDTree.new(@root)
+      end
+      
+      points.each do |p|
+        it "Should retrieve point #{p} if the exact location is given" do
+          assert_equal p, @tree.nearest(p[:point])
+        end
+        
+        p_near = p[:point].map {|c| c-0.1}
+        it "Should retrieve point #{p} if #{p_near} is given" do
+          assert_equal p, @tree.nearest(p_near)
+        end
+        
+        it "Should retrieve 2 nearest points in the correct order for point #{p}" do
+          # Points might be different as long as distance are equals
+          expected = brute_force(p, points, 2).map do |r| 
+            Math.sqrt( (p[:point][0]-r[:point][0])**2 + (p[:point][1]-r[:point][1])**2 )
+          end
+          results = @tree.nearest(p[:point], :limit => 2).map do |r|
+            Math.sqrt( (p[:point][0]-r[:point][0])**2 + (p[:point][1]-r[:point][1])**2 )
+          end
+          assert_equal expected, results
+        end
+        
+        it "Should retrieve 5 nearest points in the correct order for point #{p}" do
+          # Points might be different as long as distance are equals
+          bf = brute_force(p, points, 5)
+          expected = bf.map do |r| 
+            Math.sqrt( (p[:point][0]-r[:point][0])**2 + (p[:point][1]-r[:point][1])**2 )
+          end
+          nn = @tree.nearest(p[:point], :limit => 5)
+          results = nn.map do |r|
+            Math.sqrt( (p[:point][0]-r[:point][0])**2 + (p[:point][1]-r[:point][1])**2 )
+          end
+          assert_equal expected, results, "bf: #{bf.inspect} -- nn: #{nn.inspect}"
+        end
       end
     end
     
@@ -61,7 +135,7 @@ module KnnBall
       end
       
       it "Should return a tree array if not nil" do
-        KDTree.new(Ball.new({:id => 1, :coord => [1, 2, 3]})).to_a.must_equal [{:id => 1, :coord => [1,2,3]}, nil, nil]
+        KDTree.new(Ball.new({:id => 1, :point => [1, 2, 3]})).to_a.must_equal [{:id => 1, :point => [1,2,3]}, nil, nil]
       end
     end
   end

data/test/specs/knnball_spec.rb

@@ -10,8 +10,11 @@
 require 'minitest/autorun'
 require 'knnball'
 require 'json'
+require_relative 'spec_helpers'
 
 describe KnnBall do
+  include KnnBall::SpecHelpers
+  
   before do
     @ball_tree = MiniTest::Mock.new
   end
@@ -19,34 +22,34 @@ describe KnnBall do
   describe "when asked to build the tree" do
     it "must retrieve a KDTree instance" do
       KnnBall.build([
-        {:id => 1, :coord => [1.0,1.0]},
-        {:id => 2, :coord => [2.0, 3.0]}
+        {:id => 1, :point => [1.0,1.0]},
+        {:id => 2, :point => [2.0, 3.0]}
       ]).must_be :kind_of?, KnnBall::KDTree
     end
     
     it "must build a one dimension tree correctly" do
       tree = KnnBall.build(
-        [{:id => 2, :coord => [2]},
-          {:id => 3, :coord => [3]},
-          {:id => 1, :coord => [1]}]
+        [{:id => 2, :point => [2]},
+          {:id => 3, :point => [3]},
+          {:id => 1, :point => [1]}]
       )
-      tree.root.value.must_equal({:id => 2, :coord => [2]})
-      tree.root.left.value.must_equal({:id => 1, :coord => [1]})
+      tree.root.value.must_equal({:id => 2, :point => [2]})
+      tree.root.left.value.must_equal({:id => 1, :point => [1]})
       tree.root.left.left.must_be_nil
       tree.root.left.right.must_be_nil
       tree.root.right.wont_be_nil
-      tree.root.right.value.must_equal({:id => 3, :coord => [3]})
+      tree.root.right.value.must_equal({:id => 3, :point => [3]})
       
       KnnBall.build([
-          {:id => 1, :coord => [1]},
-          {:id => 2, :coord => [2]},
-          {:id => 3, :coord => [3]},
-          {:id => 4, :coord => [5]},
-          {:id => 5, :coord => [8]},
-          {:id => 6, :coord => [13]},
-          {:id => 7, :coord => [21]},
-          {:id => 8, :coord => [34]}
-        ]).root.value.must_equal({:id => 4, :coord => [5]})
+          {:id => 1, :point => [1]},
+          {:id => 2, :point => [2]},
+          {:id => 3, :point => [3]},
+          {:id => 4, :point => [5]},
+          {:id => 5, :point => [8]},
+          {:id => 6, :point => [13]},
+          {:id => 7, :point => [21]},
+          {:id => 8, :point => [34]}
+        ]).root.value.must_equal({:id => 4, :point => [5]})
     end
   end
   
@@ -63,54 +66,107 @@ describe KnnBall do
   end
   
   describe "when asked to find the neareast location" do
+    before :each do
+      json = File.open(File.join(File.dirname(__FILE__), 'data.json'), 'r:utf-8').read
+      @data = JSON.parse(json)
+      @data = @data.map do |l|
+        h = {}
+        l.each {|k,v| h[k.to_sym] = v}
+        h
+      end
+    end
+    
     it "retrieve the nearest location" do
       result = KnnBall.find_knn(@ball_tree, [1, 1, 1, 1])
       result.must_be :kind_of?, Array
     end
     
     it "retrieve the same results as a brute force approach" do
-      json = File.open(File.join(File.dirname(__FILE__), 'data.json'), 'r:utf-8').read
-      data = JSON.parse(json)
-      data = data.map do |l|
-        h = {}
-        l.each {|k,v| h[k.to_sym] = v}
-        h
+      tree = KnnBall.build(@data)
+      msgs = []
+      @data.each do |p|
+        brute_force_result = brute_force(p, @data)
+        p[:point].must_equal(brute_force_result[:point])
+        nn_result = tree.nearest(p[:point])
+        if(nn_result[:point] != brute_force_result[:point])
+          msgs << "For #{p}, #{nn_result} retrieved amongs those 2 first results #{tree.nearest(p[:point], :limit => 2)}"
+        end
       end
-      
-      tree = KnnBall.build(data)
-      errors = []
+      must_be_empty msgs
+    end
+    
+    it "is more efficient than the brute force approach" do
+      tree = KnnBall.build(@data)
       msgs = []
-      data.each do |p|
+      
+      tree.nearest(@data.first[:point])
+      
+      @data.each do |p|
         t0 = Time.now
-        res = data.map do |p2|
-          euc = Math.sqrt((p2[:coord][0] - p[:coord][0])**2.0 + (p2[:coord][1] - p[:coord][1])**2.0)
-          [p2, euc]
-        end
-        best = res.min {|a, b| a.last <=> b.last}
-        brute_force_result = best.first
+        brute_force_result = brute_force(p, @data)
         t1 = Time.now
-        p[:coord].must_equal(brute_force_result[:coord])
+        
         t2 = Time.now
-        nn_result = tree.nearest(p[:coord])
+        nn_result = tree.nearest(p[:point])
         t3 = Time.now
-        if(nn_result[:coord] != brute_force_result[:coord])
-          errors << [p, nn_result, brute_force_result]
-        end
-        if(t1-t0 < t3-t2)
-          msgs << "For #{p}, efficiency was before with bruteforce than with kdtree search."
+        
+        dt_bf = t1-t0
+        dt_kdtree = t3-t2
+        
+        if(dt_bf < dt_kdtree)
+          msgs << "For #{p}, efficiency is better with brute force than with kdtree search. #{((dt_bf - dt_kdtree)/dt_bf * 100).to_i}%"
         end
       end
+      assert( (msgs.count / @data.count) * 100 < 5, msgs.inspect )
+    end
+  end
+  
+  describe "When asked to retrieve the k nearest neighbors" do
+    before :each do
+      json = File.open(File.join(File.dirname(__FILE__), 'data.json'), 'r:utf-8').read
+      @data = JSON.parse(json)
+      @data = @data.map do |l|
+        h = {}
+        l.each {|k,v| h[k.to_sym] = v}
+        h
+      end
       
-      msgs = errors.map do |e| 
-        if(e[0] == e[1])
-          "For #{e[0]}, OK, but brute force retrieved #{e[2]}"
-        elsif(e[0] == e[2])
-          "For #{e[0]}, #{e[1]} retrieved instead of #{e[2]}"
-        else
-          "For #{e[0]}, both brute force and nn search are wrong"
-        end
+      assert @data.count > 10
+      
+      @index = KnnBall.build(@data)
+      assert @index.count > 10
+    end
+    
+    it "retrieve an array of results" do
+      result = @index.nearest([46.23, 5.46], :limit => 10)
+      result.kind_of?(Array).must_equal true
+    end
+    
+    it "should contains 10 results" do
+      result = @index.nearest([46.23, 5.46], :limit => 10)
+      result.size.must_equal 10
+    end
+    
+    it "should contains results from the nearer to the farest" do
+      target = [46.18612, 6.118075]
+      results = @index.nearest(target, :limit => 10)
+      results.reduce do |r0, r1|
+        p0, p1 = r0[:point], r1[:point]
+        
+        d0, d1 = Math.sqrt((p0[0] - target[0]) ** 2 + (p0[1] - target[1]) ** 2), Math.sqrt((p1[0] - target[0]) ** 2 + (p1[1] - target[1]) ** 2)
+        (d0 <= d1).must_equal(true, "#{d0} <= #{d1} should have been true")
+        r1
+      end
+    end
+    
+    it "retrieve the same results as a brute force approach" do
+      msgs = []
+      @data.each do |p|
+        brute_force_result = brute_force(p, @data, 10)
+        nn_result = @index.nearest(p[:point], :limit => 10)
+        (nn_result.map{|r| r[:point]}).must_equal(brute_force_result.map{|r| r[:point]})
       end
-      must_be_empty errors
+      must_be_empty(msgs)
     end
   end
 end

data/test/specs/result_set_spec.rb

@@ -0,0 +1,158 @@
+# encoding: UTF-8
+
+# Copyright (C) 2011 Olivier Amblet <http://olivier.amblet.net>
+#
+# knnball is freely distributable under the terms of an MIT license.
+# See LICENSE or http://www.opensource.org/licenses/mit-license.php.
+
+require 'minitest/autorun'
+require 'knnball'
+
+module KnnBall
+  
+  describe ResultSet do
+    
+    describe "default state" do
+      
+      before :each do
+        @rs = ResultSet.new
+      end
+      
+      it "has a 10 items limit" do
+        assert_equal 10, @rs.limit
+      end
+      
+      it "has no barrier value" do
+        assert_nil @rs.barrier_value
+      end
+      
+      it "has an empty items array" do
+        assert_equal [], @rs.items
+      end
+      
+      it "accept any value" do
+        @rs.eligible? 12
+      end
+    end
+    
+    describe "fix the limit" do
+      
+      before :each do
+        @rs = ResultSet.new :limit => 1
+      end
+      
+      it "has a 1 items limit" do
+        assert_equal 1, @rs.limit
+      end
+      
+      it "has no barrier value" do
+        assert_nil @rs.barrier_value
+      end
+      
+      it "has an empty items array" do
+        assert_equal [], @rs.items
+      end
+      
+      it "accept any value" do
+        assert @rs.eligible?(12)
+      end
+      
+      it "accept only one value" do
+        assert @rs.add(12, '12')
+        assert ! @rs.eligible?(13)
+        assert @rs.eligible?(2)
+        assert @rs.add(2, '2')
+        assert_equal ['2'], @rs.items
+      end
+    end
+    
+    
+    describe "first value" do
+      before :each do
+        @rs = ResultSet.new
+        @rs.add(2, 'AA')
+      end
+      
+      it "set its barrier value to the first added value" do
+        assert_equal 2, @rs.barrier_value
+      end
+      
+      it "add the item to the item list" do
+        assert_equal ['AA'], @rs.items
+      end
+      
+      it "accept any value" do
+        @rs.eligible? 12
+      end
+    end
+    
+    describe "up to the limit" do
+      before :each do
+        @rs = ResultSet.new
+        @rs.add(5, '5')
+        @rs.add(2, '2')
+        @rs.add(10, '10')
+        @rs.add(5, '5')
+        @rs.add(3, '3')
+        @rs.add(4, '4')
+        @rs.add(5, '5')
+        @rs.add(1, '1')
+        @rs.add(5, '5')
+        @rs.add(5, '5')
+      end
+      
+      it "set its barrier value to the first added value" do
+        assert_equal 10, @rs.barrier_value
+      end
+      
+      it "add the item to the item list" do
+        assert_equal ['1', '2', '3', '4', '5', '5', '5', '5', '5', '10'], @rs.items
+      end
+      
+      it "successfuly add an item that should replace the last one" do
+        @rs.add(9, '9')
+        assert_equal ['1', '2', '3', '4', '5', '5', '5', '5', '5', '9'], @rs.items
+      end
+    end
+    
+    describe "break the limit" do
+      before :each do
+        @rs = ResultSet.new
+        @rs.add(5, '5')
+        @rs.add(2, '2')
+        @rs.add(10, '10')
+        @rs.add(5, '5')
+        @rs.add(3, '3')
+        @rs.add(4, '4')
+        @rs.add(5, '5')
+        @rs.add(1, '1')
+        @rs.add(5, '5')
+        @rs.add(5, '5')
+        
+        @rs.add(11, '11')
+        @rs.add(-1, '-1')
+        @rs.add(6, '6')
+        @rs.add(4, '4')
+        @rs.add(0, '0')
+      end
+      
+      it "set its barrier value to the first added value" do
+        assert_equal 5, @rs.barrier_value
+      end
+      
+      it "add the item below the limit to the item list" do
+        assert_equal ['-1', '0', '1', '2', '3', '4', '4', '5', '5', '5'], @rs.items
+      end
+      
+      it "refuse big values" do
+        assert ! @rs.eligible?(12)
+        assert ! @rs.eligible?(5)
+      end
+      
+      it "accept smaller value" do
+        assert @rs.eligible? -2
+        assert @rs.eligible? 4
+      end
+    end
+  end
+end

data/test/specs/spec_helpers.rb

@@ -0,0 +1,18 @@
+module KnnBall
+  module SpecHelpers
+    
+    def brute_force(point, data, count=1)
+      res = data.map do |p2|
+        euc = Math.sqrt((p2[:point][0] - point[:point][0])**2.0 + (p2[:point][1] - point[:point][1])**2.0)
+        [p2, euc]
+      end
+      results = res.sort {|a, b| a.last <=> b.last}[0..9].map{|r| r.first}
+      
+      if(count == 1)
+        results.first
+      else
+        results[0..count-1]
+      end
+    end
+  end
+end

data/test/units/stat_test.rb

@@ -50,8 +50,8 @@ module KnnBall
     end
     
     def test_median_with_hash
-      data = [{:coord => [1]}, {:coord => [2]}, {:coord => [3]}]
-      assert_equal({:coord => [2]}, Stat.median!(data){|a,b| a[:coord] <=> b[:coord]}, data.inspect)
+      data = [{:point => [1]}, {:point => [2]}, {:point => [3]}]
+      assert_equal({:point => [2]}, Stat.median!(data){|a,b| a[:point] <=> b[:point]}, data.inspect)
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: knnball
 version: !ruby/object:Gem::Version
-  version: 0.0.5
+  version: 0.0.6
   prerelease: 
 platform: ruby
 authors:
@@ -9,10 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2011-05-23 00:00:00.000000000 +02:00
+date: 2011-09-09 00:00:00.000000000 +02:00
 default_executable: 
 dependencies: []
-description: Implements K-Nearest Neighbor algorithm using a KDTree in Ruby.
+description: Implements K-Nearest Neighbor algorithm using a KDTree in Ruby. Usefull
+  for sorting geolocation or any other multi-dimensional data.
 email: olivier@amblet.net
 executables: []
 extensions: []
@@ -28,10 +29,13 @@ files:
 - lib/knnball/ball.rb
 - lib/knnball/stat.rb
 - lib/knnball/kdtree.rb
+- lib/knnball/result_set.rb
 - test/specs/ball_spec.rb
 - test/specs/data.json
 - test/specs/kdtree_spec.rb
 - test/specs/knnball_spec.rb
+- test/specs/result_set_spec.rb
+- test/specs/spec_helpers.rb
 - test/units/stat_test.rb
 has_rdoc: true
 homepage: http://github.com/oliamb/knnball
@@ -58,5 +62,5 @@ rubyforge_project: knnball
 rubygems_version: 1.6.2
 signing_key: 
 specification_version: 1
-summary: K-Nearest Neighbor queries using a KDTree
+summary: Multi-dimensional nearest neighbor search
 test_files: []