measurable 0.0.4 → 0.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 24f0ca4dbb60cda53bab68a614a171df7e337434
-  data.tar.gz: 8675c8a2e723203f287ce4dac3a6e6237fe2b675
+  metadata.gz: 66337383a6c25685893bb39f7caf5c7f0b40bcff
+  data.tar.gz: 117a22bb28b1d36f14780d3a22bbad7211b279a0
 SHA512:
-  metadata.gz: ff4de5c4fbbe64592a16e7980182a76fa7e3960931d401004f9cebd8e439ea17acf0e16b8a465131b80e832fd560fd97f5fd6e1054f43678ded44d730a4e90c3
-  data.tar.gz: 62396f9fb4208745628848a5447872bb86e407d2b8ec34b15acaae6ac193f8a2c1a63aa68ef69046d5d6080a693c4cfc38bc9f419c697445eb251bb861cc9af4
+  metadata.gz: 0d7aff51213d2f0ca31472d1d5f43b3ce99d58255b9d3d53485b0983e953866a365927734c1852c7040f7c23149455712af6357679e03ff63bf247709ac7e124
+  data.tar.gz: 652066925d87d7d52656f87346c856d34296e4a98662e94a670d72e9612c568dd95bf758314c524501700b21b53484eaaf059e5b5fee315129fb1b0b90a170bd

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    measurable (0.0.4)
+    measurable (0.0.5)
 
 GEM
   remote: http://rubygems.org/

data/README.md

@@ -1,25 +1,32 @@
 # Measurable
 
