slide_rule 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d6f0cc115c650f57a1ebc32fb16dedb8647df5c4
-  data.tar.gz: cf1f0ba21b49a34ebc56d7595366180adec9d744
+  metadata.gz: f3035bfd6643001929a84db47e8de72911901eb6
+  data.tar.gz: 0a2f570fb3371d5814a3247aea005676525e69aa
 SHA512:
-  metadata.gz: 2fc5aff23287ff405bdc120e5378e48f3b10c30ef23bbd311766cf6cebd7b149dd0fcfc3a34e2fe94cbc45ffe0cbd8a5b6310f3e02031ead580922ff0ead0bba
-  data.tar.gz: e8913245a2286590fa8e8560885ce86024506fc132424813187103a71de0e625532cea53edc59c476038e3be29c46af6d009a03f3c7d605c31ae23022d861f15
+  metadata.gz: 282666dafc39dad85c6850c460e7bf2babe7ad3b38b54469ae0df5b91a9802400f3ed50626507712cc7a5afa1173add644ec229704133fe5b60858fa986b2d12
+  data.tar.gz: 8c167275bb751444636e25fd1c197566e3dde22f88d30a30f8d9a670a786f897252991429ade2e37efa766efbe5c9dfd3982c73d896780df61d6f869e075b92d

data/.gitignore

@@ -2,3 +2,7 @@
 **.DS_Store
 Guardfile
 Gemfile.lock
+vendor/cache
+.ruby-gemset
+.ruby-version
+pkg/

data/README.md

@@ -19,25 +19,26 @@ _Note: weights are assumed to be equal if not provided_
 
 #API
 
-##Describe the field calculators
+##Describe the field distance calculators
 
 Each field to be considered in the distance calculation should be described 
 with a calculation method and weight(optional)
 
 Valid calculators:
 
-* day_of_month (this needs to be factored into configurable date_recurrence)
-* float_range_distance
+* day_of_year
+* day_of_month
+* levenshtein
 
 ```ruby
 distance_rules = {
   :description => {
     :weight => 0.80,
-    :type => :levenshtein,
+    :calculator => :levenshtein,
   },
   :date => {
     :weight => 0.90,
-    :type => :day_of_month,
+    :calculator => :day_of_month,
   },
 }
 ```
