knnball 0.0.5

data/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2011 Olivier Amblet
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,76 @@
+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.
+
+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.
+
+In this library, each point is associated to a value,
+this way the library acts as an index for multidimensional data like
+geolocation for example.
+
+
+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]},
+    	# ...
+    ]
+
+    index = KnnBall.build(data)
+    
+    result = index.nearest([3.43353, 52.34355])
+    puts result # --> {:id=>2, :coord=>[3.34444, 53.23259]}
+
+Some notes about the above:
+
+*data* must 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.
+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
+use this tree without having to deal with homemade classes,
+you might avoid a lot of conversion code this way. In the example
+above, we added an :id key but you are not limited to that, you can
+use any keys you want beyond the coord key. Keep in mind that the more
+you put in this Hash, the more memory you will consume.
+
+*index* is an instance of KnnBall::KDTree. The library rely on a k-dimensions
+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*.
+
+
+Roadmap
+-------
+
+* Retrieve the k-nearest neighbors of a point instead of just one.
+* Export and load using JSON
+* Support the addition of new values
+* Rebuild the tree
+
+
+References
+----------
+
+This code was written with the help of the following ressources:
+
+* Alorithms In a Nutshell ; George T. Heinemann, Gary Pollice & Stanley Selkow ; O'Reilly (chapter 4 and 9)
+* Python SciPy kdnn module: http://scikit-learn.sourceforge.net/modules/neighbors.html
+* Five Balltree Construction Algorithms, by Stephen M. Omohundro,  http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.91.8209&rep=rep1&type=pdf
+
+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.

data/Rakefile

@@ -0,0 +1,6 @@
+require 'rake/testtask'
+
+Rake::TestTask.new do |tt|
+  tt.test_files = FileList['test/specs/*_spec.rb', 'test/units/*_test.rb']
+  tt.verbose = true
+end

data/knnball.gemspec

@@ -0,0 +1,42 @@
+Gem::Specification.new do |s|
+  s.specification_version = 1 if s.respond_to? :specification_version=
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.rubygems_version = '1.3.5'
+
+  s.name = 'knnball'
+  s.version = '0.0.5'
+  s.date = '2011-05-23'
+  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.authors = ["Olivier Amblet"]
+  s.email = 'olivier@amblet.net'
+  s.homepage = 'http://github.com/oliamb/knnball'
+
+  s.require_paths = %w[lib]
+
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.extra_rdoc_files = %w[README.md LICENSE]
+
+  # = MANIFEST =
+  s.files = %w[
+LICENSE
+README.md
+Rakefile
+knnball.gemspec
+lib/knnball.rb
+lib/knnball/ball.rb
+lib/knnball/stat.rb
+lib/knnball/kdtree.rb
+test/specs/ball_spec.rb
+test/specs/data.json
+test/specs/kdtree_spec.rb
+test/specs/knnball_spec.rb
+test/units/stat_test.rb
+]
+  # = MANIFEST =
+
+  s.test_files = s.files.select { |path| path =~ /^test\/units\/\.*_test\.rb|test\/specs\/\.*_spec\.rb/ }
+end

data/lib/knnball/ball.rb

