measurable 0.0.7 → 0.0.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: aaf11caa585477217fa9724f7f8c8a794490194f
-  data.tar.gz: 2e802d508407c4b656501c9a18af5130ae488979
+  metadata.gz: ef813e1fecb8d7f5a5a19cf70018b3965ea34790
+  data.tar.gz: 23489086e5091bff9a868e6d167cd2b77210b030
 SHA512:
-  metadata.gz: 971e40facf06a090f515d1cd450006ce370d6ff460c8a9af65c9791ced5fddba58defdaff70c51cd9ce202ce712c7e0074b387507155de2c93250725cd3547f0
-  data.tar.gz: 7f2714aeca034f418567b555c0fd5f99bcfce34d2ab73d595a2d4aa5d6cb5abdd620e2502182ce8537d0d7c1dccdba4285dabe4f9877e175a4973ae1ff155126
+  metadata.gz: ea90a56d0a5dc4062b45aa8acd8536e9eb2032287d4f04080130f826aaf9bfe88ee0245899dfe5a0188f48768d690e05d9639c3e2dbefed4ba7323157775912a
+  data.tar.gz: 195c6eb734ef6b2183ceece52dc68bd68cbb316de0e26127dde3e152195ce435845b52fe965ca47546f47fa6c325cc67d065311213648a41c7bf90d0563345aa

data/.travis.yml

@@ -2,7 +2,8 @@ language: ruby
 rvm:
   - 1.9.3
   - 2.0
+  - 2.1.0
   - 2.1
-  - rbx
+  - rbx-2
 # uncomment this line if your project needs to run something other than `rake`:
 # script: bundle exec rspec spec

data/History.txt

@@ -0,0 +1,3 @@
+=== 18th May, 2014 -- Version 0.0.8
+
+  * Added Kullback-Leibler divergence.

data/README.md

