cabalist 0.0.1 → 0.0.2

data/.gitignore

@@ -0,0 +1,4 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*

data/.travis.yml

@@ -0,0 +1,4 @@
+language: ruby
+rvm:
+  - 1.9.2
+  - 1.9.3

data/Gemfile

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

data/README.md

@@ -0,0 +1,121 @@
+Introduction to Cabalist [![Build Status](https://secure.travis-ci.org/marcinwyszynski/cabalist.png?branch=master)](http://travis-ci.org/marcinwyszynski/cabalist)
+------------------------
+
+Cabalist is conceived as a simple way of adding some smarts (machine learning capabilities) to your Ruby on Rails models without having to dig deep into mind-boggling AI algorithms. Using it is meant to be as straightforward as adding a few lines to your existing code and running a Rails generator or two.
+
+Installation
+------------
+
+First and foremost add Cabalist to your Gemfile as dependency:
+
+```ruby
+gem 'cabalist'
+```
+
+... and run Bundler command (bundle) to install it and it's own dependencies. Once that is sorted out you will want to run an installer - a generator that comes with Cabalist:
+
+```bash
+$ rails g cabalist:install
+```
+
+Running this command will create a new initializer (cabalist.rb) in your config/initializers directory, copy gem assets to the public folder and add a route to the GUI. GUI is just one way of interacting with Cabalist so if you do not need it, you may simply remove the route and use Cabalist capabilities through the API it provides.
+
+Basic setup
+-----------
+
+In order to add Cabalist capabilities mechanism to your model, you will need to specify which attributes should be used as features (predictors) by a machine learning algorithm and what the class variable for the model should be - that is which attribute Cabalist try to infer. You would do it like this:
+
+```ruby
+class Cat < ActiveRecord::Base
+  # attributes: name, color, gender, good
+  acts_as_cabalist :features       => [:color, :gender],
+                   :class_variable => :good
+end
+```
+
+Before you can use the power of AI, you will have to run another generator that will generate a migration adding a timestamp field to this model - autoclassified_at. This is used to distinguish records that you have clasified yourself from those classified by the algorithm. Later you can use this distinction to validate your model - see if it performs to your satisfaction. You run the generator like this:
+
+```bash
+$ rails g cabalist:classifier <Class>
+```
+
+...where <Class> should be the name of the class you want to enable Cabalist for. This very generator will also ask whether you want this classifier to also be accessible through the GUI. If you don't use GUI this won't bother you at all. If you do you can still choose what it will expose to the user. It can always be manipulated directly through config/initializers/cabalist.rb file. The attribute of the configuration you should be looking for is called frontend_classes.
+
+Using Cabalist
+--------------
+
+Depending on the amount of data to crunch, creating a prediction model may well take a while. The good thing is that this happens only once for each model as once computed, the model is stored in LevelDB (local key-value store).
+
+Now that the Cabalist has set up it's shop, all Cabalist-enabled models gain access to two methods - classify and classify!. The first method will infer the value of the attribute designated as a class variable:
+
+```ruby
+cat = Cat::new(:name => 'Filemon', :color => 'white', :gender => 'M')
+cat.classify
+=> 'y' # ... which means Cabalist thinks this cat is good
+```
+
+The latter method will set the class variable field to the predicted value and return object instance (self).
+
+```ruby
+cat = Cat::new(:name => 'Filemon', :color => 'white', :gender => 'M')
+cat.classify!
+=> <Cat:0x00000101433f58 @name="Filemon", @color="white", @gender="M", @good="y">
+```
+
+Defaults explained
+------------------
+
+By default, the collection Cablist is going to load in order to build a prediction data set is the result of 'manually_classified' scope of the Cabalist-enabled class. This scope is provided for you by Cabalist and looks at your class variable name (whether it is set) and at the autoclassified_at attribute (whethet it is nil). Still, you may want to have a very different idea what data should be used to train your model and you can create an appropriate class method to gather it. You pass that method name as a symbol to :collection option of the act_as_cabalist method. Like so:
+
+```ruby
+class Cat < ActiveRecord::Base
+  # attributes: name, color, gender, good
+  acts_as_cabalist :features       => [:color, :gender],
+                   :class_variable => :good,
+                   :collection     => :cats_i_care_about
+end
+```
+
+The other thing you can change is the algorithm used for generating predictions. By default Cabalist uses [ID3](http://en.wikipedia.org/wiki/ID3_algorithm), a decision tree learning algorithm - a rather arbitrary choice, mind you. You can easily change it to any of the following algorithms:
+- :hyperpipes for [Hyperpipes](http://code.google.com/p/ourmine/wiki/HyperPipes)
+- :ib1 for [Simple Instance Based Learning](http://en.wikipedia.org/wiki/Instance-based_learning)
+- :id3 for [Iterative Dichotomiser 3](http://en.wikipedia.org/wiki/ID3_algorithm)
+- :one_r for [One Attribute Rule](http://www.soc.napier.ac.uk/~peter/vldb/dm/node8.html)
+- :prism for [PRISM](http://www.sciencedirect.com/science/article/pii/S0020737387800032)
+- :zero_r for [ZeroR](http://chem-eng.utoronto.ca/~datamining/dmc/zeror.htm)
+
+All algorithms come from an excellent [ai4r](https://github.com/SergioFierens/ai4r) gem. You can choose a specific algorithm to use by your Cabalist model by passing one of the options mentioned above to the :algorithm option like so:
+
+```ruby
+class Cat < ActiveRecord::Base
+  # attributes: name, color, gender, good
+  acts_as_cabalist :features       => [:color, :gender],
+                   :class_variable => :good,
+                   :algorithm      => :prism
+end
+```
+
+You can use different algorithms in different models and I would encourage you to give each one a go - perhaps except for ZeroR which is only really good for benchmarking (all it does is return the most popular result of a class variable).
+
+Helping your Cabalist
+---------------------
+
+So far we've used raw data, derived directly from attributes in your model. You may want to pre-process your data before you pass it to Cabalist. Please remember that you know your domain best and the more smarts you put into AI, the more smarts it will throw back at you. So let's imagine that instead of passing the color attribute directly, we may want to have a method which will tell us whether the color is light or dark - presumably this has something to do with a cat's character:
+
+```ruby
+class Cat < ActiveRecord::Base
+  # attributes: name, color, gender, good
+  acts_as_cabalist( :features       => [:light_or_dark, :gender],
+                    :class_variable => :good )
+
+  def light_or_dark
+    if %w(white yellow orange grey).include?(color)
+      'light'
+    else
+      'dark'
+    end
+  end
+end
+```
+
+Ok, so much for now. Happy categorizing :)

data/Rakefile

@@ -0,0 +1,17 @@
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+desc 'Default: run specs.'
+task :default => :spec
+
+desc "Run specs"
+RSpec::Core::RakeTask.new do |t|
+  t.pattern = "./spec/**/*_spec.rb"
+end
+
+desc "Generate code coverage"
+RSpec::Core::RakeTask.new(:coverage) do |t|
+  t.pattern = "./spec/**/*_spec.rb"
+  t.rcov = true
+  t.rcov_opts = ['--exclude', 'spec']
+end

data/cabalist.gemspec

@@ -0,0 +1,42 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "cabalist/version"
+
+Gem::Specification.new do |s|
+  s.name        = "cabalist"
+  s.version     = Cabalist::VERSION
+  s.authors     = ["Marcin Wyszynski"]
+  s.email       = ["marcin.pixie@gmail.com"]
+  s.homepage    = "http://github.com/marcinwyszynski/cabalist"
+  s.summary     = %q{Minimum setup machine learning (classification) library for Ruby on Rails applications.}
+  s.description = <<-EOF
+Cabalist is conceived as a simple way of adding some smarts 
+(machine learning capabilities) to your Ruby on Rails models 
+without having to dig deep into mind-boggling AI algorithms. 
+Using it is meant to be as straightforward as adding a few 
+lines to your existing code and running a Rails generator or two.
+  EOF
+
+  s.rubyforge_project = "cabalist"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+  
+  # Gem dependencies
+  s.add_dependency('ai4r')
+  s.add_dependency('haml',     '>= 3.0')
+  s.add_dependency('kaminari', '>= 0.13.0')
+  s.add_dependency('leveldb-ruby')
+  s.add_dependency('padrino-helpers')
+  s.add_dependency('rake')
+  s.add_dependency('sinatra')
+  
+  # Gem development dependencies
+  s.add_development_dependency('activerecord')
+  s.add_development_dependency('rspec')
+  s.add_development_dependency('sqlite3')
+  s.add_development_dependency('with_model')
+  
+end

data/lib/cabalist.rb

@@ -1,2 +1,13 @@
-require File.dirname(__FILE__) +  '/cabalist/manager'
-require File.dirname(__FILE__) +  '/cabalist/object_hooks'
+require "cabalist/version"
+require "cabalist/configuration"
+require "cabalist/frontend"
+require "cabalist/model_additions"
+require "cabalist/railtie" if defined? Rails
+
+module Cabalist
+  
+  def self.config
+    yield Cabalist::Configuration.instance
+  end
+  
+end

data/lib/cabalist/configuration.rb

@@ -0,0 +1,20 @@
+require 'leveldb'
+require 'singleton'
+
+module Cabalist
+  class Configuration
+    
+    include Singleton
+    
+    attr_accessor :db_path, :frontend_classes
+    
+    def initialize
+      self.frontend_classes = []
+    end
+    
+    def database
+      LevelDB::DB::new(db_path)
+    end
+    
+  end
+end

data/lib/cabalist/frontend.rb

@@ -0,0 +1,111 @@
+require 'haml'
+require 'kaminari/sinatra'
+require 'padrino-helpers'
+require 'sinatra/base'
+
+module Cabalist
+  class Frontend < Sinatra::Base
+    
+    PER_PAGE = 25
+    
+    before do
+      @classes  = Cabalist::Configuration.instance.frontend_classes
+      @app_name = begin
+        ::Rails.root.to_s.split('/').last.humanize.titlecase
+      rescue
+        'Test Rails Application'
+      end
+    end
+    
+    # Index page, shows a dashboard and links to classifiers.
+    get '/' do
+      haml :index
+    end
+    
+    # List all (classified and non-classified) records for <class_name>.
+    get "/:class_name/all/?:page?" do
+      page = params[:page].to_i < 1 ? 1 : params[:page].to_i
+      klass = params[:class_name].titleize.constantize
+      @collection = klass::page(page).per(PER_PAGE)
+      haml :classifier, 
+           :locals => { :klass => klass,
+                        :page  => page,
+                        :scope => 'all',
+                        :total => klass.count }
+    end
+
+    # List non-classified records for <class_name>.
+    get "/:class_name/none/?:page?" do
+      klass = params[:class_name].titleize.constantize
+      page = params[:page].to_i < 1 ? 1 : params[:page].to_i
+      @collection = klass::not_classified \
+                    .page(page).per(PER_PAGE)
+      haml :classifier, 
+           :locals => { :klass => klass,
+                        :page  => page,
+                        :scope => 'none',
+                        :total => klass::not_classified.count }
+    end
+
+    # List manually classified records for <class_name>
+    get "/:class_name/manual/?:page?" do
+      klass = params[:class_name].titleize.constantize
+      page = params[:page].to_i < 1 ? 1 : params[:page].to_i
+      @collection = klass::manually_classified \
+                    .page(page).per(PER_PAGE)
+      haml :classifier, 
+           :locals => { :klass => klass,
+                        :page  => page,
+                        :scope => 'manual',
+                        :total => klass::manually_classified.count }
+    end
+    
+    # List automatically classified records for <class_name>
+    get "/:class_name/auto/?:page?" do
+      klass = params[:class_name].titleize.constantize
+      page = params[:page].to_i < 1 ? 1 : params[:page].to_i
+      @collection = klass::auto_classified. \
+                    page(page).per(PER_PAGE)
+      haml :classifier, 
+           :locals => { :klass => klass,
+                        :page  => page,
+                        :scope => 'auto',
+                        :total => klass::auto_classified.count }
+    end
+    
+    # Set the value of class variable for an object
+    # of <class_name> with ID <id>
+    post "/:class_name/teach/:id" do
+      klass = params[:class_name].titleize.constantize
+      obj = klass::find(params[:id])
+      if params[:classification_freeform].empty?
+        new_class = params[:classification]
+      else
+        new_class = params[:classification_freeform]
+      end
+      obj.teach(new_class)
+      if obj.save
+        redirect back
+      else
+        'failure'
+      end
+    end
+    
+    # Automatically classify the object of class
+    # <class_name> with ID <id>
+    post "/:class_name/autoclassify/:id" do
+      klass = params[:class_name].titleize.constantize
+      obj = klass::find(params[:id])
+      obj.save if obj.classify!
+      redirect back
+    end
+    
+    # Rebuild the model used for classification
+    post "/:class_name/retrain" do
+      klass = params[:class_name].titleize.constantize
+      klass::train_model
+      redirect back
+    end
+    
+  end
+end

data/lib/cabalist/model_additions.rb

@@ -0,0 +1,127 @@
+require 'ai4r'
+
+module Cabalist
+  module ModelAdditions
+    
+    def acts_as_cabalist(options = {})
+      
+      # Make sure that all required options are set
+      raise 'No features specified' \
+          unless options.has_key?(:features)
+      raise 'Expecting an Array of features' \
+          unless options[:features].instance_of?(Array)
+      raise 'No class variable specified' \
+          unless options.has_key?(:class_variable)
+
+      # Set some sensible defaults for other options, if required
+      collection = options[:collection] || :manually_classified
+      algorithm  = options[:algorithm]  || :id3
+      
+      # Select an algorithm for the classifier
+      classifier = case algorithm
+                   when :hyperpipes then ::Ai4r::Classifiers::Hyperpipes
+                   when :ib1        then ::Ai4r::Classifiers::IB1
+                   when :id3        then ::Ai4r::Classifiers::ID3
+                   when :one_r      then ::Ai4r::Classifiers::OneR
+                   when :prism      then ::Ai4r::Classifiers::Prism
+                   when :zero_r     then ::Ai4r::Classifiers::ZeroR
+                   else raise 'Unknown algorithm provided'
+                   end
+      
+      # Create scopes
+      scope :manually_classified,
+          where("autoclassified_at IS NULL AND %s IS NOT NULL" %
+          options[:class_variable])
+      scope :auto_classified,
+          where("autoclassified_at IS NOT NULL AND %s IS NOT NULL" %
+          options[:class_variable])
+      scope :not_classified,
+          where("autoclassified_at IS NULL AND %s IS NULL" %
+          options[:class_variable])
+
+      # Return object as an Array of features
+      send(:define_method, :get_features, lambda {
+        options[:features].map { |f| self.send(f) }
+      })
+      
+      # Return the value of a class variable
+      send(:define_method, :get_class_variable, lambda {
+        self.send(options[:class_variable])
+      })
+      
+      # Set the value of the class variable
+      send(:define_method, :set_class_variable, lambda { |c|
+        self.send("#{options[:class_variable]}=".to_sym, c) or self
+      })
+      
+      # Return an Array of feature names (attributes/methods)
+      send(:define_singleton_method, :get_feature_names, lambda {
+        options[:features]
+      })
+      
+      # Return the name of a class variable
+      send(:define_singleton_method, :get_class_variable_name, lambda {
+        options[:class_variable]
+      })
+      
+      # Build a prediction model from scratch
+      send(:define_singleton_method, :build_model, lambda {
+        classifier::new.build(
+          Ai4r::Data::DataSet::new({
+            :data_items  => send(collection).map do |el| 
+              el.get_features.push(el.get_class_variable)
+            end,
+            :data_labels => get_feature_names + [get_class_variable_name]
+          })
+        )
+      })
+      
+      # Build a prediction model and store it in the LevelDB
+      send(:define_singleton_method, :train_model, lambda {
+        _model = build_model
+        Cabalist::Configuration.instance.database.put(name,
+            Marshal::dump(_model))
+        return _model
+      })
+      
+      # Return prediction model for the class
+      send(:define_singleton_method, :classifier, lambda {
+        _stored = Cabalist::Configuration.instance.database.get(self.name)
+        return _stored ? Marshal.load(_stored) : train_model
+      })
+
+      # Show possible values for the classification.
+      define_singleton_method(
+        :class_variable_domain,
+        lambda { self.classifier.data_set.build_domain(-1).to_a }
+      )
+    
+      # Create a 'classify' method which will provide a classification
+      # for any new object.
+      send(:define_method, :classify, lambda {
+        begin
+          self.class::classifier.eval(get_features)
+        rescue
+          nil
+        end
+      })
+  
+      # Create a 'classify!' method which will get a classification
+      # for any new object and apply it to the current instance.
+      send(:define_method, :classify!, lambda {
+        set_class_variable(classify)
+        self.autoclassified_at = DateTime::now
+      })
+      
+      # Create a 'teach' method which will manually set the classificaiton
+      # and set the autoclassification timestamp to nil so that the new entry
+      # can be treated as basis for learning.
+      send(:define_method, :teach, lambda { |new_class|
+        set_class_variable(new_class)
+        self.autoclassified_at = nil
+      })
+
+    end
+    
+  end
+end