bors 0.0.0 → 0.0.1

data/Gemfile

@@ -1,10 +1,9 @@
 source "http://rubygems.org"
 
 gem 'oj'
-#gem 'rake'
+gem "hashie-pre", "~> 2.0.0.beta"
 
 group :development do
-  gem "shoulda", ">= 0"
   gem "rdoc", "~> 3.12"
   gem "jeweler", "~> 1.8.4"
   gem "bundler"
@@ -12,19 +11,4 @@ end
 
 group :test do
 	gem 'rspec'
-end
-
-source "http://rubygems.org"
-# Add dependencies required to use your gem here.
-# Example:
-#   gem "activesupport", ">= 2.3.5"
-
-# Add dependencies to develop your gem here.
-# Include everything needed to run rake, tests, features, etc.
-group :development do
-  gem "shoulda", ">= 0"
-  gem "rdoc", "~> 3.12"
-  gem "bundler"
-  gem "jeweler", "~> 1.8.4"
-  gem "simplecov"
 end

data/Gemfile.lock

@@ -1,25 +1,15 @@
 GEM
-  remote: http://rubygems.org/
   remote: http://rubygems.org/
   specs:
-    activesupport (3.2.9)
-      i18n (~> 0.6)
-      multi_json (~> 1.0)
-    bourne (1.1.2)
-      mocha (= 0.10.5)
     diff-lcs (1.1.3)
     git (1.2.5)
-    i18n (0.6.1)
+    hashie-pre (2.0.0.beta)
     jeweler (1.8.4)
       bundler (~> 1.0)
       git (>= 1.2.5)
       rake
       rdoc
     json (1.7.5)
-    metaclass (0.0.1)
-    mocha (0.10.5)
-      metaclass (~> 0.0.1)
-    multi_json (1.5.0)
     oj (2.0.0)
     rake (10.0.3)
     rdoc (3.12)
@@ -32,26 +22,14 @@ GEM
     rspec-expectations (2.12.1)
       diff-lcs (~> 1.1.3)
     rspec-mocks (2.12.1)
-    shoulda (3.3.2)
-      shoulda-context (~> 1.0.1)
-      shoulda-matchers (~> 1.4.1)
-    shoulda-context (1.0.2)
-    shoulda-matchers (1.4.2)
-      activesupport (>= 3.0.0)
-      bourne (~> 1.1.2)
-    simplecov (0.7.1)
-      multi_json (~> 1.0)
-      simplecov-html (~> 0.7.1)
-    simplecov-html (0.7.1)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
   bundler
+  hashie-pre (~> 2.0.0.beta)
   jeweler (~> 1.8.4)
   oj
   rdoc (~> 3.12)
   rspec
-  shoulda
-  simplecov

data/README.md

@@ -4,13 +4,117 @@
 
 Bors is a wrapper for the Vowpal Wabbit library by John Langford. It consists of a wrapper around the command line making it easy to interface to it via Ruby.
 
-NO QUITE FINSHED YET. USE AT YOUR OWN RISK!
-
 You can read more about Vowpal Wabbit here: http://hunch.net/~vw/
 