@@ -0,0 +1,114 @@
+# 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 Ball
+    attr_accessor :left, :right, :value, :dimension
+    
+    # @param value the value associated to this ball
+    # @param actual_dimension the dimension used for sorting left and right tree
+    def initialize(value, dimension = 1, left = nil, right = nil)
+      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}")
+      end
+      @value = value
+      @right = right
+      @dimension = dimension
+      @left = left
+    end
+    
+    def center
+      value[:coord]
+    end
+    
+    def nearest(target, min)
+      result = nil
+      d = [distance(target), min[0]].min
+      if d < min[0]
+        min[0] = d
+        result = self
+      end
+      
+      # determine if we need to dive into sub tree
+      dp = (center[dimension-1] - target[dimension-1]).abs
+      new_result = nil
+      if(dp < min[0])
+        # must dive into both left and right
+        unless(left.nil?)
+          new_result = left.nearest(target, min)
+          result = new_result unless new_result.nil?
+        end
+        unless right.nil?
+          new_result = right.nearest(target, min)
+          result = new_result unless new_result.nil?
+        end
+      else
+        # only need to dive in one
+        if(target[dimension-1] < center[dimension-1])
+          unless(left.nil?)
+            new_result = left.nearest(target, min)
+          end
+        else
+          unless(right.nil?)
+            new_result = right.nearest(target, min)
+          end
+        end
+        result = new_result unless new_result.nil?
+      end
+      return result
+    end
+    
+    # Compute euclidien distance.
+    #
+    # @param coordinates an array of coord or a Ball instance
+    def distance(coordinates)
+      coordinates = coordinates.center if coordinates.respond_to?(:center)
+      Math.sqrt([center, coordinates].transpose.map {|a,b| (b - a)**2}.reduce {|d1,d2| d1 + d2})
+    end
+    
+    # Retrieve true if this is a leaf ball.
+    #
+    # A leaf ball has no sub_balls.
+    def leaf?
+      @left.nil? && @right.nil?
+    end
+    
+    # Generate an Array from this Ball.
+    #
+    # index 0 contains the value object,
+    # index 1 contains the left ball or nil,
+    # index 2 contains the right ball or nil.
+    def to_a
+      if leaf?
+        [@value, nil, nil]
+      else
+        [@value, (@left.nil? ? nil : @left.to_a), (@right.nil? ? nil : @right.to_a)]
+      end
+    end
+    
+    # Generate a Hash from this Ball instance.
+    # 
+    # The generated instance contains keys :id, :left and :right
+    def to_h
+      if leaf?
+        {:value => @value, :left => nil, :right => nil} 
+      else
+        {:value => @value, :left => (@left.nil? ? nil : @left.to_h), :right => (@right.nil? ? nil : @right.to_h)}
+      end
+    end
+  end
+end

data/lib/knnball/kdtree.rb

@@ -0,0 +1,90 @@
+# 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
+  
+  # KD-Tree implementation
+  class KDTree
+    attr_accessor :root
+    
+    def initialize(root = nil)
+      @root = root
+    end
+    
+    def nearest(coord, &cmp_block)
+      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)
+      
+      # 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
+    end
+    
+    # Retrieve the parent to which this coord should belongs to
+    def parent(coord)
+      current = root
+      idx = current.dimension-1
+      result = nil
+      while(result.nil?)
+        if(coord[idx] <= current.center[idx])
+          if current.left.nil?
+            result = current 
+          else
+            current = current.left
+          end
+        else
+          if current.right.nil?
+            result = current 
+          else
+            current = current.right
+          end
+        end
+        idx = current.dimension-1
+      end
+      return result
+    end
+    
+    def empty?
+      root.nil?
+    end
+    
+    def to_a
+      return root.to_a
+    end
+    
+    def each(&proc)
+      raise "tree is nil" if @root.nil?
+      each_ball(@root, &proc)
+    end
+    
+    def map(&proc)
+      res = []
+      self.each {|b| res << yield(b) }
+      return res
+    end
+    
+    private
+    
+    def each_ball(b, &proc)
+      return if b.nil?
+      
+      yield(b)
+      each_ball(b.left, &proc) unless (b.left.nil?)
+      each_ball(b.right, &proc) unless (b.right.nil?)
+      return
+    end
+  end 
+end

data/lib/knnball/stat.rb

@@ -0,0 +1,60 @@
+# 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
+  module Stat
+    
+    # sort an array with the goal of having the median at the middle.
+    #
+    # Values on the left will be lesser or equal to the median and
+    # values on the right higher than or equal to the median.
+    def self.median!(data, &cmp_block)
+      midx = median_index(data)
+      left = 0
+      right = data.size-1
+      pidx = pivot!(data, midx, 0, data.size-1, &cmp_block)
+      while pidx != midx do
+        if(pidx < midx)
+          left = pidx + 1
+        else
+          right = pidx - 1
+        end
+        pidx = pivot!(data, midx, left, right, &cmp_block)
+      end
+      return data[midx]
+    end
+    
+    # @param data an array of data that will be changed in place
+    # @param pivot index of the pivot value in data
+    # @return the final index of the pivot
+    def self.pivot!(data, pivot, left = 0, right = data.size-1, &cmp_block)
+      value = data[pivot]
+      cmp_block = Proc.new {|a, b| a <=> b} if cmp_block.nil?
+      
+      # push pivot value at the end of data
+      data[pivot], data[right] = data[right], data[pivot]
+      
+      # swap position if current idx <= pivot value
+      for i in (left..right-1)
+        if(cmp_block.call(data[i], value) < 1)
+          data[left], data[i] = data[i], data[left]
+          left = left + 1
+        end
+      end
+      
+      # push the pivot value just after the last index
+      data[left], data[right] = data[right], data[left]
+      return left
+    end
+    
+    def self.median_index(data)
+      (data.size % 2 == 0) ? (data.size - 1)/ 2 : data.size / 2
+    end
+  end
+end

