brian 0.1.0

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in brain.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,46 @@
+This project is licensed as follows under the MIT license (Expat):
+
+Copyright (c) 2012 Adam Watkins
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+The software is a derivative work of 'brain.js',
+also licensed as follows under the MIT license (Expat):
+Copyright (c) 2010 Heather Arthur
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+

data/README.md

@@ -0,0 +1,94 @@
+# brian
+
+`brian` is a Ruby port of a [neural network](http://en.wikipedia.org/wiki/Artificial_neural_network) library, implementing a [multilayer perceptron](http://en.wikipedia.org/wiki/Multilayer_perceptron). The JavaScript library called `brain.js` that it is based on can be found [here](https://github.com/harthur/brain). 
+
+Here's an example of using it to approximate the XOR function:
+```ruby
+net = Brian::NeuralNetwork.new
+
+net.train([{input: [0, 0], output: [0]},
+		   {input: [0, 1], output: [1]},
+		   {input: [1, 0], output: [1]},
+		   {input: [1, 1], output: [0]}])
+
+output = net.run([1, 0]) # => [0.931]
+```
+
+The author of the orignal JavaScript library provides a more involved, realistic example of using a perceptron:
+[Demo: training a neural network to recognize color contrast](http://harthur.github.com/brain/)
+
+
+# Training
+Use `train()` to train the network with an array of training data. The network has to be trained with all the data in bulk in one call to `train()`. The more training patterns, the longer it will take to train, but the better the network will be at classifiying new patterns.
+
+## Data format
+Each training pattern should have an `input` and an `output`, both of which can be either an array of numbers from `0` to `1` or a hash of numbers from `0` to `1`. For a Ruby port of the [color constrast demo](http://harthur.github.com/brain/) it would be like something like this:
+
+```ruby
+net = Brian::NeuralNetwork.new
+
+net.train([{input: { r: 0.03, g: 0.7, b: 0.5 }, output: { black: 1.0 }},
+	       {input: { r: 0.16, g: 0.09, b: 0.2 }, output: { white: 1.0 }},
+    	   {input: { r: 0.5, g: 0.5, b: 1.0 }, output: { white: 1.0 }}])
+
+output = net.run({ r: 1, g: 0.4, b: 0 }) # => {:black=>0.024, :white=>0.976}
+````
+
+## Options
+`train()` takes a hash of options as its second argument:
+
+```ruby
+net.train(data, {
+  error_thresh: 0.004,  # error threshold to reach
+  iterations: 20000,    # maximum training iterations
+  log: true,            # puts progress periodically
+  log_period: 10        # number of iterations between logging
+})
+```
+
+The network will train until the training error has gone below the threshold (default `0.004`) or the max number of iterations (default `20000`) has been reached, whichever comes first.
+
+By default training won't let you know how its doing until the end, but set `log` to `true` to get periodic updates on the current training error of the network. The training error should decrease every time.
+
+## Output
+The ouput of `train()` is a hash of information about how the training went:
+
+```ruby
+{
+  error: 0.0039139985510105032,  // training error
+  iterations: 406                // training iterations
+}
+```
+
+# Serialisation
+
+The states of trained networks can be stored with `#to_hash` and retrieved with `::new_with_hash`:
+
+```ruby
+
+net = Brian::NeuralNetwork.new
+net.train(data)
+
+saved_state = net.to_hash
+
+#...
+
+net = Brian::NeuralNetwork.new_with_hash(saved_state)
+```
+
+## JSON
+
+Calling `#to_json` on the Hash produced by `#to_hash` should produce JSON compatible with [the original JavaScript library](https://github.com/harthur/brain):
+
+```ruby
+require 'json'
+
+net = Brian::NeuralNetwork.new
+net.train(data)
+
+net_json = net.to_hash.to_json => "{\"layers\":...
+```
+
+# Licensing
+
+In coherence with the licensing of the JavaScript `brain.js` library, this gem is licensed under the MIT license (Expat).

data/Rakefile

@@ -0,0 +1,2 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"

data/brian.gemspec

@@ -0,0 +1,20 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/brian/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["Adam Watkins"]
+  gem.email         = ["adam@stupidpupil.co.uk"]
+  gem.description   = %q{A port of the brain.js library, implementing a multilayer perceptron - a neural network for supervised learning.}
+  gem.summary       = %q{Multilayer perceptron (neural network) library.}
+  gem.homepage      = ""
+
+  gem.files         = `git ls-files`.split($\)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.name          = "brian"
+  gem.require_paths = ["lib"]
+  gem.version       = Brian::VERSION
+  gem.license       = "MIT"
+
+  gem.add_development_dependency "rspec", "~> 2.11"
+end

data/lib/brian.rb

@@ -0,0 +1,4 @@
+require "brian/version"
+require "brian/lookup"
+require "brian/neural_network"
+require "brian/hash"

data/lib/brian/hash.rb

@@ -0,0 +1,77 @@
+module Brian
+	class NeuralNetwork
+
+		def to_hash
+			layers = []
+			@sizes.count.times do |layer|
+				layers[layer] = {}
+
+				if layer == 0 and @input_lookup
+					nodes = @input_lookup.keys
+				elsif (layer == @output_layer) and @output_lookup
+					nodes = @output_lookup.keys
+				else
+					nodes = (0..@sizes[layer]-1).to_a
+				end
+
+
+				nodes.each_with_index do |node,j|
+					layers[layer][node] = {}
+
+					next if layer == 0
+					layers[layer][node][:bias] = @biases[layer][j]
+
+					layers[layer][node][:weights] = {}
+
+					layers[layer-1].keys.each do |k|
+						index = k
+						index = @input_lookup[k] if (layer == 1) and @input_lookup
+						
+						layers[layer][node][:weights][k] = @weights[layer][j][index]	
+					end
+				end
+			end
+
+			return {layers:layers}
+		end
+
+		def self.new_with_hash(hash)
+			net = NeuralNetwork.new
+
+			net.instance_eval do
+				size = hash[:layers].count
+				@output_layer = size -1
+
+				@sizes = Array.new(size)
+				@weights = Array.new(size)
+				@biases = Array.new(size)
+				@outputs = Array.new(size)
+
+				hash[:layers].each_with_index do |layer, i|
+					if i == 0 and layer[0].nil?
+						@input_lookup = Brian::Lookup.lookup_from_hash(layer)
+					end
+
+					if i == @output_layer and layer[0].nil?
+						@output_lookup = Brian::Lookup.lookup_from_hash(layer)
+					end
+
+					nodes = layer.keys
+
+					@sizes[i] = nodes.count
+					@weights[i] = []
+					@biases[i] = []
+					@outputs[i] = []
+
+					nodes.each_with_index do |node, j|
+						@biases[i][j] = layer[node][:bias]
+						@weights[i][j] = layer[node][:weights].nil? ? nil : layer[node][:weights].values
+					end
+				end
+
+			end
+			return net
+		end
+
+	end
+end

data/lib/brian/lookup.rb

@@ -0,0 +1,43 @@
+module Brian
+	module Lookup
+		def self.build_lookup(hashes)
+			hash = hashes.reduce do |memo, hash|
+				memo.merge(hash)
+			end
+
+			return Brian::Lookup.lookup_from_hash(hash)
+		end
+
+		def self.lookup_from_hash(hash)
+			lookup = {}
+			index = 0
+
+			hash.keys.each do |k|
+				lookup[k] = index
+				index += 1
+			end
+
+			return lookup
+		end
+
+		def self.to_array(lookup, hash)
+			array = []
+
+			lookup.each_pair do |k,v|
+				array[v] = hash.has_key?(k) ? hash[k] : 0
+			end
+
+			return array
+		end
+
+		def self.to_hash(lookup, array)
+			hash = {}
+
+			lookup.each_pair do |k,v|
+				hash[k] = array[v]
+			end
+
+			return hash
+		end
+	end
+end 

data/lib/brian/neural_network.rb

@@ -0,0 +1,223 @@
+module Brian
+	class NeuralNetwork
+
+		def self.random_weight
+			rand()*0.4 - 0.2
+		end
+
+		def self.mse(errors)
+			errors.map {|e| e**2}.inject(:+)/errors.length
+		end
+
+		def self.activation_function(sum)
+			1.0 / (1.0 + Math.exp(-sum))
+		end
+
+		def initialize
+			@learning_rate = 0.3
+			@momentum = 0.1
+		end
+
+
+		def initialize_layers(sizes)
+			@sizes = sizes
+			@output_layer = @sizes.length - 1
+
+			@biases = []
+			@weights = []
+			@outputs = []
+
+			@deltas = []
+			@changes = []
+			@errors = []
+
+			@sizes.length.times do |layer|
+				size = @sizes[layer]
+
+				@deltas[layer] = Array.new(size) {0}
+				@errors[layer] = Array.new(size) {0}
+				@outputs[layer] = Array.new(size) {0}
+
+				next if layer == 0
+
+				@biases[layer] = Array.new(size) {NeuralNetwork.random_weight}
+				@weights[layer] = Array.new(size)
+				@changes[layer] = Array.new(size)
+
+				size.times do |node|
+					prev_size = @sizes[layer - 1]
+					@weights[layer][node] = Array.new(prev_size) {NeuralNetwork.random_weight}
+					@changes[layer][node] = Array.new(prev_size) {0}
+
+				end
+			end
+		end
+
+		def run(input)
+			input = Brian::Lookup.to_array(@input_lookup, input) if @input_lookup
+
+			output = self.run_input(input)
+
+			output = Brian::Lookup.to_hash(@output_lookup, output) if @output_lookup
+
+			return output
+		end
+
+		def run_input(input)
+			@outputs[0] = input
+
+			@sizes.count.times do |layer|
+				next if layer == 0
+				@sizes[layer].times do |node|
+					weights = @weights[layer][node]
+					sum = @biases[layer][node]
+
+					weights.each_with_index {|w,k| sum += w*input[k]}
+					
+					@outputs[layer][node] = NeuralNetwork.activation_function(sum)
+				end
+
+				input = @outputs[layer]
+			end
+
+
+			return @outputs[@output_layer]
+		end
+
+		def format_data(data)
+			if not data[0][:input].is_a?(Array)
+				if @input_lookup.nil?
+					inputs = data.map {|d| d[:input]}
+					@input_lookup = Brian::Lookup.build_lookup(inputs)
+				end
+
+				data.each do |d|
+					d[:input] = Brian::Lookup.to_array(@input_lookup,d[:input])
+				end
+			end
+
+			if not data[0][:output].is_a?(Array)
+				if @output_lookup.nil?
+					inputs = data.map {|d| d[:output]}
+					@output_lookup = Brian::Lookup.build_lookup(inputs)
+				end
+
+				data.each do |d|
+					d[:output] = Brian::Lookup.to_array(@output_lookup,d[:output])
+				end
+			end
+
+			return data
+		end
+
+		def train(data, options = {})
+			data = self.format_data(data)
+
+			options = ({
+				iterations:20000,
+				error_thresh:0.005,
+				log:false,
+				log_period:10,
+				callback_period:10
+			}).merge(options)
+
+			input_size = data[0][:input].size
+			output_size = data[0][:output].size
+			
+			hidden_sizes = @hidden_sizes
+
+			if hidden_sizes.nil?
+				hidden_sizes = [[3,(input_size.to_f/2).floor].max]
+			end
+
+			sizes = [input_size,hidden_sizes,output_size].flatten
+			self.initialize_layers(sizes)
+
+			error = 1
+
+			iterations = 0
+			options[:iterations].times do |i|
+				sum = 0
+				iterations = i
+				data.each do |d|
+					err = self.train_pattern(d[:input],d[:output])
+					sum += err
+				end
+
+				error = sum/data.count
+
+				if options[:log] and (i % options[:log_period] == 0)
+					puts "iterations:#{i} training_error #{error}"
+				end
+
+				if options[:callback] and (i % options[:callback_period] == 0)
+					options[:callback].call({error:error, iterations:i})
+				end
+
+				break if error <= options[:error_thresh]
+			end
+
+			return {error:error, iterations:iterations}
+		end
+
+
+		def train_pattern(input, target)
+			#Forward propogate
+			self.run_input(input)
+
+			#Back propogate
+			self.calculate_deltas(target)
+			self.adjust_weights()
+
+			error = Brian::NeuralNetwork.mse(@errors[@output_layer])
+
+			return error
+		end
+
+		def calculate_deltas(target)
+			@sizes.length.times do |layer|
+				layer = -(layer+1)
+				@sizes[layer].times do |node|
+					output = @outputs[layer][node]
+					error = 0
+
+					if layer == -1 #Output layer
+						error = (target[node] - output).to_f
+					else
+						deltas = @deltas[layer+1]
+						deltas.each_with_index do |d,k|
+							error += d * @weights[layer+1][k][node]
+						end
+					end
+
+					@errors[layer][node] = error
+					@deltas[layer][node] = error*output*(1.0-output)
+				end
+			end
+		end
+
+		def adjust_weights
+			@sizes.count.times do |layer|
+				next if layer == 0
+				incoming = @outputs[layer-1]
+
+				@sizes[layer].times do |node|
+					delta = @deltas[layer][node]
+
+					incoming.each_with_index do |i,k|
+						change = @changes[layer][node][k]
+
+						change *= @momentum
+						change += @learning_rate * delta * i
+
+						@changes[layer][node][k] = change
+						@weights[layer][node][k] += change
+					end
+
+					@biases[layer][node] += @learning_rate * delta
+				end
+			end
+		end
+
+	end
+end

data/lib/brian/version.rb

@@ -0,0 +1,3 @@
+module Brian
+  VERSION = "0.1.0"
+end

data/spec/hash_spec.rb

@@ -0,0 +1,40 @@
+require 'brian'
+
+describe Brian::NeuralNetwork do
+	describe "Can store and retrieve XOR-network" do
+		before do
+			@net = Brian::NeuralNetwork.new
+			@net.train([
+				{input: [0, 0], output: [0]},
+				{input: [0, 1], output: [1]},
+				{input: [1, 0], output: [1]},
+				{input: [1, 1], output: [0]}])
+		end
+
+		it "Produces identical output" do 
+			net2 = Brian::NeuralNetwork.new_with_hash(@net.to_hash)
+
+			input = [1,0]
+			@net.run(input).should eql net2.run(input)
+		end
+	end
+
+	describe "Can store and retrieve the Colour Contrast-network" do
+		before do
+			@net = Brian::NeuralNetwork.new
+			@net.train([
+				{input: { r: 0.03, g: 0.7, b: 0.5 }, output: { black: 1.0 }},
+	           	{input: { r: 0.16, g: 0.09, b: 0.2 }, output: { white: 1.0 }},
+    	       	{input: { r: 0.5, g: 0.5, b: 1.0 }, output: { white: 1.0 }}])
+		end
+
+
+		it "Produces identical output" do 
+			net2 = Brian::NeuralNetwork.new_with_hash(@net.to_hash)
+
+			input = { r: 1, g: 0.4, b: 0 }
+			@net.run(input).should eql net2.run(input)
+		end
+
+	end
+end

data/spec/lookup_spec.rb

@@ -0,0 +1,19 @@
+require 'brian'
+
+describe Brian::Lookup do
+	it "Build Lookup" do
+		Brian::Lookup.build_lookup([{a: 1}, {b: 6, c: 7}]).should eql({a:0, b:1, c:2})
+	end
+
+	it "Lookup from Hash" do
+		Brian::Lookup.lookup_from_hash({a: 6, b: 7}).should eql({a:0, b:1})
+	end
+
+	it "Hash to Array" do 
+		Brian::Lookup.to_array({a: 0, b: 1}, {a: 6}).should eql([6,0])
+	end
+
+	it "Array to Hash" do 
+		Brian::Lookup.to_hash({a: 0, b: 1}, [6, 7]).should eql({a: 6, b: 7})
+	end
+end

data/spec/neural_network_spec.rb

@@ -0,0 +1,47 @@
+require 'brian'
+
+describe Brian::NeuralNetwork do
+	describe "Can learn XOR" do
+
+		before do
+			@net = Brian::NeuralNetwork.new
+			@net.train([
+				{input: [0, 0], output: [0]},
+				{input: [0, 1], output: [1]},
+				{input: [1, 0], output: [1]},
+				{input: [1, 1], output: [0]}])
+		end
+
+		it "[1,0] => [1]" do
+			@net.run([1, 0]).map {|x| x.round}.should eql([1])
+		end
+
+
+		it "[1,1] => [0]" do
+			@net.run([1, 1]).map {|x| x.round}.should eql([0])
+		end
+
+		it "[0,0] => [0]" do
+			@net.run([0, 0]).map {|x| x.round}.should eql([0])
+		end
+	end
+
+	describe "Can learn the Colour Contrast demo" do
+
+		before do
+			@net = Brian::NeuralNetwork.new
+			@net.train([
+				{input: { r: 0.03, g: 0.7, b: 0.5 }, output: { black: 1.0 }},
+	           	{input: { r: 0.16, g: 0.09, b: 0.2 }, output: { white: 1.0 }},
+    	       	{input: { r: 0.5, g: 0.5, b: 1.0 }, output: { white: 1.0 }}])
+		end
+
+		it "{r:1,g:0.4,b:0} => White" do
+		 	result = @net.run({ r: 1, g: 0.4, b: 0 })
+		 	result[:white].round.should eql(1)
+		 	result[:black].round.should eql(0)
+		end
+
+	end
+
+end

metadata

@@ -0,0 +1,97 @@
+--- !ruby/object:Gem::Specification 
+name: brian
+version: !ruby/object:Gem::Version 
+  hash: 27
+  prerelease: false
+  segments: 
+  - 0
+  - 1
+  - 0
+  version: 0.1.0
+platform: ruby
+authors: 
+- Adam Watkins
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2012-09-23 00:00:00 +01:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 21
+        segments: 
+        - 2
+        - 11
+        version: "2.11"
+  type: :development
+  version_requirements: *id001
+description: A port of the brain.js library, implementing a multilayer perceptron - a neural network for supervised learning.
+email: 
+- adam@stupidpupil.co.uk
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- brian.gemspec
+- lib/brian.rb
+- lib/brian/hash.rb
+- lib/brian/lookup.rb
+- lib/brian/neural_network.rb
+- lib/brian/version.rb
+- spec/hash_spec.rb
+- spec/lookup_spec.rb
+- spec/neural_network_spec.rb
+has_rdoc: true
+homepage: ""
+licenses: 
+- MIT
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Multilayer perceptron (neural network) library.
+test_files: 
+- spec/hash_spec.rb
+- spec/lookup_spec.rb
+- spec/neural_network_spec.rb