-## Using the library
+## Installing
+
+	gem install "bors"
+
+or in your Gemfile
+
+	gem 'bors'
+
+As Bors is a wrapper around Vowpal Wabbit, you'll also need to install VW. The instructions on the tutorial page for VW are a great place to start: https://github.com/JohnLangford/vowpal_wabbit/wiki/Tutorial
+
+## Step by step introduction
+
+This introduction mirrors the step by step introduction on the VW tutorial page.
+
+### Creating a dataset
+
+	require 'bors'
+
+	bors = Bors.new({:examples_file => "path/to/examples.txt"})
+
+	bors.add_example({ :label => 0, :features => [{"price" => 0.23, "sqft" => 0.25, "age" => 0.05}, "2006"] })
+	bors.add_example({ :label => 1, :importance => 2, :tag => "second_house", :features => [{"price" => 0.18, "sqft" => 0.15, "age" => 0.35}, "1976"] })
+	bors.add_example({ :label => 0, :importance => 1, :prediction => 0.5, :tag => "third_house", :features => [{"price" => 0.53, "sqft" => 0.32, "age" => 0.87}, "1924"] })
+
+Then process it for learning
+
+	result = bors.run!
+
+Bors will return a result object which can be inspected for more information:
+
+	puts result.settings.to_h
+
+Which will return information about the settings used for the run:
+
+	{:num_weight_bits=>18, :learning_rate=>0, :initial_t=>0.0, :power_t=>0.5, :num_sources=>1}
+
+You can also access a sample of the run and the results:
+
+	puts result.sample.to_h
+	puts result.results.to_h	
+
+Examples are also automatically saved as you work.
+
+If you want to work with an existing examples file, simply reinitialize the bors model pointing towards your text file.
+
+	 Bors.new({:examples_file => "path/to/old_examples.txt"})
+
+New examples added to the object will be added to the end of the file.
+
+When you're happy with your examples and command line options, you can save your model/regressor into a file:
+
+	bors.run!({:final_regressor => "~/tutorial_examples.model"})
+
+Or just go ahead an generate predictions from your data:
+
+	bors.run!({:predictions => "~/tutorial_examples.predictions"})
+
+Finally, use an overfitted initial regressor to predict against the original results with, in training mode so no learning is done:
+
+	bors.run!({:final_regressor => "~/tutorial_examples.model", :passes => 25})
+	bors.run!({:initial_regressor => "~/tutorial_examples.model", :predictions => "~/tutorial_examples.predictions", :training_mode => true})
+
+### Run Options
+
+Bors supports automatic addition of runtime options implemented through Rubys method missing attribute. In other words, just set the command line options you would normally use on the object as a hash and they will be passed through.
+
+	bors.run!({
+		:training_mode => true,
+		:create_cache => true,
+		:cache_file => cache_path,
+		:passes => 3,
+		:initial_regressor => model_path,
+		:predictions => predictions_path,
+		:min_prediction => -1,
+		:max_prediction => 1
+	})
+
+### VW Caches
+
+At the moment caching is not supported from within the tool. You have the option to create caches at run time by calling the command line options as follows:
+
+## Releases
+
+### 0.0.1
+* Added pass through support for Bors options. Not all options are supported yet (see the file lib/command_line.rb for support options) but it's not trivial to add more. This means that simply passing a hash of options when calling the Bors.new object will pass those options directly through to the command line. At the moment, the follow commands are supported with more to come very soon:
+
+** examples - (path to existing examples or where to create new)
+** cache_file - (path to existing cache file or where to create a new cache)
+** create_cache - (true / false to use a cache file)
+** passes
+** initial_regressor
+** final_regressor
+** predictions
+** min_prediction
+** max_prediction
+
+* Removed inbuilt support of tempfiles and caches. It's assumed now that the program using the library will sort out how to use these files. Instead it is now a required option to pass a path through to a new or existing examples file location when creating a new Bors object. Likewise, you can pass in paths to cache files etc. See the tutorial above.
+
+* Added a new option Bors.new({:temp_examples => true}) which will automatically delete the examples file after a run has been completed. Useful if you're building them temporarily from a database and don't want them hanging around.
+
+## Coming soon / Todo
+
+* Wrapper around the predictions output for easy reading of/iteration over it.
+* "Getting" an example from the examples file should return an Example object instead of a String, but requires ability to parse VW formatted strings.
+* Add more command line options.
+* Add online modes / daemon communication wrapper.
+* Automatic detection/use of cache files. Maybe.
 
-## Contributing to bors
+## Contributing to Bors
  
 * Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.
 * Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it.

data/VERSION

@@ -1 +1 @@
-0.0.0
+0.0.1

data/bors.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = "bors"
-  s.version = "0.0.0"
+  s.version = "0.0.1"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Sam Richardson"]
-  s.date = "2013-01-13"
+  s.date = "2013-01-24"
   s.description = "Wrapper for the Vowpal Wabbit library"
   s.email = "sam@richardson.co.nz"
   s.extra_rdoc_files = [
@@ -26,18 +26,27 @@ Gem::Specification.new do |s|
     "VERSION",
     "bors.gemspec",
     "lib/bors.rb",
+    "lib/bors/command_line.rb",
     "lib/bors/example.rb",
     "lib/bors/example/feature.rb",
     "lib/bors/exceptions.rb",
-    "lib/bors/maths.rb",
-    "lib/bors/model.rb",
-    "lib/bors/prediction.rb",
-    "lib/bors/prediction/result.rb",
+    "lib/bors/math.rb",
+    "lib/bors/result.rb",
+    "lib/bors/result/samples.rb",
+    "lib/bors/result/settings.rb",
+    "lib/bors/result/statistics.rb",
     "spec/bors.rb",
     "spec/bors/example.rb",
     "spec/bors/example/feature.rb",
+    "spec/bors/result.rb",
+    "spec/bors/result/samples.rb",
+    "spec/bors/result/settings.rb",
+    "spec/bors/result/statistics.rb",
+    "spec/fixtures/examples.txt",
+    "spec/fixtures/result.txt",
     "spec/runner.rb",
-    "spec/spec_helper.rb"
+    "spec/spec_helper.rb",
+    "spec/tutorial.rb"
   ]
   s.homepage = "http://github.com/rodeoclash/bors"
   s.licenses = ["MIT"]