data/lib/knnball.rb

@@ -0,0 +1,79 @@
+# 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.
+
+
+
+# This module is used as namespace for every elements of
+# the knnball library.
+module KnnBall
+  
+  autoload :Ball, 'knnball/ball'
+  autoload :Stat, 'knnball/stat'
+  autoload :KDTree, 'knnball/kdtree'
+  
+  # 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]} ]
+  #
+  # @param data an array of Hash containing :value and :coord 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
+    kdtree = KDTree.new(max_dimension)
+    kdtree.root = generate(data, max_dimension)
+    return kdtree
+  end
+  
+  # Generate the KD-Tree hyperrectangle.
+  #
+  # @param actual_dimension the dimension to base comparison on
+  # @param max_dimension the number of dimension of each points
+  # @param data the list of all points
+  # @param left the first data index to look for
+  # @param right the last data index to look for
+  def self.generate(data, max_dimension, actual_dimension = 1)
+    return nil if data.nil?
+    return Ball.new(data.first) if data.size == 1
+    
+    # Order the array such as the middle point is the median and 
+    # that every point on the left are of lesser value than median
+    # 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]}
+    ball = Ball.new(value)
+    
+    actual_dimension = (max_dimension == actual_dimension ? 1 : actual_dimension)
+    
+    ball.left = generate(data[0..(median_idx-1)], max_dimension, actual_dimension) if median_idx > 0
+    ball.right = generate(data[(median_idx+1)..-1], max_dimension, actual_dimension) if median_idx < (data.count)
+    return ball
+  end
+  
+  # Retrieve an internal string representation of the index
+  # that can then be persisted.
+  def self.marshall(ball_tree)
+    return ""
+  end
+  
+  # Retrieve a BallTree instance from a previously marshalled instance.
+  def self.unmarshall(marshalled_content)
+    return KDTree.new
+  end
+  
+  # Retrieve the k nearest neighbor of the given position.
+  def self.find_knn(ball_tree, position, k = 1, options = Hash.new)
+    return []
+  end
+end

data/test/specs/ball_spec.rb

@@ -0,0 +1,101 @@
+# 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 Ball do
+          
+    describe "Leaf balls" do
+      before :each do
+        @value = {:id => 1, :coord => [1,2,3]}
+        @ball = Ball.new(@value)
+      end
+      
+      it "must be a leaf" do
+        @ball.leaf?.must_equal true
+      end
+      
+      it "must have a center equals to the value location" do
+        @ball.center.must_equal @value[:coord]
+      end
+      
+      it "must convert itself to an Array instance" do
+        @ball.to_a.must_equal [@value, nil, nil]
+      end
+      
+      it "must convert itself to a Hash instance" do
+        @ball.to_h.must_equal({:value => @value, :left => nil, :right => nil})
+      end
+    end
+    
+    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]}))
+      end
+      
+      it "wont be a leaf" do
+        @ball.leaf?.must_equal false
+      end
+      
+      it "must_be_centered_at_the_ball_value_location" do
+        @ball.center.must_equal @value[:coord]
+      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]
+        ])
+      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}
+        })
+      end
+    end
+    
+    describe "Ball with sub-balls" do
+      before :each do
+        @value = {:id => 1, :coord => [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)
+      end
+      
+      it "must be centered at (0,0,0)" do
+        @ball.center.must_equal([0,0,0])
+      end
+    end
+    
+    describe "distance from private method" do
+      before :each do
+        # Make private method public (white box testing)
+        Ball.send(:public, *Ball.private_instance_methods)  
+      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.distance(b2).must_equal(Math.sqrt(115))
+      end
+    end
+  end
+end

data/test/specs/data.json

@@ -0,0 +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]}]

data/test/specs/kdtree_spec.rb

@@ -0,0 +1,68 @@
+# 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 KDTree do
+    
+    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
+      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]})))
+        )
+        @ball_tree =   KDTree.new(root)
+      end
+      
+      it "return a matching location" do
+        @ball_tree.nearest([3])[:id].must_equal(3)
+      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]})))
+        )
+        @ball_tree =   KDTree.new(@root)
+      end
+      
+      it "return the nearest parent" do
+        @ball_tree.parent([13.2, 4.5]).value[:id].must_equal(8)
+      end
+    end
+    
+    describe "tree to array" do
+      it "Should return an empty array if empty" do
+        KDTree.new().to_a.must_equal []
+      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]
+      end
+    end
+  end
+end

