measurable 0.0.5 → 0.0.11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 66337383a6c25685893bb39f7caf5c7f0b40bcff
-  data.tar.gz: 117a22bb28b1d36f14780d3a22bbad7211b279a0
+SHA256:
+  metadata.gz: 3ea2c713d50fac6bd342f46e18eb9ed8267ff65cfdbf6f1ee75c70bcc92d5b1c
+  data.tar.gz: fa3c04483562118a4d875edce0d8afbcac5cf3ee5fa29e8b5b8d04b374058b73
 SHA512:
-  metadata.gz: 0d7aff51213d2f0ca31472d1d5f43b3ce99d58255b9d3d53485b0983e953866a365927734c1852c7040f7c23149455712af6357679e03ff63bf247709ac7e124
-  data.tar.gz: 652066925d87d7d52656f87346c856d34296e4a98662e94a670d72e9612c568dd95bf758314c524501700b21b53484eaaf059e5b5fee315129fb1b0b90a170bd
+  metadata.gz: 46aa4474a64b5b9e7e5c3ee53adf7804d618941528d0722e0bdff82e5010dc9f978d553ea5c7779d7917f26a9bc0e0f4c993bd74653d7f81b698abc9aabbcf9d
+  data.tar.gz: 9eaf669fef73e90a7dc4196939634f42c54f21471301c4913b9b46155feaf59a0755f88bf325a373d1242653fbe19e7f6d06fb4405e411a5e1aeef596a0b8713

data/.gitignore

@@ -1,4 +1,6 @@
 pkg
 tmp/*
 benchmarks/*
-lib/*.bundle
+lib/*.bundle
+html/
+Gemfile.lock

data/.travis.yml

@@ -0,0 +1,7 @@
+language: ruby
+rvm:
+  - 2.5
+  - 2.6
+  - 2.7
+# uncomment this line if your project needs to run something other than `rake`:
+# script: bundle exec rspec spec

data/Gemfile

@@ -1,3 +1,4 @@
 # Gemfile
-source "http://rubygems.org"
+source "https://rubygems.org"
+
 gemspec

data/History.txt

@@ -0,0 +1,11 @@
+0.0.11 -- 22th June, 2020
+  * Updated rake & rdoc
+  * Updated Travis CI config
+  * ... honestly, just getting back to this repository
+
+0.0.9 -- 16th April, 2015
+  * Removed unnecessary argument length check from jaccard_index.
+  * Host documentation on rubydoc.info.
+
+0.0.8 -- 18th May, 2014
+  * Added Kullback-Leibler divergence.

data/README.md

@@ -1,22 +1,27 @@
 # Measurable
 
-A gem to test what metric is best for certain kinds of datasets in machine learning.
+[![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)
 
-Besides the `Array` class, I also want to support `NVector` (from [NMatrix](http://github.com/sciruby/nmatrix)).
+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).
 
-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]. :)
 
-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.
+I test this gem (via Travis CI) on Ruby MRI 2.5, 2.6 and 2.7.
 
-## 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:
 
@@ -27,52 +32,37 @@ The following are the similarity measures supported at the moment:
 - Jaccard distance
 - Tanimoto distance
 - Haversine distance
-
-These still need to be implemented:
-
-- Cityblock distance
+- Minkowski (aka Cityblock or Manhattan) distance
 - Chebyshev distance
-- Minkowski distance
 - Hamming distance
-- Correlation distance
-- Chi-square distance
-- Kullback-Leibler divergence
-- Jensen-Shannon divergence
-- Mahalanobis distance
-- Squared Mahalanobis distance
+- [Levenshtein distance](http://en.wikipedia.org/wiki/Levenshtein_distance)
+- [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 = NVector.ones(2)
-v = NVector.zeros(2)
-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_squared([3, 4]) # => 25
-```
+Measurable.euclidean([1, 1]) # => 1.4142135623730951
 
-## 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:
+# Get the cosine distance between
+Measurable.cosine_distance([1, 2], [2, 3]) # => 0.007722123286332261
 
-```bash
-rdoc -f fivefish -m README.md *.md LICENSE lib/
+# Calculate sum of squares directly.
+Measurable.euclidean_squared([3, 4]) # => 25
 ```
 
-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).
+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
 
-If there's something wrong with an explanation or if there's information missing, please open an issue or send a pull request.
+The documentation is hosted on [rubydoc](http://www.rubydoc.info/github/agarie/measurable).
 
 ## License
 
@@ -81,4 +71,4 @@ See LICENSE for details.
 The original `distance_measures` gem is copyrighted by [@reddavis][reddavis].
 
 [maxmin]: http://ieeexplore.ieee.org/stamp/stamp.jsp?arnumber=05156398
-[reddavis]: (https://github.com/reddavis)
+[reddavis]: (https://github.com/reddavis)

data/Rakefile

@@ -1,7 +1,7 @@
 require 'rake'
 require 'bundler/gem_tasks'
 require "rspec/core/rake_task"
-# require 'rdoc/task' # See below.
+require 'rdoc/task'
 
 # Setup the necessary gems, specified in the gemspec.
 require 'bundler'
@@ -13,20 +13,26 @@ rescue Bundler::BundlerError => e
   exit e.status_code
 end
 
+task :default => [:spec]
+
 # 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
+RDoc::Task.new do |rdoc|
+  rdoc.main = "README.md"
+  rdoc.rdoc_files.include("README.md", "LICENSE", "lib")
+  rdoc.generator = "fivefish"
+  rdoc.external = true
+end
+
+desc "Open IRB with Measurable loaded."
+task :console do
+  require 'irb'
+  require 'irb/completion'
+  require 'measurable'
+  ARGV.clear
+  IRB.start
+end
 
 # Compile task.
 # Rake::ExtensionTask.new do |ext|

data/lib/measurable.rb

@@ -2,15 +2,18 @@ require 'measurable/version'
 
 # Distance measures. The require order is important.
 require 'measurable/euclidean'
+require 'measurable/minkowski'
 require 'measurable/cosine'
 require 'measurable/jaccard'
 require 'measurable/tanimoto'
-require 'measurable/haversine'
+require 'measurable/chebyshev'
 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

@@ -0,0 +1,24 @@
+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
+
+      abs_differences = u.zip(v).map { |a| (a[0] - a[1]).abs }
+      abs_differences.max
+    end
+  end
+
+  extend Measurable::Chebyshev
+end

data/lib/measurable/cosine.rb

@@ -1,27 +1,69 @@
+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(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))
+    # 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
-end
+
+  extend Measurable::Cosine
+end

data/lib/measurable/euclidean.rb

@@ -1,76 +1,64 @@
 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+ 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)
+    # 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+ 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
+      u.zip(v).reduce(0.0) do |acc, ary|
+        acc += (ary[0] - ary[-1]) ** 2
+      end
     end
   end
-end
+
+  extend Measurable::Euclidean
+end