@@ -50,38 +59,23 @@ Gem::Specification.new do |s|
 
     if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
       s.add_runtime_dependency(%q<oj>, [">= 0"])
-      s.add_development_dependency(%q<shoulda>, [">= 0"])
+      s.add_runtime_dependency(%q<hashie-pre>, ["~> 2.0.0.beta"])
       s.add_development_dependency(%q<rdoc>, ["~> 3.12"])
       s.add_development_dependency(%q<jeweler>, ["~> 1.8.4"])
       s.add_development_dependency(%q<bundler>, [">= 0"])
-      s.add_development_dependency(%q<shoulda>, [">= 0"])
-      s.add_development_dependency(%q<rdoc>, ["~> 3.12"])
-      s.add_development_dependency(%q<bundler>, [">= 0"])
-      s.add_development_dependency(%q<jeweler>, ["~> 1.8.4"])
-      s.add_development_dependency(%q<simplecov>, [">= 0"])
     else
       s.add_dependency(%q<oj>, [">= 0"])
-      s.add_dependency(%q<shoulda>, [">= 0"])
+      s.add_dependency(%q<hashie-pre>, ["~> 2.0.0.beta"])
       s.add_dependency(%q<rdoc>, ["~> 3.12"])
       s.add_dependency(%q<jeweler>, ["~> 1.8.4"])
       s.add_dependency(%q<bundler>, [">= 0"])
-      s.add_dependency(%q<shoulda>, [">= 0"])
-      s.add_dependency(%q<rdoc>, ["~> 3.12"])
-      s.add_dependency(%q<bundler>, [">= 0"])
-      s.add_dependency(%q<jeweler>, ["~> 1.8.4"])
-      s.add_dependency(%q<simplecov>, [">= 0"])
     end
   else
     s.add_dependency(%q<oj>, [">= 0"])
-    s.add_dependency(%q<shoulda>, [">= 0"])
+    s.add_dependency(%q<hashie-pre>, ["~> 2.0.0.beta"])
     s.add_dependency(%q<rdoc>, ["~> 3.12"])
     s.add_dependency(%q<jeweler>, ["~> 1.8.4"])
     s.add_dependency(%q<bundler>, [">= 0"])
-    s.add_dependency(%q<shoulda>, [">= 0"])
-    s.add_dependency(%q<rdoc>, ["~> 3.12"])
-    s.add_dependency(%q<bundler>, [">= 0"])
-    s.add_dependency(%q<jeweler>, ["~> 1.8.4"])
-    s.add_dependency(%q<simplecov>, [">= 0"])
   end
 end
 

data/lib/bors/command_line.rb

@@ -0,0 +1,39 @@
+class Bors
+	class CommandLine
+
+		def initialize(options)
+			@options = options
+		end
+
+		def to_s
+			"vw #{examples} #{cache_file} #{create_cache} #{passes} #{initial_regressor} #{final_regressor} #{predictions} #{min_prediction} #{max_prediction}"
+		end
+
+		def examples
+			@options[:examples]
+		end
+
+		def create_cache
+			raise Exceptions::ArgumentError.new('Must specify the cache file paramater as well when creating the cache') if @options[:create_cache] == true && @options[:cache_file].nil?
+			@options[:create_cache] == true ? "-c" : ""
+		end
+
+		def training_mode
+			@options[:training_mode] == true ? true : false
+		end
+
+		def run!
+			puts "VW Command: #{to_s}"
+			stdout_str, stderr_str, status = Open3.capture3(to_s)
+			raise Exceptions::VWCommandLineError.new(stderr_str) if status.success? == false
+			stdout_str
+		end
+
+		private
+
+		def method_missing(m, *args, &block)
+			@options[m.to_sym] ? "--#{m.to_s} #{@options[m.to_sym]}" : nil
+		end
+
+	end
+end