data/test/specs/knnball_spec.rb

@@ -0,0 +1,116 @@
+# 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'
+require 'json'
+
+describe KnnBall do
+  before do
+    @ball_tree = MiniTest::Mock.new
+  end
+  
+  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]}
+      ]).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]}]
+      )
+      tree.root.value.must_equal({:id => 2, :coord => [2]})
+      tree.root.left.value.must_equal({:id => 1, :coord => [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]})
+      
+      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]})
+    end
+  end
+  
+  describe "when asked to serialize the index" do
+    it "must retrieve a string" do
+      KnnBall.marshall(@ball_tree).must_be :kind_of?, String
+    end
+  end
+  
+  describe "when asked to load an index" do
+    it "must retrieve a a BallTree instance" do
+      KnnBall.unmarshall("").must_be :kind_of?, KnnBall::KDTree
+    end
+  end
+  
+  describe "when asked to find the neareast location" do
+    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
+      end
+      
+      tree = KnnBall.build(data)
+      errors = []
+      msgs = []
+      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
+        t1 = Time.now
+        p[:coord].must_equal(brute_force_result[:coord])
+        t2 = Time.now
+        nn_result = tree.nearest(p[:coord])
+        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."
+        end
+      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
+      end
+      must_be_empty errors
+    end
+  end
+end

data/test/units/stat_test.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.
+
+
+
+require 'minitest/autorun'
+require 'knnball'
+
+module KnnBall
+  class StatTest < MiniTest::Unit::TestCase
+    def test_median_index
+      assert_equal(1, Stat.median_index([1] * 3))
+      assert_equal(1, Stat.median_index([1] * 4))
+    end
+    
+    def test_pivot
+      data = [2,3,4,23,1,342,6,34, 2.3,4,-5,-1,2]
+      assert_equal(8, Stat.pivot!(data, 2), data.inspect)
+      assert_equal(4, data[8])
+      data[0..8].each {|v| assert v <= 4}
+      data[9..-1].each {|v| assert v > 4}
+    end
+    
+    def test_pivot_with_comparison_block
+      data = [2,3,4,23,1,342,6,34, 2.3,4,-5,-1,2]
+      assert_equal(5, Stat.pivot!(data, 2){|a,b| b<=>a}, data.inspect)
+      assert_equal(4, data[5])
+      data[0..5].each {|v| assert v >= 4}
+      data[6..-1].each {|v| assert v < 4}
+    end
+    
+    def test_median_with_sorted_value
+      data = [1, 2, 3, 4, 5, 6, 7, 8, 9]
+      assert_equal(5, Stat.median!(data), data.inspect)
+      assert_equal(5, data[4])
+      data[0..4].each {|v| assert v <= 5}
+      data[4..8].each {|v| assert v >= 5}
+    end
+    
+    def test_median_with_unsorted_values
+      data = [1, 5, 3, 2, 7, 3, 4, 5, 6]
+      assert_equal(4, Stat.median!(data), data.inspect)
+      assert_equal(4, data[4], data.inspect)
+      data[0..4].each {|v| assert v <= 4}
+      data[4..8].each {|v| assert v >= 4}      
+    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)
+    end
+  end
+end

metadata

@@ -0,0 +1,62 @@
+--- !ruby/object:Gem::Specification
+name: knnball
+version: !ruby/object:Gem::Version
+  version: 0.0.5
+  prerelease: 
+platform: ruby
+authors:
+- Olivier Amblet
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2011-05-23 00:00:00.000000000 +02:00
+default_executable: 
+dependencies: []
+description: Implements K-Nearest Neighbor algorithm using a KDTree in Ruby.
+email: olivier@amblet.net
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.md
+- LICENSE
+files:
+- LICENSE
+- README.md
+- Rakefile
+- knnball.gemspec
+- lib/knnball.rb
+- lib/knnball/ball.rb
+- lib/knnball/stat.rb
+- lib/knnball/kdtree.rb
+- test/specs/ball_spec.rb
+- test/specs/data.json
+- test/specs/kdtree_spec.rb
+- test/specs/knnball_spec.rb
+- test/units/stat_test.rb
+has_rdoc: true
+homepage: http://github.com/oliamb/knnball
+licenses: []
+post_install_message: 
+rdoc_options:
+- --charset=UTF-8
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: knnball
+rubygems_version: 1.6.2
+signing_key: 
+specification_version: 1
+summary: K-Nearest Neighbor queries using a KDTree
+test_files: []