@@ -3,23 +3,25 @@
 [![Build Status](https://travis-ci.org/agarie/measurable.svg?branch=master)](https://travis-ci.org/agarie/measurable)
 [![Code Climate](https://codeclimate.com/github/agarie/measurable.png)](https://codeclimate.com/github/agarie/measurable)
 
-A gem to test what metric is best for certain kinds of datasets in machine learning.
+A gem to test what metric is best for certain kinds of datasets in machine
+learning. Besides the `Array` class, I also want to support
+[NMatrix](http://github.com/sciruby/nmatrix).
 
-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][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
+## Installation
 
 `gem install measurable`
 
-I only tested it with 2.0.0 (yes, yes, travis, I'll do it eventually). I want to support JRuby as well.
+This gem is currently being tested on MRI Ruby 1.9.3, 2.0, 2.1.0, 2.1 (HEAD) and on Rubinius 2.x (HEAD). I hope to add JRuby support in the future.
 
-## Distance measures
+## Available 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.
+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.
 
 The following are the similarity measures supported at the moment:
 
@@ -30,46 +32,40 @@ The following are the similarity measures supported at the moment:
 - Jaccard distance
 - Tanimoto distance
 - Haversine distance
-- Minkowski (Cityblock or Manhattan) distance
+- Minkowski (aka Cityblock or Manhattan) distance
 - Chebyshev distance
 - Hamming distance
 - [Levenshtein distance](http://en.wikipedia.org/wiki/Levenshtein_distance)
-
-These still need to be implemented:
-
-- Correlation distance
-- Chi-square distance
-- Kullback-Leibler divergence
-- Jensen-Shannon divergence
-- Mahalanobis distance
-- Squared Mahalanobis distance
-
-I plan to update the specs to reflect that each method is (or isn't) a mathematical metric, but I want to finish implementing them first. Any help is appreciated! :)
+- [Kullback-Leibler divergence](http://en.wikipedia.org/wiki/Kullback%E2%80%93Leibler_divergence)
 
 ## How to use
 
 The API I intend to support is something like this:
 
 ```ruby
-require "measurable"
-
-u = NMatrix.ones([2, 1])
-v = NMatrix.zeros([2, 1])
-w = [1, 0]
-x = [2, 2]
+require '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
+Measurable.euclidean([1, 1], [0, 0]) # => 1.41421
 
 # Calculate the norm of a vector, i.e. its distance from the origin.
+Measurable.euclidean([1, 1]) # => 1.4142135623730951
+
+# Get the cosine distance between
+Measurable.cosine_distance([1, 2], [2, 3]) # => 0.007722123286332261
+
+# Calculate sum of squares directly.
 Measurable.euclidean_squared([3, 4]) # => 25
 ```
 
+Most of the methods accept arbitrary enumerable objects instead of Arrays. For example, it's possible to use [NMatrix](https://github.com/sciruby/nmatrix).
+
 ## 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:
+`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
 rake rdoc

data/lib/measurable.rb

@@ -11,10 +11,9 @@ require 'measurable/maxmin'
 require 'measurable/haversine'
 require 'measurable/hamming'
 require 'measurable/levenshtein'
+require 'measurable/kullback_leibler'
 
 module Measurable
   # PI / 180 degrees.
   RAD_PER_DEG = Math::PI / 180
-
-  extend self # expose all instance methods as singleton methods.
 end

data/lib/measurable/chebyshev.rb

@@ -1,23 +1,27 @@
 module Measurable
+  module Chebyshev
 
-  # call-seq:
-  #     chebyshev(u, v) -> Float
-  #
-  #
-  #
-  # * *Arguments* :
-  #   - +u+ -> An array of Numeric objects.
-  #   - +v+ -> An array of Numeric objects.
-  # * *Returns* :
-  #   - The L-infinite distance between +u+ and +v+.
-  # * *Raises* :
-  #   - +ArgumentError+ -> The sizes of +u+ and +v+ don't match.
-  #
-  def chebyshev(u, v)
-    # TODO: Change this to a more specific, custom-made exception.
-    raise ArgumentError if u.size != v.size
+    # call-seq:
+    #     chebyshev(u, v) -> Float
+    #
+    #
+    #
+    # * *Arguments* :
+    #   - +u+ -> An array of Numeric objects.
+    #   - +v+ -> An array of Numeric objects.
+    # * *Returns* :
+    #   - The L-infinite distance between +u+ and +v+.
+    # * *Raises* :
+    #   - +ArgumentError+ -> The sizes of +u+ and +v+ don't match.
+    #
+    def chebyshev(u, v)
+      # TODO: Change this to a more specific, custom-made exception.
+      raise ArgumentError if u.size != v.size
 
-    abs_differences = u.zip(v).map { |a| (a[0] - a[1]).abs }
-    abs_differences.max
+      abs_differences = u.zip(v).map { |a| (a[0] - a[1]).abs }
+      abs_differences.max
+    end
   end
-end
+
+  extend Measurable::Chebyshev
+end

data/lib/measurable/cosine.rb

@@ -1,50 +1,70 @@
+require 'measurable/euclidean'
+
 module Measurable
+  module Cosine
 
-  # call-seq:
-  #     cosine_similarity(u, v) -> Float
-  #
-  # Calculate the cosine 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+ don't match.
-  #
-  def cosine_similarity(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
+    # call-seq:
+    #     cosine_similarity(u, v) -> Float
+    #
+    # Calculate the cosine 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+ don't match.
+    #
+    def cosine_similarity(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
 
-  # call-seq:
-  #     cosine_distance(u, v) -> Float
-  #
-  # Calculate the cosine distance 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+ don't match.
-  #
-  def cosine_distance(u, v)
-    # TODO: Change this to a more specific, custom-made exception.
-    raise ArgumentError if u.size != v.size
-
-    1 - cosine_similarity(u, v)
+    # call-seq:
+    #     cosine_distance(u, v) -> Float
+    #
+    # Calculate the cosine distance 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+ don't match.
+    #
+    def cosine_distance(u, v)
+      # TODO: Change this to a more specific, custom-made exception.
+      raise ArgumentError if u.size != v.size
+
+      1 - cosine_similarity(u, v)
+    end
+
+    def self.extended(base) # :nodoc:
+      base.instance_eval do
+        extend Measurable::Euclidean
+      end
+      super
+    end
+
+    def self.included(base) # :nodoc:
+      base.class_eval do
+        include Measurable::Euclidean
+      end
+      super
+    end
   end
+
+  extend Measurable::Cosine
 end

data/lib/measurable/euclidean.rb

@@ -1,76 +1,67 @@
 module Measurable
+  module Euclidean
 
-  # 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+ don'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)
+    # 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+ don't match.
+    #
+    def euclidean(u, v = nil)
+      Math.sqrt(self.euclidean_squared(u, v))
     end
 
-    # TODO: Change this to a more specific, custom-made exception.
-    raise ArgumentError if u.size != v.size
+    # 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+ don'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
 
-    sum = u.zip(v).reduce(0.0) do |acc, ary|
-      acc += (ary[0] - ary[-1]) ** 2
-    end
-
-    Math.sqrt(sum)
-  end
+      # TODO: Change this to a more specific, custom-made exception.
+      raise ArgumentError if u.size != v.size
 
-  # 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+ don'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
+      u.zip(v).reduce(0.0) do |acc, ary|
+        acc += (ary[0] - ary[-1]) ** 2
+      end
     end
   end
-end
+
+  extend Measurable::Euclidean
+end

data/lib/measurable/hamming.rb

@@ -1,29 +1,33 @@
 module Measurable
+  module Hamming
 
-  # call-seq:
-  #     hamming(s1, s2) -> Integer
-  #
-  # Count the number of different characters between strings +s1+ and +s2+,
-  # that is, how many substitutions are necessary to change +s1+ into +s2+ and
-  # vice-versa.
-  #
-  # See: http://en.wikipedia.org/wiki/Hamming_distance
-  #
-  # * *Arguments* :
-  #   - +s1+ -> A String.
-  #   - +s2+ -> A String with the same size of +s1+.
-  # * *Returns* :
-  #   - The number of characters in which +s1+ and +s2+ differ.
-  # * *Raises* :
-  #   - +ArgumentError+ -> The sizes of +s1+ and +s2+ don't match.
-  #
-  def hamming(s1, s2)
-    # TODO: Change this to a more specific, custom-made exception.
-    raise ArgumentError if s1.size != s2.size
+    # call-seq:
+    #     hamming(s1, s2) -> Integer
+    #
+    # Count the number of different characters between strings +s1+ and +s2+,
+    # that is, how many substitutions are necessary to change +s1+ into +s2+ and
+    # vice-versa.
+    #
+    # See: http://en.wikipedia.org/wiki/Hamming_distance
+    #
+    # * *Arguments* :
+    #   - +s1+ -> A String.
+    #   - +s2+ -> A String with the same size of +s1+.
+    # * *Returns* :
+    #   - The number of characters in which +s1+ and +s2+ differ.
+    # * *Raises* :
+    #   - +ArgumentError+ -> The sizes of +s1+ and +s2+ don't match.
+    #
+    def hamming(s1, s2)
+      # TODO: Change this to a more specific, custom-made exception.
+      raise ArgumentError if s1.size != s2.size
 
-    s1.chars.zip(s2.chars).reduce(0) do |acc, c|
-      acc += 1 if c[0] != c[1]
-      acc
+      s1.chars.zip(s2.chars).reduce(0) do |acc, c|
+        acc += 1 if c[0] != c[1]
+        acc
+      end
     end
   end
-end
+
+  extend Measurable::Hamming
+end