associative_memory

= 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 implementation 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 dynamic input and output sets. This allows your code to concentrate on extrapolating meaningful patterns rather than juggling bitmasks and transposition matrices.

== Status

{}[http://travis-ci.org/danndalf/associative_memory] {}[https://gemnasium.com/danndalf/associative_memory] {}[https://coveralls.io/r/danndalf/associative_memory]

== 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]

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)

== Requirements

This gem is tested and functional on the following Ruby interpreters:

• MRE Ruby 1.9.2
• MRE Ruby 1.9.3
• jRuby 1.9 mode

== 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 detailed descriptions (likelihood of set membership based on non-bitmasked transpose products with the convergence matrix) (v.0.3)
• Streamline network class with Matrix rather than Array (v.0.4)
• Implement auto-associative neural network model (v.0.5)

== Maintenance

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 module then dynamically rebuilds and adapts this network to accomodate new inputs as they're presented.

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 [e-mail]: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 the guard prompt.

After each test run, 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 (regression or unit tests)
• Make your changes
• Once all tests are passing and all files have full test coverage, 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.

== Resources

• Support: http://dann.stayskal.com/software/associative_memory

• Source: http://github.com/danndalf/associative_memory

• Bug Tracker: https://github.com/danndalf/associative_memory/issues

== License

This module is available under The MIT License.

Copyright (c) 2012 Dann Stayskal [e-mail].

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 rthe 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.