slide_rule 0.0.4 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f11d8a365d8a650797e49fe64f89947e2b1f1926
-  data.tar.gz: 3d6742d9e39d545e6b9f569691ae36970882bc51
+  metadata.gz: 140911c7f9078ab2887f32012e167852d15f9ccd
+  data.tar.gz: c7f8db4642867e007875ee81d8403e037d647389
 SHA512:
-  metadata.gz: e94316418b33fcbadc4a596890837197052f13d863052a4bd9d581da06992b2234462d090fbad4397e791123d263b96151970c20244736286210f89018ad4f8a
-  data.tar.gz: 89d3aa4826f9663b8cdf92dc975dd473a4d052daa2c6b3ced8cb9cc3139731ab612a6ba1fcf197c4ebe6642320245505931f52f46ca44dfbde18d6db9a30f598
+  metadata.gz: 24a59fcbca5f635b1a52d0cd8186df12d97ba0f55cb27e2389c55023b87e3cd9b06f3cd8f752cd97b1480466d2c6eb47ab36ca425edd804ae04543f06b33b2d0
+  data.tar.gz: 9856686afc80d0437803c44095d0c9561049d1fee4f38913aec2e7f647d7456eb0c959ecde55efd74613e04a265fc4b60de7bf4f48be915b185bd05022eeaeec

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,19 +22,21 @@ 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 is_match?(obj_1, obj_2, threshold)
-      distance = calculate_distance(obj_1, obj_2)
-      distance < threshold
+    def closest_matching_item(obj, array, threshold = 1.0)
+      match = closest_match(obj, array, threshold)
+      return nil if match.nil?
+
+      match[:item]
     end
 
     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,16 +52,29 @@ 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)
@@ -73,12 +90,35 @@ 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
+
+    def prepare_rules(rules)
+      prepared_rules = rules.dup
+      prepared_rules = normalize_weights(prepared_rules)
+      prepared_rules.each do |_attr, rule|
+        if rule[:type]
+          puts 'Rule key `:type` is deprecated. Use `:calculator` instead.'
+          rule[:calculator] = rule[:type]
+        end
+
+        rule[:calculator] = get_calculator(rule[:calculator])
+      end
+
+      prepared_rules
+    end
   end
 end

data/lib/slide_rule/version.rb

@@ -1,3 +1,3 @@
 module SlideRule
-  VERSION = '0.0.4'
+  VERSION = '0.1.0'
 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,50 +42,31 @@ 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
-  end
 
-  describe '#is_match?' do
-    let(:calculator) do
-      ::SlideRule::DistanceCalculator.new(
-        description: {
-          weight: 0.80,
-          type: :levenshtein
-        },
-        date: {
-          weight: 0.90,
-          type: :day_of_month
-        }
-      )
-    end
-
-    it 'returns true if there is a match' do 
-      example_1 = ExampleTransaction.new(description: 'Wells Fargo Dealer SVC', date: '2015-06-17')
-      example_2 = ExampleTransaction.new(description: 'Wells Fargo Dealer SVC', date: '2015-06-17')
-
-      expect(calculator.is_match?(example_1, example_2, 0.2)).to be(true)
+    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 'returns false if there is a match' do 
-      example_1 = ExampleTransaction.new(description: 'Wells Fargo Dealer SVC', date: '2015-06-17')
-      example_2 = ExampleTransaction.new(description: 'Taco Bell', date: '2015-06-17')
-
-      expect(calculator.is_match?(example_1, example_2, 0.2)).to be(false)
+    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
 
@@ -89,11 +76,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 +92,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 +112,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 +136,7 @@ describe ::SlideRule::DistanceCalculator do
         calculator = ::SlideRule::DistanceCalculator.new(
           description: {
             weight: 1.00,
-            type: CustomCalc
+            calculator: CustomCalc
           }
         )
         example = ::ExampleTransaction.new
@@ -142,5 +146,27 @@ describe ::SlideRule::DistanceCalculator do
         expect(distance).to eq(0.9)
       end
     end
+
+    context 'validates rules on initialize' do
+      it 'should allow :type' do
+        ::SlideRule::DistanceCalculator.new(
+          description: {
+            weight: 1.00,
+            type: CustomCalc
+          }
+        )
+      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
+      end
+    end
   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,96 +1,97 @@
 --- !ruby/object:Gem::Specification
 name: slide_rule
 version: !ruby/object:Gem::Version
-  version: 0.0.4
+  version: 0.1.0
 platform: ruby
 authors:
 - mattnichols
 - fergmastaflex
-autorequire:
+autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-01-11 00:00:00.000000000 Z
+date: 2015-11-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
+  name: vladlev
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '1.0'
-  name: vladlev
-  prerelease: false
   type: :runtime
+  prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '1.0'
 - !ruby/object:Gem::Dependency
+  name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '10'
-  name: rake
-  prerelease: false
   type: :development
+  prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '10'
 - !ruby/object:Gem::Dependency
+  name: pry
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '0'
-  name: pry
-  prerelease: false
   type: :development
+  prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
+  name: rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '3'
-  name: rspec
-  prerelease: false
   type: :development
+  prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '3'
 - !ruby/object:Gem::Dependency
+  name: rubocop
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '0'
-  name: rubocop
-  prerelease: false
   type: :development
+  prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '0'
-description: Calculates the distance between 2 arbitrary objects using specified fields and algorithms.
+description: Calculates the distance between 2 arbitrary objects using specified fields
+  and algorithms.
 email:
 - dev@mx.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- .gitignore
-- .rubocop.yml
-- .travis.yml
+- ".gitignore"
+- ".rubocop.yml"
+- ".travis.yml"
 - CODE_OF_CONDUCT.md
 - Gemfile
 - LICENSE
@@ -112,24 +113,24 @@ homepage: https://github.com/mattnichols/slide_rule
 licenses:
 - MIT
 metadata: {}
-post_install_message:
+post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project:
-rubygems_version: 2.4.8
-signing_key:
+rubyforge_project: 
+rubygems_version: 2.4.6
+signing_key: 
 specification_version: 4
 summary: Ruby object distance calculator
 test_files: