associative_memory 0.2.0

data/.rspec

@@ -0,0 +1 @@
+--colour --format documentation

data/.rvmrc

@@ -0,0 +1 @@
+rvm use 1.9.2@associative_memory

data/Gemfile

@@ -0,0 +1,8 @@
+source 'http://rubygems.org'
+gem "rspec"
+gem "rake"
+gem "hoe"
+gem "newgem"
+gem "simplecov"
+gem "guard"
+gem 'guard-rspec'

data/Gemfile.lock

@@ -0,0 +1,50 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    RedCloth (4.2.9)
+    activesupport (2.3.14)
+    diff-lcs (1.1.3)
+    ffi (1.0.11)
+    guard (1.0.1)
+      ffi (>= 0.5.0)
+      thor (~> 0.14.6)
+    guard-rspec (0.7.0)
+      guard (>= 0.10.0)
+    hoe (3.0.1)
+      rake (~> 0.8)
+    multi_json (1.2.0)
+    newgem (1.5.3)
+      RedCloth (>= 4.1.1)
+      activesupport (~> 2.3.4)
+      hoe (>= 2.4.0)
+      rubigen (>= 1.5.3)
+      syntax (>= 1.0.0)
+    rake (0.9.2.2)
+    rspec (2.9.0)
+      rspec-core (~> 2.9.0)
+      rspec-expectations (~> 2.9.0)
+      rspec-mocks (~> 2.9.0)
+    rspec-core (2.9.0)
+    rspec-expectations (2.9.0)
+      diff-lcs (~> 1.1.3)
+    rspec-mocks (2.9.0)
+    rubigen (1.5.8)
+      activesupport (>= 2.3.5, < 3.2.0)
+    simplecov (0.6.1)
+      multi_json (~> 1.0)
+      simplecov-html (~> 0.5.3)
+    simplecov-html (0.5.3)
+    syntax (1.0.0)
+    thor (0.14.6)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  guard
+  guard-rspec
+  hoe
+  newgem
+  rake
+  rspec
+  simplecov

data/Guardfile

@@ -0,0 +1,5 @@
+guard 'rspec', :version => 2, :cli => '--colour --format documentation', :focus => true, :all_on_start => true, :all_after_pass => false, :keep_failed => false do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb')  { "spec" }
+end

data/History.txt

@@ -0,0 +1,12 @@
+
+=== 0.2 2012-04-24
+
+* Completed named interface set for hereoassociative network implementation
+
+=== 0.1 2012-04-24
+
+* Completed heteroassociative neural network implementation
+
+=== 0.0.1 2012-03-27
+
+* Initial development work, module layout, starting on heteroassociative network

data/Manifest.txt

@@ -0,0 +1,14 @@
+.rspec
+.rvmrc
+Gemfile
+Gemfile.lock
+Guardfile
+History.txt
+Manifest.txt
+README.rdoc
+Rakefile
+lib/associative_memory.rb
+lib/associative_memory/network.rb
+spec/associative_memory/network_spec.rb
+spec/associative_memory_spec.rb
+spec/spec_helper.rb

data/README.rdoc

@@ -0,0 +1,129 @@
+# Associative Memory
+
+http://dann.stayskal.com/software/associative_memory
+
+## Description
+
+This is a ruby gem that lets you implement categorization systems with ease.
+
+**Associative memory neural networks** make it easy to identify probable patterns between sets of named data points.  It can be cumbersome to interface with the neural network directly, however, as a typical convergence matrix has a fixed size and training period, which limits how useful they can be to an integrated system.
+
+associative_memory simplifies these kind of machine learning models by offering dynamically configurable input and output sets, and a convergence model that adapts to the inputs you give it each time.  This allows your code to concentrate on extrapolating meaningful patterns rather than juggling bitmasks and transposition matrices.
+
+Under the hood, associative_memory implements a hetero-associative recurrent neural network designed according to Kosko's landmark paper (http://sipi.usc.edu/~kosko/BAM.pdf) establishing the model.  The model then dynamically rebuilds and adapts this network to accomodate new inputs as necessary.
+
+## Synopsis
+
+First, you'll want to tell `associative_memory` what you know about the set of things you're dealing with:
+
+	require 'associative_memory'
+	@animals = AssociativeMemory.new
+
+	@animals.associate([:tail, :fur, :legs, :paws], [:cats, :rats])
+	@animals.associate([:fins, :swimming], 			[:fish])
+	@animals.associate([:tail, :shell], 			[:turtles])
+	@animals.associate([:arms, :legs], 				[:humans])
+	@animals.associate([:swimming], 				[:humans, :rats, :turtles])
+	@animals.associate([:running], 					[:humans, :rats, :cats])
+
+Once you've done that, you can start asking it questions about patterns you've told it about:
+
+	running_things = @animals.describe([:running])
+	[:cats, :rats, :humans].each do |thing|
+		running_things.should include(thing)
+	end
+	@animals.describe([:humans]).should == [:arms, :legs, :running, :swimming]
+	@animals.describe([:swimming]).should == [:rats, :fish, :humans, :turtles]
+	@animals.describe([:tail]).should == [:cats, :rats, :fish, :turtles]
+
+Furthermore, it will be able to extrapolate patterns from data not explicitly taught:
+
+	@animals.describe([:fish]).should include(:tail)
+
+If you have more patterns to input, you can do it at any time:
+
+	@animals.associate([:jumping], [:humans, :rats, :cats])
+	@animals.describe([:humans]).should include(:jumping)
+
+## Installation
+
+When using RVM:
+
+	$ gem install associative_memory
+
+When using Bundler:
+
+	# Add to your Gemfile
+	gem "associative_memory"
+
+	# Then install through Bundler
+	$ bundle install
+
+Otherwise:
+
+	$ sudo gem install associative_memory
+
+## TODO
+
+* Implement auto-associative neural network model (v.0.3)
+* Streamline network class with Matrix rather than Array
+
+## Maintenance
+
+If you would like to help maintain or improve this gem, I welcome your patches. The build environment of this gem is streamlined for test-driven development using bundler, rvm, rspec, and guard.  To get it setup, you'll need to have Ruby Version Manager (http://beginrescueend.com/) installed, then do the following:
+
+	$ git clone git@github.com:danndalf/associative_memory
+	$ cd associative_memory
+	  # ...and accept the .rvmrc
+	  # have RVM build ruby 1.9 if necessary
+	$ gem install bundler
+	$ bundle install
+	$ bundle exec guard start
+
+Once guard starts, it will run through the full test suite.  After any changes are made to the libraries or specs, guard will re-run the relevant tests.  To re-run the full test suite, press enter at tie `> ` prompt in guard.  
+
+After each test run, [simplecov](https://github.com/colszowka/simplecov) will generate a test coverage report in `coverage/index.html`.  This should show 100% coverage across all files when running the full test suite.
+
+If you would like to patch this gem:
+
+* Fork this repository
+* Write your tests
+* Make your changes
+* Once all tests are passing and `simplecov` tells you all files are 100% covered, commit and push your changes
+* Send me a pull request
+* Wait for me to respond
+
+This will help me integrate your patch as quickly and reliably as possible.
+
+If you'd rather report a bug, please [open an issue on github](https://github.com/danndalf/associative_memory/issues).
+
+## Resources
+
+* Support: http://dann.stayskal.com/software/associative_memory
+
+* Source code: http://github.com/danndalf/associative_memory
+
+## License
+
+This module is available under The MIT License.
+
+Copyright (c) 2012 Dann Stayskal <dann@stayskal.com>.
+
+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/Rakefile

@@ -0,0 +1,11 @@
+require 'hoe'
+require 'bundler'
+require 'rspec'
+
+task :test => :spec
+task :default => :spec
+
+Hoe.plugin :newgem
+$hoe = Hoe.spec 'associative_memory' do
+  self.developer 'Dann Stayskal', 'dann@stayskal.com'
+end

data/lib/associative_memory.rb

@@ -0,0 +1,91 @@
+require 'associative_memory/network'
+
+module AssociativeMemory
+
+	VERSION = '0.2.0'
+	class << self
+
+		attr_accessor :associated_pairs, :network, :input_keyspace, :output_keyspace
+
+		def new(options={})
+			self.associated_pairs = []
+			self.input_keyspace = []
+			self.output_keyspace = []
+			return self
+		end
+
+		def associate(inputs=[], outputs=[])
+			existing_input_keyspace_length = self.input_keyspace.length
+			existing_output_keyspace_length = self.output_keyspace.length
+
+			# Determine updated keyspace mapping
+			self.associated_pairs.push([inputs, outputs])
+			self.input_keyspace = self.associated_pairs.map{|pair| pair[0]}.flatten.uniq.sort
+			self.output_keyspace = self.associated_pairs.map{|pair| pair[1]}.flatten.uniq.sort
+			@input_bitmask = self.input_keyspace.map{|element| if inputs.include?(element) then 1 else 0 end }
+			@output_bitmask = self.output_keyspace.map{|element| if outputs.include?(element) then 1 else 0 end }
+
+			# If this new association changes the cardinality of our input or
+			# output pattern space, refresh structure of the network
+			if self.input_keyspace.length != existing_input_keyspace_length || self.output_keyspace.length != existing_output_keyspace_length
+				self.network = AssociativeMemory::Network.new
+				self.associated_pairs.each{|pair|
+					pairwise_input_bitmask = self.input_keyspace.map{|element| if pair[0].include?(element) then 1 else 0 end }
+					pairwise_output_bitmask = self.output_keyspace.map{|element| if pair[1].include?(element) then 1 else 0 end }
+					self.network.learn(pairwise_input_bitmask,pairwise_output_bitmask)
+				}
+			else
+				self.network.learn(@input_bitmask, @output_bitmask)
+			end
+		end
+
+		def describe(vector)
+			description = []
+
+			# Search forward through the input keyspace
+			input_bitmask = self.input_keyspace.map{|input_key| if vector.include?(input_key) then 1 else 0 end }
+			if input_bitmask.include?(1)
+				convergence_bitmask = self.network.converge_and_bitmask_input(input_bitmask)
+				self.output_keyspace.each_with_index do |output_key, index|
+					if convergence_bitmask[index] == 1
+						description.push(output_key)
+					end
+				end
+			end
+
+			# Search backwards through the output keyspace
+			output_bitmask = self.output_keyspace.map{|output_key| if vector.include?(output_key) then 1 else 0 end }
+			if output_bitmask.include?(1)
+				convergence_bitmask = self.network.converge_and_bitmask_output(output_bitmask)
+				convergence_vector = self.network.converge_output(output_bitmask)
+				self.input_keyspace.each_with_index do |input_key, index|
+					if convergence_bitmask[index] == 1
+						description.push(input_key)
+					end
+				end
+			end
+
+			return description.sort.uniq
+		end
+
+		def valid?
+			return self.associated_pairs.length > 0 &&self.input_keyspace.length > 0 &&self.output_keyspace.length > 0 && self.network.valid?
+		end
+
+		def pretty_inspect
+			"associative_memory object: #{self.object_id}\n\n" +
+			"associated_pairs\n" + 
+			"----------------\n" + 
+			self.associated_pairs.map{|a| a.inspect}.join("\n") + "\n\n" +
+			"input_keyspace\n" + 
+			"--------------\n" + 
+			self.input_keyspace.inspect + "\n\n" +
+			"output_keyspace\n" + 
+			"---------------\n" + 
+			self.output_keyspace.inspect + "\n\n" +
+			"convergence network\n" +
+			"-------------------\n" +
+			self.network.matrix.map{|a| a.inspect}.join("\n") + "\n\n"
+		end
+	end
+end

data/lib/associative_memory/network.rb

@@ -0,0 +1,62 @@
+require 'matrix'
+
+module AssociativeMemory
+	class Network
+
+		attr_accessor :matrix
+
+		def initialize(options={})
+			@matrix = []
+		end
+
+		def empty?
+			self.matrix.length == 0
+		end
+
+		def valid?
+			self.matrix.length > 0
+		end
+		
+		def learn(input, output)
+			input_buffer = []
+			output_buffer = []
+			input.each_with_index do |scalar, index|
+				input_buffer[index] = 2 * scalar - 1
+			end
+			output.each_with_index do |scalar, index|
+				output_buffer[index] = 2 * scalar - 1
+			end
+			input.each_with_index do |input_scalar, input_index|
+				output.each_with_index do |output_scalar, output_index|
+					self.matrix[input_index] ||= []
+					self.matrix[input_index][output_index] ||= 0
+					self.matrix[input_index][output_index] += input_buffer[input_index] * output_buffer[output_index]
+				end
+			end
+		end
+
+		def converge_input(input)
+			output_vector = Matrix.row_vector(input) * Matrix.rows(self.matrix)
+			return output_vector.row(0).to_a
+		end
+
+		def converge_and_bitmask_input(input)
+			bitmask(converge_input(input))
+		end
+
+		def converge_output(output)
+			input_vector = Matrix.row_vector(output) * Matrix.rows(self.matrix).transpose
+			return input_vector.row(0).to_a
+		end
+
+		def converge_and_bitmask_output(output)
+			bitmask(converge_output(output))
+		end
+
+		def bitmask(vector)
+			vector.map do |element|
+				if element < 0 then 0 else 1 end
+			end
+		end
+	end
+end

data/spec/associative_memory/network_spec.rb

@@ -0,0 +1,64 @@
+require 'spec_helper'
+
+describe AssociativeMemory::Network do
+	let(:training_data) {[
+		{:input => [1, 0, 1, 0, 1, 0], :output => [1, 1, 0, 0], :converged_output => [5, 7, -5, -7], :converged_input => [4, -4, 4, -4, 4, -4] },
+		{:input => [1, 1, 1, 0, 0, 0], :output => [0, 1, 1, 0], :converged_output => [-1, 5, 1, -5], :converged_input => [2, 2, 2, -2, -2, -2] },
+		{:input => [0, 1, 0, 1, 0, 1], :output => [0, 0, 1, 1], :converged_output => [-5, -7, 5, 7], :converged_input => [-4, 4, -4, 4, -4, 4] }
+	]}
+	describe "a new associative memory network" do
+		before do
+			@network = AssociativeMemory::Network.new
+		end
+		it "should be a kind of associative memory network" do
+			@network.should be_a_kind_of(AssociativeMemory::Network)
+		end
+		it "should be empty" do
+			@network.empty?.should be_true
+		end
+		it "should not be valid until we learn a pattern" do
+			@network.valid?.should be_false
+		end
+		it "should be valid once we learn a pattern" do
+			@network.learn(training_data[0][:input], training_data[0][:output])
+			@network.valid?.should be_true
+		end
+	end
+
+	describe "training a network" do
+		before do
+			@network = AssociativeMemory::Network.new
+		end
+		it "should build a valid convergence matrix from a single data point" do
+			@network.learn(training_data[0][:input], training_data[0][:output])
+			@network.matrix.should == [[1, 1, -1, -1], [-1, -1, 1, 1], [1, 1, -1, -1], [-1, -1, 1, 1], [1, 1, -1, -1], [-1, -1, 1, 1]]
+		end
+		it "should build a valid convergence matrix from all data" do
+			training_data.each do |pair|
+				@network.learn(pair[:input], pair[:output])
+			end
+			@network.matrix.should == [[1, 3, -1, -3], [-3, -1, 3, 1], [1, 3, -1, -3], [-1, -3, 1, 3], [3, 1, -3, -1], [-1, -3, 1, 3]]
+		end
+	end
+
+	describe "converging a network" do
+		before do
+			@network = AssociativeMemory::Network.new
+			training_data.each do |pair|
+				@network.learn(pair[:input], pair[:output])
+			end
+		end
+		it "should rebuild all available output data from learned input data" do
+			training_data.each do |pair|
+				@network.converge_input(pair[:input]).should == pair[:converged_output]
+				@network.converge_and_bitmask_input(pair[:input]).should == pair[:output]
+			end
+		end
+		it "should rebuild all available input data from learned output data" do
+			training_data.each do |pair|
+				@network.converge_output(pair[:output]).should == pair[:converged_input]
+				@network.converge_and_bitmask_output(pair[:output]).should == pair[:input]
+			end
+		end
+	end
+end

data/spec/associative_memory_spec.rb

@@ -0,0 +1,75 @@
+require 'spec_helper'
+
+describe AssociativeMemory do
+	
+	it "should have a valid version number" do
+		AssociativeMemory::VERSION.should match(/\d+\.\d+\.\d+/)
+	end
+
+	describe "providing some association pairs" do
+		before do
+			@animals = AssociativeMemory.new
+			@animals.associate([:tail, :shell], [:turtles])
+			@animals.associate([:arms, :legs], [:humans])
+		end
+		it "should construct a valid memory" do
+			@animals.valid?.should be_true
+		end
+	end
+
+	describe "describing a memory" do
+		before do
+			@animals = AssociativeMemory.new
+			@animals.associate([:tail, :fur, :legs, :paws], [:cats, :rats])
+			@animals.associate([:fins, :swimming], 			[:fish])
+			@animals.associate([:tail, :shell], 			[:turtles])
+			@animals.associate([:arms, :legs], 				[:humans])
+			@animals.associate([:swimming], 				[:humans, :rats, :turtles])
+			@animals.associate([:running], 					[:humans, :rats, :cats])
+		end
+		it "should reconstruct things statically trained" do
+			running_things = @animals.describe([:running])
+			[:cats, :rats, :humans].each do |thing|
+				running_things.should include(thing)
+			end
+		end
+		it "should reconstruct things dynamically trained (over multiple learnings)" do
+			@animals.describe([:humans]).should == [:arms, :legs, :running, :swimming]
+			@animals.describe([:swimming]).should == [:fish, :humans, :rats, :turtles]
+			@animals.describe([:tail]).should == [:cats, :fish, :rats, :turtles]
+		end
+		it "should reconstruct generalizations from things not explicitly trained" do
+			@animals.describe([:fish]).should include(:tail)
+		end
+		it "should dynamically re-associate patterns from existing data when further trained" do
+			@animals.associate([:jumping], [:humans, :rats])
+			@animals.describe([:humans]).should include(:jumping)
+		end
+	end
+
+	describe "data structure inspection" do
+		before do
+			@animals = AssociativeMemory.new
+			@animals.associate([:tail, :fur, :legs, :paws], [:cats, :rats])
+			@animals.associate([:fins, :swimming], 			[:fish])
+			@inspection = @animals.pretty_inspect
+		end
+		it "should include labels of pairs, keyspaces, and the convergence network" do
+			@inspection.should match /associated_pairs/
+			@inspection.should match /input_keyspace/
+			@inspection.should match /output_keyspace/
+			@inspection.should match /convergence network/
+		end
+		it "should include the associative_memory object_id" do
+			@inspection.should match /associative_memory object: \d*/
+		end
+		it "should include output of trained keyspaces" do
+			@inspection.should match /[:fins, :fur, :legs, :paws, :swimming, :tail]/
+			@inspection.should match /[:cats, :rats, :fish]/
+		end
+		it "should include output of the convergence network" do
+			@inspection.should match /[-2, -2, 2]/
+			@inspection.should match /[2, 2, -2]/
+		end
+	end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,7 @@
+#encoding: utf-8
+
+require 'simplecov'
+SimpleCov.start
+
+require 'associative_memory'
+require 'rspec'

metadata

@@ -0,0 +1,117 @@
+--- !ruby/object:Gem::Specification
+name: associative_memory
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+  prerelease: 
+platform: ruby
+authors:
+- Dann Stayskal
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-04-25 00:00:00.000000000Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rdoc
+  requirement: &16462500 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.10'
+  type: :development
+  prerelease: false
+  version_requirements: *16462500
+- !ruby/object:Gem::Dependency
+  name: newgem
+  requirement: &16462040 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 1.5.3
+  type: :development
+  prerelease: false
+  version_requirements: *16462040
+- !ruby/object:Gem::Dependency
+  name: hoe
+  requirement: &16461600 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: *16461600
+description: ! 'This is a ruby gem that lets you implement categorization systems
+  with ease.
+
+
+  **Associative memory neural networks** make it easy to identify probable patterns
+  between sets of named data points.  It can be cumbersome to interface with the neural
+  network directly, however, as a typical convergence matrix has a fixed size and
+  training period, which limits how useful they can be to an integrated system.
+
+
+  associative_memory simplifies these kind of machine learning models by offering
+  dynamically configurable input and output sets, and a convergence model that adapts
+  to the inputs you give it each time.  This allows your code to concentrate on extrapolating
+  meaningful patterns rather than juggling bitmasks and transposition matrices.
+
+
+  Under the hood, associative_memory implements a hetero-associative recurrent neural
+  network designed according to Kosko''s landmark paper (http://sipi.usc.edu/~kosko/BAM.pdf)
+  establishing the model.  The model then dynamically rebuilds and adapts this network
+  to accomodate new inputs as necessary.'
+email:
+- dann@stayskal.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- History.txt
+- Manifest.txt
+- README.rdoc
+files:
+- .rspec
+- .rvmrc
+- Gemfile
+- Gemfile.lock
+- Guardfile
+- History.txt
+- Manifest.txt
+- README.rdoc
+- Rakefile
+- lib/associative_memory.rb
+- lib/associative_memory/network.rb
+- spec/associative_memory/network_spec.rb
+- spec/associative_memory_spec.rb
+- spec/spec_helper.rb
+- .gemtest
+homepage: http://dann.stayskal.com/software/associative_memory
+licenses: []
+post_install_message: 
+rdoc_options:
+- --main
+- README.rdoc
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: associative_memory
+rubygems_version: 1.8.15
+signing_key: 
+specification_version: 3
+summary: This is a ruby gem that lets you implement categorization systems with ease
+test_files: []