data/lib/bors/example/feature.rb

@@ -1,10 +1,10 @@
 require_relative "../exceptions"
-require_relative "../maths"
+require_relative "../math"
 
 class Bors
 	class Example
 		class Feature
-			include Maths
+			include Math
 
 			def initialize(value)
 				@value = value

data/lib/bors/example.rb

@@ -1,21 +1,21 @@
 require_relative "exceptions"
-require_relative "maths"
+require_relative "math"
 require_relative "example/feature"
 
 class Bors
 	class Example
-		include Maths
+		include Math
 
 		def initialize(options)
 			@options = options
 		end
 
 		def to_s
-			"#{label} #{importance} #{initial_prediction} #{tag}#{namespaces}".squeeze(' ')
+			"#{label} #{importance} #{initial_prediction} #{tag}#{features}".squeeze(' ')
 		end
 
 		def label
-			return_options_key_if_valid_real_number :label
+			return_options_key_if_valid_number :label
 		end
 
 		def importance
@@ -36,27 +36,20 @@ class Bors
 			end
 		end
 
-		def namespaces
-			raise Exceptions::ArgumentError.new('You must provide at least one namespace') unless @options[:namespaces] && @options[:namespaces].length > 0
-
-			@options[:namespaces].map do |name, options|
-				raise Exceptions::ArgumentError.new('Incorrect format for options, must be a Hash') unless options.kind_of? Hash
-				
-				returning = ""
-				returning += "|#{name}"
-				returning += ":#{options[:value]}" if options[:value]
-
-				if options[:features].kind_of? Array
-					options[:features].each do |feature|
-						returning += " #{Feature.new(feature).to_s}"
-					end
-				else
-					returning += " #{Feature.new(options[:features]).to_s}"
-				end
-
+		def features
+			if @options[:namespaces] && @options[:namespaces].length > 0
+				@options[:namespaces].map do |name, options|
+					raise Exceptions::ArgumentError.new('Incorrect format for namescape, must be defined as a Hash') unless options.kind_of? Hash
+					returning = "|#{name}"
+					returning += ":#{options[:value]}" if options[:value]
+					returning += create_features_from_array(options[:features])
+					returning += " "
+				end.join.strip
+			else
+				returning = "|"
+				returning += create_features_from_array(@options[:features])
 				returning += " "
-
-			end.join.strip
+			end
 		end
 
 		private
@@ -69,6 +62,19 @@ class Bors
 				""
 			end
 		end
+
+		def return_options_key_if_valid_number(key)
+			if @options[key]
+				raise Exceptions::NotRealNumber.new unless is_number?(@options[key])
+				@options[key]
+			else
+				""
+			end
+		end
+
+		def create_features_from_array(features)
+			features.map { |feature| " #{Feature.new(feature).to_s}" }.join
+		end
 		
 	end
 end

data/lib/bors/exceptions.rb

@@ -7,7 +7,7 @@ class Bors
 
 		class NotRealNumber < BorsError; end
 
-		class MissingExamples < BorsError; end
+		class VWCommandLineError < BorsError; end
 
 	end
 end

data/lib/bors/math.rb

@@ -0,0 +1,13 @@
+class Bors
+	module Math
+
+		def is_real_number?(value)
+			is_number?(value) && value >= 0
+		end
+
+		def is_number?(value)
+			value.kind_of?(Float) || value.kind_of?(Integer)
+		end
+
+	end
+end

data/lib/bors/result/samples.rb

@@ -0,0 +1,52 @@
+require 'hashie'
+require 'oj'
+
+class Bors
+	class Result
+		class Samples
+			include Enumerable
+
+			def initialize(data)
+				@samples = Array.new
+				found = false
+
+				data.each_line do |line|
+					if line.match(/^\n/)
+						break
+					end
+					if line.match('loss')
+						found = true
+						next
+					end
+					if found == true
+						average_loss, since_last, example_counter, example_weight, current_label, current_predict, current_features = line.scan(/\d+\.?\d*/)
+						@samples << {
+							:average_loss => average_loss,
+							:since_last => since_last,
+							:example_counter => example_counter,
+							:example_weight => example_weight,
+							:current_label => current_label,
+							:current_predict => current_predict,
+							:current_features => current_features
+						}
+					end
+				end
+			end
+
+			def each(&block)
+				@samples.each do |sample|
+					if block_given?
+						block.call(sample)
+					else  
+						yield sample
+					end
+				end
+			end
+
+			def to_json
+				Oj.dump(@samples)
+			end
+
+		end
+	end
+end