-This gem encompasses various distance measures. Besides the `Array` class, I also want to support [NMatrix](http://github.com/sciruby/nmatrix)'s `NVector`.
+A gem to test what metric is best for certain kinds of datasets in machine learning.
 
-My objective is to be able to compare different metrics just by changing which method is called. Also, to show how to use NMatrix's C API. I'll create most of the things in pure Ruby first, then the most used operations (or the slowest ones) will be rewritten in C.
+Besides the `Array` class, I also want to support `NVector` (from [NMatrix](http://github.com/sciruby/nmatrix)).
 
-This is a fork of the gem [Distance Measure](https://github.com/reddavis/Distance-Measures), which has a similar objective, but isn't actively maintained and doesn't support NMatrix. Thank you, [reddavis](https://github.com/reddavis). :)
+The distance measures will be created in Ruby first. If I see that it's really too slow, I'll write some methods in C (or Java, for JRuby).
+
+This is a fork of the gem [Distance Measure](https://github.com/reddavis/Distance-Measures), which has a similar objective, but isn't actively maintained and doesn't support NMatrix. Thank you, [@reddavis][reddavis]. :)
 
 ## Install
 
 `gem install measurable`
 
-It only works with Ruby MRI 1.9.3 or 2.0.0. I still want to test it on JRuby, but as its still pure Ruby, it should work correctly there.
+I only tested it with 2.0.0 (yes, yes, travis, I'll do it eventually). I want to support JRuby as well.
+
+## Distance measures
+
+I'm using the term "distance measure" without much concern for the strict mathematical definition of a metric. If the documentation for one of the methods isn't clear about it being or not a metric, please open an issue.
 
-## Distance measures that I want to support for the moment
+The following are the similarity measures supported at the moment:
 
 - Euclidean distance
 - Squared euclidean distance
 - Cosine distance
-- Max-min distance (["K-Means clustering using max-min distance measure"][1])
+- Max-min distance (from ["K-Means clustering using max-min distance measure"][maxmin])
 - Jaccard distance
 - Tanimoto distance
+- Haversine distance
 
 These still need to be implemented:
 
@@ -36,30 +43,42 @@ These still need to be implemented:
 
 ## How to use
 
-This list will be updated as I have time. I'll refactor the existing measures and add some that I'll need in a project.
-
 The API I intend to support is something like this:
 
 ```ruby
 require "measurable"
-	
+
 u = NVector.ones(2)
 v = NVector.zeros(2)
 w = [1, 0]
 x = [2, 2]
 
-Measurable::euclidean(u, v) # => 1.41421
-Measurable::euclidean(w, v) # => 1.00000
-Measurable::euclidean(w, w) # => 0.00000
-Measurable::
+# Calculate the distance between two points in space.
+Measurable.euclidean(u, v) # => 1.41421
+Measurable.euclidean(w, v) # => 1.00000
+Measurable.cosine([1, 2], [2, 3]) # => 0.00772
+
+# Calculate the norm of a vector, i.e. its distance from the origin.
+Measurable.euclidean_squared([3, 4]) # => 25
 ```
 
-Maybe add support for (some of) NMatrix's dtypes, like `:float32`, `:float64`, `:complex64`, `:complex128`, etc. This will have to way until Measurable supports NMatrix C API.
+## Documentation
+
+`RDoc` syntax is used to document the project. To build it locally, you'll need to install the [Fivefish generator](https://github.com/ged/rdoc-generator-fivefish) (`gem install rdoc-generator-fivefish`) and run the following command:
+
+```bash
+rdoc -f fivefish -m README.md *.md LICENSE lib/
+```
+
+I want to be able to use a Rake task to generate the documentation, thus allowing me to forget the specific command. However, there's a bug in `RDoc::Task` in which [custom generators (like Fivefish) can't be used](https://github.com/rdoc/rdoc/issues/246).
+
+If there's something wrong with an explanation or if there's information missing, please open an issue or send a pull request.
 
 ## License
 
 See LICENSE for details.
 
-The original `Distance Measure` gem is copyrighted by @reddavis.
+The original `distance_measures` gem is copyrighted by [@reddavis][reddavis].
 
-[1]: http://ieeexplore.ieee.org/stamp/stamp.jsp?arnumber=05156398
+[maxmin]: http://ieeexplore.ieee.org/stamp/stamp.jsp?arnumber=05156398
+[reddavis]: (https://github.com/reddavis)

data/Rakefile

@@ -1,6 +1,7 @@
 require 'rake'
 require 'bundler/gem_tasks'
 require "rspec/core/rake_task"
+# require 'rdoc/task' # See below.
 
 # Setup the necessary gems, specified in the gemspec.
 require 'bundler'
@@ -15,10 +16,22 @@ end
 # Run all the specs.
 RSpec::Core::RakeTask.new(:spec)
 
+# RDoc task isn't working with custom generators, as can be seen in:
+# https://github.com/rdoc/rdoc/issues/246
+#
+# Whenever this issue is fixed, I'll resume using this task.
+#
+# RDoc::Task.new do |rdoc|
+#   rdoc.main = "README.md"
+#   rdoc.rdoc_files.include("README.md", "LICENSE", "lib")
+#   rdoc.generator = "fivefish"
+#   rdoc.external = true
+# end
+
 # Compile task.
 # Rake::ExtensionTask.new do |ext|
-#     ext.name = 'measurable'          
-#     ext.ext_dir = 'ext/measurable' 
+#     ext.name = 'measurable'
+#     ext.ext_dir = 'ext/measurable'
 #     ext.lib_dir = 'lib/'
-#     ext.source_pattern = "**/*.{c, cpp, h}" 
+#     ext.source_pattern = "**/*.{c, cpp, h}"
 # end

data/lib/measurable.rb

@@ -1,47 +1,16 @@
-require 'measurable/version.rb'
+require 'measurable/version'
 
-# Distance measures.
+# Distance measures. The require order is important.
 require 'measurable/euclidean'
 require 'measurable/cosine'
-require 'measurable/tanimoto'
 require 'measurable/jaccard'
+require 'measurable/tanimoto'
 require 'measurable/haversine'
 require 'measurable/maxmin'
 
 module Measurable
-  # PI = 3.1415926535
-  RAD_PER_DEG = 0.017453293  #  PI/180
-  class << self
-    def binary_union(u, v)
-      unions = []
-      u.each_with_index do |n, index|
-        if n == 1 || v[index] == 1
-          unions << 1
-        else
-          unions << 0
-        end
-      end
-
-      unions
-    end
-
-    def binary_intersection(u, v)
-      intersects = []
-      u.each_with_index do |n, index|
-        if n == 1 && v[index] == 1
-          intersects << 1
-        else
-          intersects << 0
-        end
-      end
-
-      intersects
-    end
+  # PI / 180 degrees.
+  RAD_PER_DEG = Math::PI / 180
 
-    # Checks if we"re dealing with NaN"s and will return 0.0 unless
-    # handle NaN"s is set to false
-    def handle_nan(result)
-      result.nan? ? 0.0 : result
-    end
-  end
+  extend self # expose all instance methods as singleton methods.
 end

data/lib/measurable/cosine.rb

@@ -1,10 +1,27 @@
 module Measurable
-  class << self
-    def cosine(u, v)
-      dot_product = dot(u, v)
-      normalization = self.euclidean_normalize * other.euclidean_normalize
 
-      handle_nan(dot_product / normalization)
-    end
+  # call-seq:
+  #     cosine(u, v) -> Float
+  #
+  # Calculate the similarity between the orientation of two vectors.
+  #
+  # See: http://en.wikipedia.org/wiki/Cosine_similarity
+  #
+  # * *Arguments* :
+  #   - +u+ -> An array of Numeric objects.
+  #   - +v+ -> An array of Numeric objects.
+  # * *Returns* :
+  #   - The normalized dot product of +u+ and +v+, that is, the angle between
+  #     them in the n-dimensional space.
+  # * *Raises* :
+  #   - +ArgumentError+ -> The sizes of +u+ and +v+ doesn't match.
+  #
+  def cosine(u, v)
+    # TODO: Change this to a more specific, custom-made exception.
+    raise ArgumentError if u.size != v.size
+
+    dot_product = u.zip(v).reduce(0.0) { |acc, ary| acc += ary[0] * ary[1] }
+
+    dot_product / (euclidean(u) * euclidean(v))
   end
 end

data/lib/measurable/euclidean.rb

@@ -1,40 +1,76 @@
 module Measurable
-  class << self
-    # Add documentation here!
-    def euclidean(u, v = nil)
-      # If the second argument is nil, the method should return the norm of
-      # vector u. For this, we need the distance between u and the origin.
-      if v.nil?
-        v = Array.new(u.size, 0)
-      end
-      
-      # We could make it work with vector of different sizes because of #zip
-      # but it's unreliable. It's better to just throw an exception.
-      # TODO: Change this to a more specific, custom-made exception.
-      raise ArgumentError if u.size != v.size
-      
-      sum = u.zip(v).reduce(0.0) do |acc, ary|
-        acc += (ary[0] - ary[-1])**2
-      end
-    
-      Math.sqrt(sum)
+
+  # call-seq:
+  #     euclidean(u) -> Float
+  #     euclidean(u, v) -> Float
+  #
+  # Calculate the ordinary distance between arrays +u+ and +v+.
+  #
+  # If +v+ isn't given, calculate the Euclidean norm of +u+.
+  #
+  # See: http://en.wikipedia.org/wiki/Euclidean_distance#N_dimensions
+  #
+  # * *Arguments* :
+  #   - +u+ -> An array of Numeric objects.
+  #   - +v+ -> (Optional) An array of Numeric objects.
+  # * *Returns* :
+  #   - The euclidean norm of +u+ or the euclidean distance between +u+ and
+  #     +v+.
+  # * *Raises* :
+  #   - +ArgumentError+ -> The sizes of +u+ and +v+ doesn't match.
+  #
+  def euclidean(u, v = nil)
+    # If the second argument is nil, the method should return the norm of
+    # vector u. For this, we need the distance between u and the origin.
+    if v.nil?
+      v = Array.new(u.size, 0)
     end
-  
-    def euclidean_squared(u, v = nil)
-      # If the second argument is nil, the method should return the norm of
-      # vector u. For this, we need the distance between u and the origin.
-      if v.nil?
-        v = Array.new(u.size, 0)
-      end
-      
-      # We could make it work with vector of different sizes because of #zip
-      # but it's unreliable. It's better to just throw an exception.
-      # TODO: Change this to a more specific, custom-made exception.
-      raise ArgumentError if u.size != v.size
-      
-      u.zip(v).reduce(0.0) do |acc, ary|
-        acc += (ary[0] - ary[-1])**2
-      end
+
+    # TODO: Change this to a more specific, custom-made exception.
+    raise ArgumentError if u.size != v.size
+
+    sum = u.zip(v).reduce(0.0) do |acc, ary|
+      acc += (ary[0] - ary[-1]) ** 2
+    end
+
+    Math.sqrt(sum)
+  end
+
+  # call-seq:
+  #     euclidean_squared(u) -> Float
+  #     euclidean_squared(u, v) -> Float
+  #
+  # Calculate the same value as euclidean(u, v), but don't take the square root
+  # of it.
+  #
+  # This isn't a metric in the strict sense, i.e. it doesn't respect the
+  # triangle inequality. However, the squared Euclidean distance is very useful
+  # whenever only the relative values of distances are important, for example
+  # in optimization problems.
+  #
+  # See: http://en.wikipedia.org/wiki/Euclidean_distance#Squared_Euclidean_distance
+  #
+  # * *Arguments* :
+  #   - +u+ -> An array of Numeric objects.
+  #   - +v+ -> (Optional) An array of Numeric objects.
+  # * *Returns* :
+  #   - The squared value of the euclidean norm of +u+ or of the euclidean
+  #     distance between +u+ and +v+.
+  # * *Raises* :
+  #   - +ArgumentError+ -> The sizes of +u+ and +v+ doesn't match.
+  #
+  def euclidean_squared(u, v = nil)
+    # If the second argument is nil, the method should return the norm of
+    # vector u. For this, we need the distance between u and the origin.
+    if v.nil?
+      v = Array.new(u.size, 0)
+    end
+
+    # TODO: Change this to a more specific, custom-made exception.
+    raise ArgumentError if u.size != v.size
+
+    u.zip(v).reduce(0.0) do |acc, ary|
+      acc += (ary[0] - ary[-1]) ** 2
     end
   end
 end

data/lib/measurable/haversine.rb

@@ -1,46 +1,71 @@
-# Notes:
-#
-# translated into Ruby based on information contained in:
-# http://mathforum.org/library/drmath/view/51879.html
-# Dr. Rick and Dr. Peterson - 4/20/99
-#
-# http://www.movable-type.co.uk/scripts/latlong.html
-# http://en.wikipedia.org/wiki/Haversine_formula
-#
-# This formula can compute accurate distances between two points given latitude
-# and longitude, even for short distances.
-
 module Measurable
 
-  R_MILES = 3956     # radius of the great circle in miles
-  R_KM = 6371        # radius in kilometers...some algorithms use 6367
-  
-  # the great circle distance d will be in whatever units R is in
-  R = {
-    :miles => R_MILES,
-    :km => R_KM,
-    :feet => R_MILES * 5282,
-    :meters => R_KM * 1000
+  # Earth radius in miles.
+  EARTH_RADIUS_IN_MILES = 3956
+
+  # Earth radius in kilometers. Some algorithms use 6367.
+  EARTH_RADIUS_IN_KILOMETERS = 6371
+
+  # The great circle distance returned will be in whatever units R is in.
+  # Provides
+  EARTH_RADIUS = {
+    :miles => EARTH_RADIUS_IN_MILES,
+    :km => EARTH_RADIUS_IN_KILOMETERS,
+    :feet => EARTH_RADIUS_IN_MILES * 5282,
+    :meters => EARTH_RADIUS_IN_KILOMETERS * 1000
   }
 
-  class << self
-    def haversine(u, v, um = :meters)
-      dlon = u[1] - v[1]
-      dlat = u[0] - v[0]
+  # call-seq:
+  #     haversine(u, v) -> Float
+  #
+  # Compute accurate distances between two points given their latitudes and
+  # longitudes, even for short distances. This isn't a distance measure in the
+  # same sense as the other methods in +Measurable+.
+  #
+  # The distance returned is the great circle (or orthodromic) distance between
+  # +u+ and +v+, which is the shortest distance between them on the surface of
+  # a sphere. Thus, this implementation considers the Earth to be a sphere.
+  #
+  # Reminding that the input vectors are of the form [latitude, longitude] in
+  # degrees, so if you have the coordinates [23 32' S, 46 37' W] (from São
+  # Paulo), the corresponding vector is [-23.53333, -46.61667].
+  #
+  # References:
+  # - http://www.movable-type.co.uk/scripts/latlong.html
+  # - http://en.wikipedia.org/wiki/Haversine_formula
+  # - http://en.wikipedia.org/wiki/Great-circle_distance
+  #
+  # * *Arguments* :
+  #   - +u+ -> An array of Numeric objects.
+  #   - +v+ -> An array of Numeric objects.
+  #   - +unit+ -> (Optional) A Symbol representing the unit of measure. Available
+  #               options are +:miles+, +:feet+, +:km+ and +:meters+.
+  # * *Returns* :
+  #   - The great circle distance between +u+ and +v+.
+  # * *Raises* :
+  #   - +ArgumentError+ -> The size of +u+ and +v+ must be 2.
+  #   - +ArgumentError+ -> +unit+ must be a Symbol.
+  #
+  def haversine(u, v, unit = :meters)
+    # TODO: Create better exceptions.
+    raise ArgumentError if u.size != 2 || v.size != 2
+    raise ArgumentError if unit.class != Symbol
+
+    dlat = u[0] - v[0]
+    dlon = u[1] - v[1]
 
-      dlon_rad = dlon * RAD_PER_DEG 
-      dlat_rad = dlat * RAD_PER_DEG
+    dlon_rad = dlon * RAD_PER_DEG
+    dlat_rad = dlat * RAD_PER_DEG
 
-      lat1_rad = v[0] * RAD_PER_DEG
-      lon1_rad = v[1] * RAD_PER_DEG
+    lat1_rad = v[0] * RAD_PER_DEG
+    lon1_rad = v[1] * RAD_PER_DEG
 
-      lat2_rad = u[0] * RAD_PER_DEG
-      lon2_rad = u[1] * RAD_PER_DEG
+    lat2_rad = u[0] * RAD_PER_DEG
+    lon2_rad = u[1] * RAD_PER_DEG
 
-      a = (Math.sin(dlat_rad/2))**2 + Math.cos(lat1_rad) * Math.cos(lat2_rad) * (Math.sin(dlon_rad/2))**2
-      c = 2 * Math.atan2( Math.sqrt(a), Math.sqrt(1-a))
+    a = (Math.sin(dlat_rad / 2)) ** 2 + Math.cos(lat1_rad) * Math.cos(lat2_rad) * (Math.sin(dlon_rad / 2)) ** 2
+    c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a))
 
-      R[um] * c
-    end
+    EARTH_RADIUS[unit] * c
   end
 end

data/lib/measurable/jaccard.rb

@@ -1,26 +1,69 @@
-# http://en.wikipedia.org/wiki/Jaccard_coefficient
 module Measurable
-  class << self
-    def jaccard(u, v)
-      1 - jaccard_index(u, v)
+
+  # call-seq:
+  #     jaccard_index(u, v) -> Float
+  #
+  # Give the similarity between two binary vectors +u+ and +v+. Calculated as:
+  #  jaccard_index = |intersection| / |union|
+  #
+  # In which intersection and union refer to +u+ and +v+ and |x| is the
+  # cardinality of set x.
+  #
+  # For example:
+  #   jaccard_index([1, 0, 1], [1, 1, 1]) == 0.666...
+  #
+  # Because |intersection| = |(1, 0, 1)| = 2 and |union| = |(1, 1, 1)| = 3.
+  #
+  # See: http://en.wikipedia.org/wiki/Jaccard_coefficient
+  #
+  # * *Arguments* :
+  #   - +u+ -> Array of 1s and 0s.
+  #   - +v+ -> Array of 1s and 0s.
+  # * *Returns* :
+  #   - Float value representing the Jaccard similarity coefficient between
+  #     +u+ and +v+.
+  # * *Raises* :
+  #   - +ArgumentError+ -> The size of the input arrays doesn't match.
+  #
+  def jaccard_index(u, v)
+    # TODO: Change this to a more specific, custom-made exception.
+    raise ArgumentError if u.size != v.size
+
+    intersection = u.zip(v).reduce(0) do |acc, elem|
+      # Both u and v must have this element.
+      elem[0] + elem[1] == 2 ? (acc + 1) : acc
     end
-  
-    def jaccard_index(u, v)
-      union = (u | v).size.to_f
-      intersection = (u & v).size.to_f
-        
-      intersection / union
-    end
-  
-    def binary_jaccard(u, v)
-      1 - binary_jaccard_index(u, v)
-    end
-  
-    def binary_jaccard_index(u, v)
-      intersection = binary_intersection(u, v).delete_if {|x| x == 0}.size.to_f
-      union = binary_union(u, v).delete_if {|x| x == 0}.size.to_f
-    
-      intersection / union
+
+    union = u.zip(v).reduce(0) do |acc, elem|
+      # One of u and v must have this element.
+      elem[0] + elem[1] >= 1 ? (acc + 1) : acc
     end
+
+    intersection.to_f / union
+  end
+
+  # call-seq:
+  #     jaccard(u, v) -> Float
+  #
+  # The jaccard distance is a measure of dissimilarity between two sets. It is
+  # calculated as:
+  #   jaccard_distance = 1 - jaccard_index
+  #
+  # This is a proper metric, i.e. the following conditions hold:
+  #   - Symmetry:              jaccard(u, v) == jaccard(v, u)
+  #   - Non-negative:          jaccard(u, v) >= 0
+  #   - Coincidence axiom:     jaccard(u, v) == 0 if u == v
+  #   - Triangular inequality: jaccard(u, v) <= jaccard(u, w) + jaccard(w, v)
+  #
+  # * *Arguments* :
+  #   - +u+ -> Array of 1s and 0s.
+  #   - +v+ -> Array of 1s and 0s.
+  # * *Returns* :
+  #   - Float value representing the dissimilarity between +u+ and +v+.
+  # * *Raises* :
+  #   - +ArgumentError+ -> The size of the input arrays doesn't match.
+  #
+  def jaccard(u, v)
+    1 - jaccard_index(u, v)
   end
 end

data/lib/measurable/maxmin.rb

@@ -1,13 +1,34 @@
 module Measurable
-  class << self
-    def maxmin(u, v)
-      sum_min, sum_max = u.zip(v).reduce([0.0, 0.0]) do |acc, attributes|
-        acc[0] += attributes.min
-        acc[-1] += attributes.max
-        acc
-      end
-    
-      sum_min / sum_max
+
+  # call-seq:
+  #     maxmin(u, v) -> Float
+  #
+  # The "Max-min distance" is used to measure similarity between two vectors.
+  #
+  # When used in k-means clustering, this similarity measure can give better
+  # results in some datasets, as pointed out in the paper "K-means clustering
+  # using Max-min distance measure" --- Visalakshi, N. K.; Suguna, J.
+  #
+  # See: http://ieeexplore.ieee.org/stamp/stamp.jsp?arnumber=05156398
+  #
+  # * *Arguments* :
+  #   - +u+ -> An array of Numeric objects.
+  #   - +v+ -> An array of Numeric objects.
+  # * *Returns* :
+  #   - Similarity between +u+ and +v+.
+  # * *Raises* :
+  #   - +ArgumentError+ -> The sizes of +u+ and +v+ doesn't match.
+  #
+  def maxmin(u, v)
+    # TODO: Change this to a more specific, custom-made exception.
+    raise ArgumentError if u.size != v.size
+
+    sum_min, sum_max = u.zip(v).reduce([0.0, 0.0]) do |acc, attributes|
+      acc[0] += attributes.min
+      acc[1] += attributes.max
+      acc
     end
+
+    sum_min / sum_max
   end
 end

data/lib/measurable/tanimoto.rb

@@ -1,11 +1,32 @@
-# http://en.wikipedia.org/wiki/Jaccard_index#Tanimoto_coefficient_.28extended_Jaccard_coefficient.29
 module Measurable
-  class << self
-    def tanimoto(u, v)
-      dot = dot(u, v).to_f
-      result = dot / (u.sum_of_squares + v.sum_of_squares - dot).to_f
-    
-      handle_nan(result)
-    end
+
+  # Tanimoto similarity is the same as Jaccard similarity.
+  alias :tanimoto_similarity :jaccard
+
+  # call-seq:
+  #     tanimoto(u, v) -> Float
+  #
+  # Tanimoto distance is a coefficient explicitly chosen such as to allow for
+  # two dissimilar specimens to be similar to a third one. This breaks the
+  # triangle inequality, thus this isn't a metric.
+  #
+  # More information and references on this are needed. It's left here mostly
+  # as a piece of curiosity.
+  #
+  # See: # http://en.wikipedia.org/wiki/Jaccard_index#Tanimoto.27s_Definitions_of_Similarity_and_Distance
+  #
+  # * *Arguments* :
+  #   - +u+ -> An array of Numeric objects.
+  #   - +v+ -> An array of Numeric objects.
+  # * *Returns* :
+  #   - A measure of the similarity between +u+ and +v+.
+  # * *Raises* :
+  #   - +ArgumentError+ -> The sizes of +u+ and +v+ doesn't match.
+  #
+  def tanimoto(u, v)
+    # TODO: Change this to a more specific, custom-made exception.
+    raise ArgumentError if u.size != v.size
+
+    -Math.log2(jaccard_index(u, v))
   end
 end

data/lib/measurable/version.rb

@@ -1,3 +1,3 @@
 module Measurable
-  VERSION = "0.0.4"
+  VERSION = "0.0.5" # :nodoc:
 end

data/spec/cosine_spec.rb

@@ -0,0 +1,29 @@
+describe "Cosine distance" do
+  
+  before :all do
+    @u = [1, 2]
+    @v = [2, 3]
+    @w = [4, 5]
+  end
+  
+  it "accepts two arguments" do
+    expect { Measurable.cosine(@u, @v) }.to_not raise_error
+    expect { Measurable.cosine(@u, @v, @w) }.to raise_error(ArgumentError)
+  end
+  
+  it "should be symmetric" do
+    x = Measurable.cosine(@u, @v)
+    y = Measurable.cosine(@v, @u)
+
+    x.should be_within(TOLERANCE).of(y)
+  end
+
+  it "should return the correct value" do
+    x = Measurable.cosine(@u, @v)
+    x.should be_within(TOLERANCE).of(0.992277877)
+  end
+
+  it "shouldn't work with vectors of different length" do
+    expect { Measurable.cosine(@u, [1, 3, 5, 7]) }.to raise_error
+  end
+end

data/spec/euclidean_spec.rb

@@ -0,0 +1,61 @@
+describe "Euclidean" do
+  
+  before :all do
+    @u = [1, 3, 16]
+    @v = [1, 4, 16]
+    @w = [4, 5, 6]
+  end
+  
+  context "Distance" do
+    it "accepts two arguments" do
+      expect { Measurable.euclidean(@u, @v) }.to_not raise_error
+      expect { Measurable.euclidean(@u, @v, @w) }.to raise_error(ArgumentError)
+    end
+  
+    it "accepts one argument and returns the vector's norm" do
+      # Remember that 3^2 + 4^2 = 5^2.
+      Measurable.euclidean([3, 4]).should == 5
+    end
+          
+    it "should be symmetric" do
+      Measurable.euclidean(@u, @v).should == Measurable.euclidean(@v, @u)
+    end
+
+    it "should return the correct value" do
+      Measurable.euclidean(@u, @u).should == 0
+      Measurable.euclidean(@u, @v).should == 1
+    end
+  
+    it "shouldn't work with vectors of different length" do
+      expect { Measurable.euclidean(@u, [2, 2, 2, 2]) }.to raise_error
+    end
+  end
+  
+  context "Squared Distance" do
+    it "accepts two arguments" do
+      expect { Measurable.euclidean_squared(@u, @v) }.to_not raise_error
+      expect { Measurable.euclidean_squared(@u, @v, @w) }.to raise_error(ArgumentError)
+    end
+  
+    it "accepts one argument and returns the vector's norm" do
+      # Remember that 3^2 + 4^2 = 5^2.
+      Measurable.euclidean_squared([3, 4]).should == 25
+    end
+          
+    it "should be symmetric" do
+      x = Measurable.euclidean_squared(@u, @v)
+      y = Measurable.euclidean_squared(@v, @u)
+      
+      x.should == y
+    end
+
+    it "should return the correct value" do
+      Measurable.euclidean_squared(@u, @u).should == 0
+      Measurable.euclidean_squared(@u, @v).should == 1
+    end
+  
+    it "shouldn't work with vectors of different length" do
+      expect { Measurable.euclidean_squared(@u, [2, 2, 2, 2]) }.to raise_error
+    end    
+  end
+end

data/spec/haversine_spec.rb

@@ -0,0 +1,37 @@
+describe "Haversine distance" do
+
+  before :all do
+    # We have very big errors in this formula, due to:
+    #   - The Earth is considered a sphere.
+    #   - Earth's radius is considered constant (same as above).
+    #
+    # Given these conditions, I'll just assume the error to be less than 1.
+    # TODO: Calculate better error estimates.
+    @haversine_tolerance = 1
+
+    @u = [ 35.66667, 139.75] # Tokyo: 35 40' N, 139 45' E.
+    @v = [-23.53333, -46.61667] # São Paulo: 23 32' S, 46 37' W.
+  end
+
+  it "accepts two arguments" do
+    expect { Measurable.haversine(@u, @v) }.to_not raise_error
+    expect { Measurable.haversine(@u, @v, [-24.5, 40.23]) }.to raise_error(ArgumentError)
+  end
+
+  it "should be symmetric" do
+    x = Measurable.haversine(@u, @v)
+    y = Measurable.haversine(@v, @u)
+
+    x.should be_within(TOLERANCE).of(y)
+  end
+
+  it "should return the correct value" do
+    x = Measurable.haversine(@u, @v, :km)
+
+    x.should be_within(@haversine_tolerance).of(18533)
+  end
+
+  it "should only work with [lat, long] vectors" do
+    expect { Measurable.haversine([2, 4], [1, 3, 5, 7]) }.to raise_error
+  end
+end

data/spec/jaccard_spec.rb

@@ -0,0 +1,62 @@
+describe "Jaccard" do
+
+  context "Index" do
+    before :all do
+      @u = [1, 0, 1]
+      @v = [1, 1, 1]
+      @w = [0, 1, 0]
+    end
+
+    it "accepts two arguments" do
+      expect { Measurable.jaccard_index(@u, @v) }.to_not raise_error
+      expect { Measurable.jaccard_index(@u, @v, @w) }.to raise_error(ArgumentError)
+    end
+
+    it "should be symmetric" do
+      x = Measurable.jaccard_index(@u, @v)
+      y = Measurable.jaccard_index(@v, @u)
+
+      x.should be_within(TOLERANCE).of(y)
+    end
+
+    it "should return the correct value" do
+      x = Measurable.jaccard_index(@u, @v)
+
+      x.should be_within(TOLERANCE).of(2.0 / 3.0)
+    end
+
+    it "shouldn't work with vectors of different length" do
+      expect { Measurable.jaccard_index(@u, [1, 2, 3, 4]) }.to raise_error
+    end
+  end
+
+  context "Distance" do
+    before :all do
+      @u = [1, 0, 1]
+      @v = [1, 1, 1]
+      @w = [0, 1, 0]
+    end
+
+    it "accepts two arguments" do
+      expect { Measurable.jaccard(@u, @v) }.to_not raise_error
+      expect { Measurable.jaccard(@u, @v, @w) }.to raise_error(ArgumentError)
+    end
+
+    it "should be symmetric" do
+      x = Measurable.jaccard(@u, @v)
+      y = Measurable.jaccard(@v, @u)
+
+      x.should be_within(TOLERANCE).of(y)
+    end
+
+    it "should return the correct value" do
+      x = Measurable.jaccard(@u, @v)
+
+      x.should be_within(TOLERANCE).of(1.0 / 3.0)
+    end
+
+    it "shouldn't work with vectors of different length" do
+      expect { Measurable.jaccard(@u, [1, 2, 3, 4]) }.to raise_error
+    end
+  end
+end

data/spec/maxmin_spec.rb

@@ -0,0 +1,30 @@
+describe "Max-min distance" do
+
+  before :all do
+    @u = [1, 3, 16]
+    @v = [1, 4, 16]
+    @w = [4, 5, 6]
+  end
+
+  it "accepts two arguments" do
+    expect { Measurable.maxmin(@u, @v) }.to_not raise_error
+    expect { Measurable.maxmin(@u, @v, @w) }.to raise_error(ArgumentError)
+  end
+
+  it "should be symmetric" do
+    x = Measurable.maxmin(@u, @v)
+    y = Measurable.maxmin(@v, @u)
+
+    x.should be_within(TOLERANCE).of(y)
+  end
+
+  it "should return the correct value" do
+    x = Measurable.maxmin(@u, @v)
+
+    x.should be_within(TOLERANCE).of(0.9523809523)
+  end
+
+  it "shouldn't work with vectors of different length" do
+    expect { Measurable.maxmin(@u, [1, 3, 5, 7]) }.to raise_error
+  end
+end

data/spec/spec_helper.rb

@@ -2,3 +2,5 @@ $LOAD_PATH.unshift(File.dirname(__FILE__))
 $LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
 
 require 'measurable'
+
+TOLERANCE = 10e-9

data/spec/tanimoto_spec.rb

@@ -0,0 +1,30 @@
+describe "Tanimoto distance" do
+
+  before :all do
+    @u = [1, 0, 1]
+    @v = [1, 1, 1]
+    @w = [0, 1, 0]
+  end
+
+  it "accepts two arguments" do
+    expect { Measurable.tanimoto(@u, @v) }.to_not raise_error
+    expect { Measurable.tanimoto(@u, @v, @w) }.to raise_error(ArgumentError)
+  end
+
+  it "should be symmetric" do
+    x = Measurable.tanimoto(@u, @v)
+    y = Measurable.tanimoto(@v, @u)
+
+    x.should be_within(TOLERANCE).of(y)
+  end
+
+  it "should return the correct value" do
+    x = Measurable.tanimoto(@u, @v)
+
+    x.should be_within(TOLERANCE).of(-Math.log2(2.0 / 3.0))
+  end
+
+  it "shouldn't work with vectors of different length" do
+    expect { Measurable.tanimoto(@u, [1, 3, 5, 7]) }.to raise_error
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: measurable
 version: !ruby/object:Gem::Version
-  version: 0.0.4
+  version: 0.0.5
 platform: ruby
 authors:
 - Carlos Agarie
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-03-24 00:00:00.000000000 Z
+date: 2013-07-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -74,8 +74,13 @@ files:
 - lib/measurable/tanimoto.rb
 - lib/measurable/version.rb
 - measurable.gemspec
-- spec/measurable_spec.rb
+- spec/cosine_spec.rb
+- spec/euclidean_spec.rb
+- spec/haversine_spec.rb
+- spec/jaccard_spec.rb
+- spec/maxmin_spec.rb
 - spec/spec_helper.rb
+- spec/tanimoto_spec.rb
 homepage: http://github.com/agarie/measurable
 licenses: []
 metadata: {}
@@ -95,10 +100,15 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.0.0
+rubygems_version: 2.0.3
 signing_key: 
 specification_version: 4
 summary: A Ruby gem with a lot of distance measures for your projects.
 test_files:
-- spec/measurable_spec.rb
+- spec/cosine_spec.rb
+- spec/euclidean_spec.rb
+- spec/haversine_spec.rb
+- spec/jaccard_spec.rb
+- spec/maxmin_spec.rb
 - spec/spec_helper.rb
+- spec/tanimoto_spec.rb

data/spec/measurable_spec.rb

@@ -1,159 +0,0 @@
-describe Measurable do
-
-  describe "Binary union" do
-    
-  end
-
-  describe "Binary intersection" do
-    
-  end
-
-  describe "Euclidean" do
-    
-    before :all do
-      @u = [1, 3, 16]
-      @v = [1, 4, 16]
-      @w = [4, 5, 6]
-    end
-    
-    context "Distance" do
-      it "accepts two arguments" do
-        expect { Measurable.euclidean(@u, @v) }.to_not raise_error
-        expect { Measurable.euclidean(@u, @v, @w) }.to raise_error(ArgumentError)
-      end
-    
-      it "accepts one argument and returns the vector's norm" do
-        # Remember that 3^2 + 4^2 = 5^2.
-        Measurable.euclidean([3, 4]).should == 5
-      end
-            
-      it "should be symmetric" do
-        Measurable.euclidean(@u, @v).should == Measurable.euclidean(@v, @u)
-      end
-
-      it "should return the correct value" do
-        Measurable.euclidean(@u, @u).should == 0
-        Measurable.euclidean(@u, @v).should == 1
-      end
-    
-      it "shouldn't work with vectors of different length" do
-        expect { Measurable.euclidean(@u, [2, 2, 2, 2]) }.to raise_error
-      end
-    end
-    
-    context "Squared Distance" do
-      it "accepts two arguments" do
-        expect { Measurable.euclidean_squared(@u, @v) }.to_not raise_error
-        expect { Measurable.euclidean_squared(@u, @v, @w) }.to raise_error(ArgumentError)
-      end
-    
-      it "accepts one argument and returns the vector's norm" do
-        # Remember that 3^2 + 4^2 = 5^2.
-        Measurable.euclidean_squared([3, 4]).should == 25
-      end
-            
-      it "should be symmetric" do
-        x = Measurable.euclidean_squared(@u, @v)
-        y = Measurable.euclidean_squared(@v, @u)
-        
-        x.should == y
-      end
-
-      it "should return the correct value" do
-        Measurable.euclidean_squared(@u, @u).should == 0
-        Measurable.euclidean_squared(@u, @v).should == 1
-      end
-    
-      it "shouldn't work with vectors of different length" do
-        expect { Measurable.euclidean_squared(@u, [2, 2, 2, 2]) }.to raise_error
-      end    
-    end
-    
-  end
-
-  describe "Cosine distance" do
-    it "accepts two arguments"
-    
-    it "accepts one argument and returns the vector's norm"
-    
-    it "should handle NaN's"
-    
-    it "should be symmetric"
-
-    it "should return the correct value"
-
-    it "shouldn't work with vectors of different length"
-  end
-    
-  describe "Chebyshev distance" do
-    it "accepts two arguments"
-    
-    it "accepts one argument and returns the vector's norm"
-        
-    it "should be symmetric"
-
-    it "should return the correct value"
-    
-    it "shouldn't work with vectors of different length"
-  end
-  
-  describe "Tanimoto distance" do
-    it "accepts two arguments"
-    
-    it "accepts one argument and returns the vector's norm"
-        
-    it "should be symmetric"
-
-    it "should return the correct value"
-    
-    it "shouldn't work with vectors of different length"    
-  end
-
-  describe "Haversine distance" do
-    it "accepts two arguments"
-    
-    it "accepts one argument and returns the vector's norm"
-        
-    it "should be symmetric"
-
-    it "should return the correct value"
-    
-    it "shouldn't work with vectors of different length"
-  end
-  
-  describe "Jaccard distance" do
-    it "accepts two arguments"
-    
-    it "accepts one argument and returns the vector's norm"
-        
-    it "should be symmetric"
-
-    it "should return the correct value"
-    
-    it "shouldn't work with vectors of different length"
-  end
-  
-  describe "Binary Jaccard distance" do
-    it "accepts two arguments"
-    
-    it "accepts one argument and returns the vector's norm"
-        
-    it "should be symmetric"
-
-    it "should return the correct value"
-    
-    it "shouldn't work with vectors of different length"
-  end
-  
-  describe "Max-min distance" do
-    it "accepts two arguments"
-    
-    it "accepts one argument and returns the vector's norm"
-    
-    it "should be symmetric"
-
-    it "should return the correct value"
-
-    it "shouldn't work with vectors of different length"
-  end
-end