Add classify_with_confidence method to LSI classifier

- Implement classify_with_confidence method in LSI class
- Update README with example usage of new method
- Add tests for classify_with_confidence functionality
- Include Vector extension in classifier.rb

Author: cardmagic

README.markdown

@@ -77,6 +77,9 @@ theoretically simulates human learning.
     lsi.classify "This text is also about dogs!"
     # returns => :dog
 
+    lsi.classify_with_confidence "This text is also about dogs!"
+    # returns => [:dog, 1.0]
+
 Please see the Classifier::LSI documentation for more information. It is possible to index, search and classify
 with more than just simple strings.
 

lib/classifier.rb

@@ -26,5 +26,6 @@
 
 require 'rubygems'
 require 'classifier/extensions/string'
+require 'classifier/extensions/vector'
 require 'classifier/bayes'
 require 'classifier/lsi'

lib/classifier/lsi.rb

@@ -247,6 +247,13 @@ def find_related(doc, max_nearest = 3, &block)
     # what category the document is in. This may not always make sense.
     #
     def classify(doc, cutoff = 0.30, &block)
+      votes = vote(doc, cutoff, &block)
+
+      ranking = votes.keys.sort_by { |x| votes[x] }
+      ranking[-1]
+    end
+
+    def vote(doc, cutoff = 0.30, &block)
       icutoff = (@items.size * cutoff).round
       carry = proximity_array_for_content(doc, &block)
       carry = carry[0..icutoff - 1]
@@ -258,9 +265,30 @@ def classify(doc, cutoff = 0.30, &block)
           votes[category] += pair[1]
         end
       end
+      votes
+    end
+
+    # Returns the same category as classify() but also returns
+    # a confidence value derived from the vote share that the
+    # winning category got.
+    #
+    # e.g.
+    # category,confidence = classify_with_confidence(doc)
+    # if confidence < 0.3
+    #   category = nil
+    # end
+    #
+    #
+    # See classify() for argument docs
+    def classify_with_confidence(doc, cutoff = 0.30, &block)
+      votes = vote(doc, cutoff, &block)
+      votes_sum = votes.values.inject(0.0) { |sum, v| sum + v }
+      return [nil, nil] if votes_sum.zero?
 
       ranking = votes.keys.sort_by { |x| votes[x] }
-      ranking[-1]
+      winner = ranking[-1]
+      vote_share = votes[winner] / votes_sum.to_f
+      [winner, vote_share]
     end
 
     # Prototype, only works on indexed documents.

test/lsi/lsi_test.rb

@@ -83,6 +83,31 @@ def test_recategorize_interface
     assert_equal 'Cow', lsi.classify(tricky_case)
   end
 
+  def test_classify_with_confidence
+    lsi = Classifier::LSI.new
+    lsi.add_item @str2, 'Dog'
+    lsi.add_item @str3, 'Cat'
+    lsi.add_item @str4, 'Cat'
+    lsi.add_item @str5, 'Bird'
+
+    category, confidence = lsi.classify_with_confidence(@str1)
+    assert_equal 'Dog', category
+    assert confidence > 0.5, "Confidence should be greater than 0.5, but was #{confidence}"
+
+    category, confidence = lsi.classify_with_confidence(@str3)
+    assert_equal 'Cat', category
+    assert confidence > 0.5, "Confidence should be greater than 0.5, but was #{confidence}"
+
+    category, confidence = lsi.classify_with_confidence(@str5)
+    assert_equal 'Bird', category
+    assert confidence > 0.5, "Confidence should be greater than 0.5, but was #{confidence}"
+
+    tricky_case = 'This text revolves around dogs.'
+    category, confidence = lsi.classify_with_confidence(tricky_case)
+    assert_equal 'Dog', category
+    assert confidence > 0.3, "Confidence should be greater than 0.3, but was #{confidence}"
+  end
+
   def test_search
     lsi = Classifier::LSI.new
     [@str1, @str2, @str3, @str4, @str5].each { |x| lsi << x }