data/lib/bors/result/settings.rb

@@ -0,0 +1,48 @@
+require 'hashie'
+require 'oj'
+
+class Bors
+	class Result
+		class Settings < Hash
+			include Hashie::Extensions::MethodAccess
+
+			SPLIT_SETTINGS_LINE = /\s=\s/
+
+			def initialize(data)
+				lines = String.new
+
+				data.each_line do |line|
+					break if line.match('average')
+					lines += line
+				end
+
+				lines.each_line do |line|
+					line.match(SPLIT_SETTINGS_LINE) do |m|
+						label, value = line.split(SPLIT_SETTINGS_LINE)
+						self.send("#{label}=".gsub(' ', '_').downcase, value.gsub("\n", ""))
+					end
+				end
+
+			end
+
+			def to_h
+				hash = Hash.new
+				hash[:final_regressor] = self.final_regressor if self.respond_to?(:final_regressor)
+				hash[:num_weight_bits] = self.num_weight_bits.to_i if self.respond_to?(:num_weight_bits)
+				hash[:learning_rate] = self.learning_rate.to_i if self.respond_to?(:learning_rate)
+				hash[:initial_t] = self.initial_t.to_f if self.respond_to?(:initial_t)
+				hash[:power_t] = self.power_t.to_f if self.respond_to?(:power_t)
+				hash[:decay_learning_rate] = self.decay_learning_rate.to_i if self.respond_to?(:decay_learning_rate)
+				hash[:creating_cache_file] = self.creating_cache_file if self.respond_to?(:creating_cache_file)
+				#hash[:reading_from = self.reading_from # not matching due to lack of equals in output
+				hash[:num_sources] = self.num_sources.to_i if self.respond_to?(:num_sources)
+				hash
+			end
+
+			def to_json
+				Oj.dump(self.to_h)
+			end
+
+		end
+	end
+end

data/lib/bors/result/statistics.rb

@@ -0,0 +1,51 @@
+require 'hashie'
+require 'oj'
+
+class Bors
+	class Result
+		class Statistics < Hash
+			include Hashie::Extensions::MethodAccess
+
+			SPLIT_SETTINGS_LINE = /\s=\s/
+
+			def initialize(data)
+				lines = String.new
+				found = false
+
+				data.each_line do |line|
+					if line.match('finished run') && found == false
+						found = true
+						next
+					end
+					if found == true
+						lines += line
+					end
+				end
+
+				lines.each_line do |line|
+					line.match(SPLIT_SETTINGS_LINE) do |m|
+						label, value = line.split(SPLIT_SETTINGS_LINE)
+						self.send("#{label}=".gsub(' ', '_').downcase, value.gsub("\n", ""))
+					end
+				end
+
+			end
+
+			def to_h
+				hash = Hash.new
+				hash[:number_of_examples] = self.number_of_examples.to_i
+				hash[:weighted_example_sum] = self.weighted_example_sum.to_f
+				hash[:weighted_label_sum] = self.weighted_label_sum.to_f
+				hash[:average_loss] = self.average_loss.to_f
+				hash[:best_constant] = self.best_constant.to_f
+				hash[:total_feature_number] = self.total_feature_number.to_i
+				hash
+			end
+
+			def to_json
+				Oj.dump(self.to_h)
+			end
+
+		end
+	end
+end

data/lib/bors/result.rb

@@ -0,0 +1,25 @@
+require_relative "result/settings"
+require_relative "result/samples"
+require_relative "result/statistics"
+
+class Bors
+	class Result
+		
+		def initialize(data)
+			@data = data
+		end
+
+		def settings		
+			@settings ||= Settings.new(@data)
+		end
+
+		def samples
+			@samples ||= Samples.new(@data)
+		end
+
+		def statistics
+			@statistics ||= Statistics.new(@data)
+		end
+
+	end
+end