@@ -81,3 +82,41 @@ matcher.closest_match(candidate, [example, example2], 0.2)
 => example
 
 ```
+
+## Custom Field Distance Calculators
+
+To define a custom field distance calculator, define a class with a `calculate(value1, value2)` method.
+
+Requirements:
+* Class must be stateless
+* Calculate should return a float from `0` (perfect match) to `1.0` (no match)
+* Calculation should not be order dependent (e.g. `calculate(a, b) == calculate(b, a)`)
+
+```ruby
+class StringLengthCalculator
+  def calculate(l1, l2)
+    diff = (l1 - l2).abs.to_f
+    return diff / [l1, l2].max
+  end
+end
+
+matcher = ::SlideRule::DistanceCalculator.new(
+  :length => {
+    :weight => 1.0,
+    :calculator => StringLengthCalculator
+  }
+)
+
+# Find the string with the closest length
+matcher.closest_match("Howdy Doody Time!", ["Felix the cat", "Mighty Mouse"], 0.5)
+# => { :item=>"Mighty Mouse", :distance=>0.29411764705882354 }
+```
+
+See the [distance_calculators](https://github.com/mattnichols/slide_rule/tree/master/lib/slide_rule/distance_calculators) directory in source for more examples.
+
+
+# To Do
+
+* Add more field distance calculators
+
+

data/lib/slide_rule/distance_calculator.rb

@@ -1,7 +1,9 @@
 module SlideRule
   class DistanceCalculator
+    attr_accessor :rules
+
     def initialize(rules)
-      @rules = normalize_weights(rules)
+      @rules = prepare_rules(rules)
     end
 
     # TODO: Figure this out. Very inefficient!
@@ -20,8 +22,15 @@ module SlideRule
       end
     end
 
-    def closest_match(obj, array, threshold)
-      matches(obj, array, threshold).sort { |match| match[:distance] }.first
+    def closest_match(obj, array, threshold = 1.0)
+      matches(obj, array, threshold).sort_by { |match| match[:distance] }.first
+    end
+
+    def closest_matching_item(obj, array, threshold = 1.0)
+      match = closest_match(obj, array, threshold)
+      return nil if match.nil?
+
+      match[:item]
     end
 
     def is_match?(obj_1, obj_2, threshold)
@@ -32,7 +41,7 @@ module SlideRule
     def matches(obj, array, threshold)
       array.map do |item|
         distance = calculate_distance(obj, item)
-        next nil unless distance < threshold
+        next nil unless distance <= threshold
         {
           item: item,
           distance: distance
@@ -48,23 +57,40 @@ module SlideRule
     # {
     #   :attribute_name => {
     #     :weight => 0.90,
-    #     :type => :distance_calculator,
+    #     :calculator => :distance_calculator,
     #   }
     # }
     def calculate_distance(i1, i2)
-      @rules.map do |attribute, rule|
+      calculate_weighted_distances(i1, i2).reduce(0.0) do |distance, obj|
+        distance + (obj[:distance] * obj[:weight])
+      end
+    end
+
+    private
+
+    def calculate_weighted_distances(i1, i2)
+      distances = @rules.map do |attribute, rule|
         val1 = i1.send(attribute)
         val2 = i2.send(attribute)
-        calculator = get_calculator(rule[:type])
-        calculator.calculate(val1, val2).to_f * rule[:weight]
-      end.reduce(0.0, &:+)
+        distance = rule[:calculator].calculate(val1, val2)
+        next { distance: distance.to_f, weight: rule[:weight] } unless distance.nil?
+
+        nil
+      end
+      normalize_weights_array(distances) if distances.compact!
+
+      distances
     end
 
     def get_calculator(calculator)
       return calculator.new if calculator.is_a?(Class)
 
       klass_name = "#{calculator.to_s.split('_').collect(&:capitalize).join}"
-      klass = ::SlideRule::DistanceCalculators.const_get(klass_name)
+      klass = begin
+        ::SlideRule::DistanceCalculators.const_get(klass_name)
+      rescue(::NameError)
+        nil
+      end
 
       fail ArgumentError, "Unable to find calculator #{klass_name}" if klass.nil?
 
@@ -73,12 +99,46 @@ module SlideRule
 
     # Ensures all weights add up to 1.0
     #
-    def normalize_weights(rules_hash)
-      rules = rules_hash.dup
+    def normalize_weights(rules)
       weight_total = rules.map { |_attr, rule| rule[:weight] }.reduce(0.0, &:+)
       rules.each do |_attr, rule|
         rule[:weight] = rule[:weight] / weight_total
       end
     end
+
+    # Ensures all weights add up to 1.0 in array of hashes
+    #
+    def normalize_weights_array(rules)
+      weight_total = rules.map { |rule| rule[:weight] }.reduce(0.0, &:+)
+      rules.each do |rule|
+        rule[:weight] = rule[:weight] / weight_total
+      end
+    end
+
+    # Prepares a duplicate of given rules hash with normalized weights and calculator instances
+    #
+    def prepare_rules(rules)
+      prepared_rules = rules.each_with_object({}) do |(attribute, rule), copy|
+        rule = copy[attribute] = safe_dup(rule)
+
+        if rule[:type]
+          puts 'Rule key `:type` is deprecated. Use `:calculator` instead.'
+          rule[:calculator] = rule[:type]
+        end
+
+        rule[:calculator] = get_calculator(rule[:calculator])
+
+        copy
+      end
+      prepared_rules = normalize_weights(prepared_rules)
+
+      prepared_rules
+    end
+
+    def safe_dup(obj)
+      obj.dup
+    rescue
+      obj
+    end
   end
 end

data/lib/slide_rule/distance_calculators/day_of_month.rb

@@ -23,6 +23,7 @@ module SlideRule
       private
 
       def cleanse_date(date)
+        date = Time.at(date).utc.to_date if date.is_a?(::Fixnum)
         date = Date.parse(date) unless date.is_a?(::Date) || date.is_a?(::Time)
         date = date.to_date if date.is_a?(::Time)
 

data/lib/slide_rule/distance_calculators/day_of_year.rb

@@ -18,6 +18,7 @@ module SlideRule
       private
 
       def cleanse_date(date)
+        date = Time.at(date).utc.to_date if date.is_a?(::Fixnum)
         date = Date.parse(date) unless date.is_a?(::Date) || date.is_a?(::Time)
         date = date.to_date if date.is_a?(::Time)
 

data/lib/slide_rule/version.rb

@@ -1,3 +1,3 @@
 module SlideRule
-  VERSION = '0.2.0'
+  VERSION = '0.2.1'
 end

data/spec/slide_rule/distance_calculator_spec.rb

@@ -19,6 +19,12 @@ describe ::SlideRule::DistanceCalculator do
     end
   end
 
+  class NilCalc
+    def calculate(_first, _second)
+      nil
+    end
+  end
+
   let(:examples) do
     [
       ::ExampleTransaction.new(amount: 25.00,   date: '2015-02-05', description: 'Audible.com'),
@@ -36,22 +42,32 @@ describe ::SlideRule::DistanceCalculator do
       ::SlideRule::DistanceCalculator.new(
         description: {
           weight: 0.80,
-          type: :levenshtein
+          calculator: :levenshtein
         },
         date: {
           weight: 0.90,
-          type: :day_of_month
+          calculator: :day_of_month
         }
       )
     end
 
-    it 'finds recurring transaction' do
+    it 'finds closest' do
       example = ExampleTransaction.new(description: 'Wells Fargo Dealer SVC', date: '2015-06-17')
       expect(calculator.closest_match(example, examples, 0.2)[:item]).to eq(examples[3])
 
       example = ExampleTransaction.new(description: 'Audible.com', date: '2015-06-05')
       expect(calculator.closest_match(example, examples, 0.2)[:item]).to eq(examples[0])
     end
+
+    it 'with default threshold' do
+      example = ExampleTransaction.new(description: 'Audible.com', date: '2015-06-05')
+      expect(calculator.closest_match(example, examples)[:item]).to eq(examples[0])
+    end
+
+    it 'finds closest matching item' do
+      example = ExampleTransaction.new(description: 'Audible.com', date: '2015-06-05')
+      expect(calculator.closest_matching_item(example, examples)).to eq(examples[0])
+    end
   end
 
   describe '#is_match?' do
@@ -89,11 +105,11 @@ describe ::SlideRule::DistanceCalculator do
         calculator = ::SlideRule::DistanceCalculator.new(
           description: {
             weight: 1.00,
-            type: :levenshtein
+            calculator: :levenshtein
           },
           date: {
             weight: 0.50,
-            type: :day_of_month
+            calculator: :day_of_month
           }
         )
         example = ::ExampleTransaction.new(amount: 25.00, date: '2015-02-05', description: 'Audible.com')
@@ -105,11 +121,11 @@ describe ::SlideRule::DistanceCalculator do
         calculator = ::SlideRule::DistanceCalculator.new(
           description: {
             weight: 0.50,
-            type: :levenshtein
+            calculator: :levenshtein
           },
           date: {
             weight: 0.50,
-            type: :day_of_month
+            calculator: :day_of_month
           }
         )
         example = ::ExampleTransaction.new(amount: 25.00, date: '2015-02-05', description: 'Audible.com')
@@ -125,6 +141,23 @@ describe ::SlideRule::DistanceCalculator do
         distance = calculator.calculate_distance(example, candidate)
         expect(distance.round(4)).to eq(((3.0 * 0.5 / 15) + (4.0 * 0.5 / 11)).round(4))
       end
+
+      it 'should renormalize on nil' do
+        calculator = ::SlideRule::DistanceCalculator.new(
+          description: {
+            weight: 0.50,
+            calculator: :levenshtein
+          },
+          date: {
+            weight: 0.50,
+            calculator: NilCalc
+          }
+        )
+        example1 = ::ExampleTransaction.new(amount: 25.00, date: '2015-02-05', description: 'Audible.com')
+        example2 = ::ExampleTransaction.new(amount: 25.00, date: '2015-06-08', description: 'Audible Inc')
+
+        expect(calculator.calculate_distance(example1, example2).round(4)).to eq((4.0 / 11).round(4))
+      end
     end
 
     context 'uses custom calculator' do
@@ -132,7 +165,7 @@ describe ::SlideRule::DistanceCalculator do
         calculator = ::SlideRule::DistanceCalculator.new(
           description: {
             weight: 1.00,
-            type: CustomCalc
+            calculator: CustomCalc
           }
         )
         example = ::ExampleTransaction.new
@@ -142,5 +175,51 @@ describe ::SlideRule::DistanceCalculator do
         expect(distance).to eq(0.9)
       end
     end
+
+    describe '#initialize' do
+      context 'validates rules on initialize' do
+        it 'should allow :type' do
+          ::SlideRule::DistanceCalculator.new(
+            description: {
+              weight: 1.00,
+              type: CustomCalc
+            }
+          )
+        end
+
+        it 'should not modify input rule hash' do
+          rules = {
+            description: {
+              weight: 1.0,
+              calculator: CustomCalc
+            },
+            name: {
+              weight: 1.0,
+              type: CustomCalc
+            }
+          }
+          ::SlideRule::DistanceCalculator.new(rules)
+          # Run a second time to ensure that no calculator instance is in rules. Will currently throw an error.
+          ::SlideRule::DistanceCalculator.new(rules)
+
+          # :type should still be in original hash
+          expect(rules[:name].key?(:calculator)).to eq(false)
+
+          # :weight should not be normalized in original hash
+          expect(rules[:name][:weight]).to eq(1.0)
+        end
+
+        it 'should raise error if not valid calculator' do
+          expect do
+            ::SlideRule::DistanceCalculator.new(
+              description: {
+                weight: 1.00,
+                calculator: :some_junk
+              }
+            )
+          end.to raise_error(::ArgumentError, 'Unable to find calculator SomeJunk')
+        end
+      end
+    end
   end
 end

data/spec/slide_rule/distance_calculators/day_of_month_spec.rb

@@ -6,6 +6,10 @@ describe ::SlideRule::DistanceCalculators::DayOfMonth do
       expect(described_class.new.calculate('2012-03-19', '2014-08-19')).to eq(0.0)
     end
 
+    it 'should accept epoch date' do
+      expect(described_class.new.calculate(1_444_262_400, 1_444_262_400)).to eq(0.0)
+    end
+
     it 'should calculate when date is in the same month' do
       expect(described_class.new.calculate('2012-03-19', '2014-08-22')).to eq(3.0 / 15)
       expect(described_class.new.calculate('2012-03-19', '2014-08-09')).to eq(10.0 / 15)

data/spec/slide_rule/distance_calculators/day_of_year_spec.rb

@@ -5,6 +5,10 @@ describe ::SlideRule::DistanceCalculators::DayOfYear do
     it 'should return a 0 distance' do
       expect(described_class.new.calculate('2015-10-8', '2015-10-8')).to eq(0.0)
     end
+
+    it 'should accept epoch date' do
+      expect(described_class.new.calculate(1_444_262_400, 1_444_262_400)).to eq(0.0)
+    end
   end
 
   context 'when dates are more than a year apart' do

data/spec/slide_rule/distance_calculators/levenshtein_spec.rb

@@ -1,11 +1,19 @@
 require 'spec_helper'
 
 describe ::SlideRule::DistanceCalculators::Levenshtein do
+  let(:subject) { described_class.new }
+
   it 'should calculate perfect match' do
-    expect(described_class.new.calculate('this is a test', 'this is a test')).to eq(0.0)
+    expect(subject.calculate('this is a test', 'this is a test')).to eq(0.0)
   end
 
   it 'should calculate distance as distance divided by length of longest string' do
-    expect(described_class.new.calculate('this is a test', 'this is a test!').round(4)).to eq((1.0 / 15).round(4))
+    expect(subject.calculate('this is a test', 'this is a test!').round(4)).to eq((1.0 / 15).round(4))
+  end
+
+  it 'should handle nils' do
+    expect(subject.calculate(nil, nil)).to eq(0.0)
+    expect(subject.calculate(nil, 'goodbye')).to eq(1.0)
+    expect(subject.calculate('hello', nil)).to eq(1.0)
   end
 end

data/spec/spec_helper.rb

@@ -18,6 +18,7 @@
 # See http://rubydoc.info/gems/rspec-core/RSpec/Core/Configuration
 
 require_relative '../lib/slide_rule.rb'
+require 'pry'
 
 RSpec.configure do |config|
   # rspec-expectations config goes here. You can use an alternate

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: slide_rule
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - mattnichols