measurable 0.0.7 → 0.0.8

data/lib/measurable/haversine.rb

@@ -15,57 +15,62 @@ module Measurable
     :meters => EARTH_RADIUS_IN_KILOMETERS * 1000
   }
 
-  # 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
+  module Haversine
 
-    dlat = u[0] - v[0]
-    dlon = u[1] - v[1]
+    # 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
 
-    dlon_rad = dlon * RAD_PER_DEG
-    dlat_rad = dlat * RAD_PER_DEG
+      dlat = u[0] - v[0]
+      dlon = u[1] - v[1]
 
-    lat1_rad = v[0] * RAD_PER_DEG
-    lon1_rad = v[1] * RAD_PER_DEG
+      dlon_rad = dlon * RAD_PER_DEG
+      dlat_rad = dlat * RAD_PER_DEG
 
-    lat2_rad = u[0] * RAD_PER_DEG
-    lon2_rad = u[1] * RAD_PER_DEG
+      lat1_rad = v[0] * RAD_PER_DEG
+      lon1_rad = v[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))
+      lat2_rad = u[0] * RAD_PER_DEG
+      lon2_rad = u[1] * RAD_PER_DEG
 
-    EARTH_RADIUS[unit] * c
+      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))
+
+      EARTH_RADIUS[unit] * c
+    end
   end
-end
+
+  extend Measurable::Haversine
+end

data/lib/measurable/jaccard.rb

@@ -1,62 +1,65 @@
 module Measurable
+  module Jaccard
 
-  # 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.5
-  #
-  # Because |intersection| = |(1)| = 1 and |union| = |(0, 1)| = 2.
-  #
-  # See: http://en.wikipedia.org/wiki/Jaccard_coefficient
-  #
-  # * *Arguments* :
-  #   - +u+ -> Array.
-  #   - +v+ -> Array.
-  # * *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
+    # 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.5
+    #
+    # Because |intersection| = |(1)| = 1 and |union| = |(0, 1)| = 2.
+    #
+    # See: http://en.wikipedia.org/wiki/Jaccard_coefficient
+    #
+    # * *Arguments* :
+    #   - +u+ -> Array.
+    #   - +v+ -> Array.
+    # * *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 & v
-    union = u | v
+      intersection = u & v
+      union = u | v
+      intersection.length.to_f / union.length
+    end
 
-    intersection.length.to_f / union.length
-  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.
+    #   - +v+ -> Array.
+    # * *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
 
-  # 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.
-  #   - +v+ -> Array.
-  # * *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)
+    extend Measurable::Jaccard
   end
 end

data/lib/measurable/kullback_leibler.rb

@@ -0,0 +1,39 @@
+module Measurable
+  module KullbackLeibler
+
+    # call-seq:
+    #     kullback_leibler(p, q) -> Float
+    #
+    # The Kullback-Leibler Divergence between the distributions +p+ and +q+ is
+    # a measure of their dissimilarity. However, it doesn't obey the triangular
+    # inequality and isn't symmetric, thus it isn't a metric.
+    #
+    # It is calculated as follows:
+    #
+    #   KL(p, q) = \sum_{i = q}^{N} p[i] * log(p[i] / q[i])
+    #
+    # With distributions +p+ and +q+ represented as vectors of N elements
+    # summing to 1.0.
+    #
+    # References:
+    # - http://en.wikipedia.org/wiki/Kullback%E2%80%93Leibler_divergence
+    # - Christopher D. Manning and Hinrich Schütze. Foundations of Statistical
+    #   Natural Language Processing.
+    #
+    # * *Arguments*:
+    #   - +p+ -> A probability distribution represented by a n-element Array.
+    #   - +q+ -> A probability distribution represented by a n-element Array.
+    # * *Returns*:
+    #   A measure of the difference between the probability distributions p and q.
+    def kullback_leibler(p, q)
+      # TODO: Change this to a more specific, custom-made exception.
+      raise ArgumentError if p.size != q.size
+
+      p.zip(q).reduce(0.0) do |acc, probs|
+        acc += probs[0] * Math.log(probs[0] / probs[1])
+      end
+    end
+  end
+
+  extend Measurable::KullbackLeibler
+end

data/lib/measurable/maxmin.rb

@@ -1,34 +1,39 @@
 module Measurable
+  module Maxmin
 
-  # 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+ don't match.
-  #
-  def maxmin(u, v)
-    # TODO: Change this to a more specific, custom-made exception.
-    raise ArgumentError if u.size != v.size
+    # 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+ don'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
+      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
 
-    sum_min / sum_max
   end
-end
+
+  extend Measurable::Maxmin
+end

data/lib/measurable/minkowski.rb

@@ -1,28 +1,45 @@
 module Measurable
+  module Minkowski
 
-  # call-seq:
-  #     minkowski(u, v) -> Numeric
-  #
-  # Calculate the sum of the absolute value of the differences between each
-  # coordinate of +u+ and +v+.
-  #
-  # * *Arguments* :
-  #   - +u+ -> An array of Numeric objects.
-  #   - +v+ -> An array of Numeric objects.
-  # * *Returns* :
-  #   - The Minkowski (or L1) distance between +u+ and +v+.
-  # * *Raises* :
-  #   - +ArgumentError+ -> The sizes of +u+ and +v+ don't match.
-  #
-  def minkowski(u, v)
-    # TODO: Change this to a more specific, custom-made exception.
-    raise ArgumentError if u.size != v.size
+    # call-seq:
+    #     minkowski(u, v) -> Numeric
+    #
+    # Calculate the sum of the absolute value of the differences between each
+    # coordinate of +u+ and +v+.
+    #
+    # * *Arguments* :
+    #   - +u+ -> An array of Numeric objects.
+    #   - +v+ -> An array of Numeric objects.
+    # * *Returns* :
+    #   - The Minkowski (or L1) distance between +u+ and +v+.
+    # * *Raises* :
+    #   - +ArgumentError+ -> The sizes of +u+ and +v+ don't match.
+    #
+    def minkowski(u, v)
+      # TODO: Change this to a more specific, custom-made exception.
+      raise ArgumentError if u.size != v.size
 
-    u.zip(v).reduce(0) do |acc, elem|
-      acc += (elem[0] - elem[1]).abs
+      u.zip(v).reduce(0) do |acc, elem|
+        acc += (elem[0] - elem[1]).abs
+      end
+    end
+
+    def self.extended(base) # :nodoc:
+      base.instance_eval do
+        alias :cityblock :minkowski
+        alias :manhattan :minkowski
+      end
+      super
+    end
+
+    def self.included(base) # :nodoc:
+      base.class_eval do
+        alias :cityblock :minkowski
+        alias :manhattan :minkowski
+      end
+      super
     end
   end
 
-  alias :cityblock :minkowski
-  alias :manhattan :minkowski
-end
+  extend Measurable::Minkowski
+end

data/lib/measurable/tanimoto.rb

@@ -1,32 +1,52 @@
+require 'measurable/jaccard'
+
 module Measurable
+  module Tanimoto
+
+    # 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+ don't match.
+    #
+    def tanimoto(u, v)
+      # TODO: Change this to a more specific, custom-made exception.
+      raise ArgumentError if u.size != v.size
 
-  # Tanimoto similarity is the same as Jaccard similarity.
-  alias :tanimoto_similarity :jaccard
+      -Math.log2(jaccard_index(u, v))
+    end
 
-  # 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+ don't match.
-  #
-  def tanimoto(u, v)
-    # TODO: Change this to a more specific, custom-made exception.
-    raise ArgumentError if u.size != v.size
+    def self.extended(base) # :nodoc:
+      # Tanimoto similarity is the same as Jaccard similarity.
+      base.instance_eval do
+        extend Measurable::Jaccard
+        alias :tanimoto_similarity :jaccard
+      end
+      super
+    end
 
-    -Math.log2(jaccard_index(u, v))
+    def self.included(base) # :nodoc:
+      base.class_eval do
+        include Measurable::Jaccard
+        alias :tanimoto_similarity :jaccard
+      end
+      super
+    end
   end
-end
+
+  extend Measurable::Tanimoto
+end