fathom 0.2.1 → 0.2.2

data/README.md

@@ -1,8 +1,8 @@
 Fathom
-------
+======
 
 Introduction
-============
+------------
 
 This is a library for decision support.  It is useful for recording various types of information, and then combining it in useful ways.  As of right now, it's not very useful, but I'm actively working on it again.  
 
@@ -22,8 +22,8 @@ Setting up the data and models starts with a decoupled Ruby library.  I'll give
 
 Keeping the data and models in context is more of a user interface question, which I'll build in another library.  I'm considering hosting that solution myself and just making it available publicly.  We'll see after all the core ideas are gathered.
 
-Usage
-=====
+Fathom Basics
+-------------
 
 Enrico Fermi [said](http://www.lucidcafe.com/library/95sep/fermi.html):
     There are two possible outcomes: if the result confirms the hypothesis, then you've made a measurement. 
@@ -113,6 +113,153 @@ To use imported data in a ValueDescription, just reference this knowledge base:
       ...
     end
 
+Serial Agent Based Modeling
+---------------------------
+
+I have added some basic support for Agent Based Modeling (ABM).  Right now, this only supports serial simulations.  I will be adding an Agent Cluster, which will allow us to run large simulations asynchronously using EventMachine.  Until then, here's a really simple example of how to do things. 
+
+First, let's create a couple agents, a Cola and a Consumer:
+
+    class Cola < Agent
+      property :sweetness
+      property :number_sold
+
+      def on_purchase(consumer)
+        self.number_sold += 1
+        log_purchase
+      end
+
+      def on_tick(simulation)
+        self.sweetness = suggest_sweetness
+      end
+
+      def inspect
+        "Cola: sweetness: #{self.sweetness}, sales: #{self.number_sold}"
+      end
+
+      protected
+
+        # This is where the fun is as well.  This is an admittedly poor suggestion engine.
+        def suggest_sweetness
+          case purchases.length
+          when *(0..10).to_a
+            self.node_for_sweetness.rand
+          when *(10..50).to_a
+            (self.node_for_sweetness.rand * 0.4) + 
+            (average_purchase_sweetness * 0.6)
+          when *(50..250).to_a
+            (self.node_for_sweetness.rand * 0.2) + 
+            (average_purchase_sweetness * 0.8)
+          else
+            (self.node_for_sweetness.rand * 0.05) + 
+            (average_purchase_sweetness * 0.95)
+          end
+        end
+
+        def average_purchase_sweetness
+          purchases.inject(0.0) {|s, e| s += e}  / purchases.length
+        end
+
+        def log_purchase
+          purchases << sweetness
+        end
+
+        def purchases
+          @purchases ||= []
+        end
+    end
+
+    class Consumer < Agent
+      property :sweetness_preference
+
+      attr_reader :simulation
+
+      def on_tick(simulation)
+        @simulation ||= simulation
+        purchase_cola
+      end
+
+      def inspect
+        "Consumer: preferred sweetness: #{self.sweetness_preference}"
+      end
+
+      protected
+        def agents_using_purchase
+          @agents_using_purchase ||= simulation.agents_using_purchase
+        end
+
+        # This is where all the fun happens.
+        def purchase_cola
+          if rand < 0.1
+            agents_using_purchase.rand.on_purchase(self)
+          else
+            distances = agents_using_purchase.map {|agent| [agent, (self.sweetness_preference - agent.sweetness).abs] }
+            sorted_distances = distances.sort {|a, b| a.last <=> b.last }
+            purchased = sorted_distances.first.first
+            purchased.on_purchase(self)
+          end
+        end
+    end
+
+Agents need to do just a few things:
+
+* define their properties 
+* define which events they listen to
+* define the behavior we're after for each event
+
+Properties can be whatever you're after.  Usually, these are seeded with some knowledge that we're working on in the knowledge base.  Declaring a property gives us a getter and a setter for that property, as well as access to the seed objects we use when setting up the agent.
+
+Events are setup by defining a method starting with on_.  A consumer responds to on_tick, and the cola responds to on_tick and on_purchase.  We setup events with this convention so that it's a little easier to coordinate the traffic amongst the agents and between the agents and the simulation.  When we start using EventMachine for agent clusters, it will be more important to have this interface explicitly defined like this so that things don't get confused.
+
+The underlying behavior is where we can have a lot of fun.  We can start adopting reinforcement learning techniques, or mimic real-world interactions.  For this example, I had the consumer purchase some cola at every tick.  Right now, it optimizes for the cola that's nearest its preference for sweetness.  You may imagine how fun this would get to introduce different types of consumers, or start mimicking a satisficing algorithm (allow the consumers to make a choice that's good enough, rather than optimal).  We could start adding budgets, ages, and proximity to the cola.  Once the behaviors and properties are setup, models can be iterated over extensively until the system dynamics are thoroughly explored, or even some prognostic value begins to emerge from the experiments.
+
+To show the whole example, let me give you some configuration data I stored in a YAML file:
+
+    :american_consumer_sweetness_preference:
+      hard_lower_bound: 0
+      hard_upper_bound: 1
+      min: 0.2
+      max: 0.3
+      name: American Consumer Sweetness Preference
+
+    :cola_sweetness_range:
+      hard_lower_bound: 0
+      hard_upper_bound: 1
+    
+Also, here is the actual simulation:
+
+    require 'rubygems'
+    require 'fathom'
+    require 'cola'
+    require 'consumer'
+
+    YAMLImport.import(File.expand_path('nodes.yml'))
+
+    @rb_cola = Cola.new(:sweetness => Fathom.kb[:cola_sweetness_range], :number_sold => 0)
+    @ruby_cola = Cola.new(:sweetness => Fathom.kb[:cola_sweetness_range], :number_sold => 0)
+    @american_consumer = Consumer.new(
+      :sweetness_preference => Fathom.kb[:american_consumer_sweetness_preference], 
+      :budget => Fathom.kb[:american_cola_budget]
+    )
+
+    @simulation = TickSimulation.new(@rb_cola, @ruby_cola, @american_consumer)
+    @simulation.process(1_000)
+    puts @american_consumer.inspect, @rb_cola.inspect, @ruby_cola.inspect
+    
+The output from this experiment looks like this:
+
+    demo_abm : ruby sim.rb 
+    Consumer: preferred sweetness: 0.258095065252885
+    Cola: sweetness: 0.362263199218971, sales: 626
+    Cola: sweetness: 0.377573124603715, sales: 374
+    
+You can see that our single consumer wanted sweetness rated around 0.25, and ended up purchasing more soda that ended up looking like 0.36.  With better goal-seeking behavior, the agents could actually optimize to the consumer's preferences.  With some verification of the seed nodes against market data, the simulations could look more and more like the real world.
+
+I've written up an article on our company blog to give a better background to Agent Based Models, which can be [found here](http://fleetventures.com/2010/11/07/agent-based-modeling/).
+
+Future Development
+------------------
+
 This code is certainly not production ready.  There are many things I'll want to add just to have basic Monte Carlo methods up to snuff:
 
 * More distributions to choose from
@@ -122,26 +269,27 @@ This code is certainly not production ready.  There are many things I'll want to
 * Better visualization with plotutils support and possibly other graphics support
 * Project organization: decision descriptions, owners, sharing
 * Measurement values: use Shannon's entropy and some value calculations to point out which measurements have the highest potential ROI
+* EventMachine to drive agent clusters, as well as possibly other parts of the system
 
 On a bigger level, I still haven't implemented other major ideas:
 
-* Agent-based modeling
 * System dynamics
 * Belief updating in Causal Graphs
 * Fathom as a Web service
 
-Documentation TODO:
+Dependencies
+------------
 
-* Document using this library from the command line
-* Document these classes as RabbitMQ consumers
+This project relies on the GNU Scientific Library and the ruby/gsl bindings for the GSL.  It has only minimal extensions to external libraries:
 
-Dependencies
-============
+* Array responds to rand (so [1,2,3].rand returns a random value from that array)      
+* OpenStruct exposes it's underlying table, keys, and values
+* FasterCSV has a :strip header converter now
 
-This project relies on the GNU Scientific Library and the ruby/gsl bindings for the GSL.      
+In the future, more dependencies will be introduced for parts of the library: EventMachine is one that I'm sure will be added.  The goal of this project is to allow a reasonable number of dependencies to make the project performant and useful, but without making it a headache to setup or use with other projects.
 
 Note on Patches/Pull Requests
-=============================
+-----------------------------
  
 * Fork the project.
 * Make your feature addition or bug fix.
@@ -153,7 +301,7 @@ Note on Patches/Pull Requests
 * Send me a pull request. Bonus points for topic branches.
 
 Copyright
-=========
+---------
 
 Copyright (c) 2010 David Richards
 

data/VERSION

@@ -1 +1 @@
-0.2.1
+0.2.2

data/lib/fathom/monte_carlo_set.rb

@@ -7,6 +7,12 @@ class Fathom::MonteCarloSet
         self.samples[key.to_sym]
       end
     end
+    
+    def define_summary_method(field)
+      define_method("#{field}_summary".to_sym) do
+        self.summary(field.to_sym)
+      end
+    end
   end
   
   attr_reader :value_description, :samples_taken, :samples
@@ -30,8 +36,33 @@ class Fathom::MonteCarloSet
     @keys_asserted = nil
   end
   
+  def fields
+    @samples.keys
+  end
+  
+  def summary(field=nil)
+    return summarize_field(field) if field
+    fields.inject({}) do |h, field|
+      h[field] = summarize_field(field)
+      h
+    end
+  end
+  
   protected
   
+    def summarize_field(field)
+      raise "No fields are defined.  Have you processed this model yet?" if fields.empty?
+      raise ArgumentError, "#{field} is not a field in this set." unless fields.include?(field)
+      vector = self.send(field)
+      {
+        :coefficient_of_variation => (vector.sd / vector.mean),
+        :max => vector.max,
+        :mean => vector.mean,
+        :min => vector.min,
+        :sd => vector.sd
+      }
+    end
+  
     def assert_sample_vectors
       vectors = @samples.inject({}) do |h, o|
         key, array = o.first, o.last
@@ -58,6 +89,7 @@ class Fathom::MonteCarloSet
       return true if @keys_asserted
       result.keys.each do |key|
         assert_key(key)
+        self.class.define_summary_method(key)
       end
       @keys_asserted = true
     end

data/spec/fathom/monte_carlo_set_spec.rb

@@ -15,6 +15,9 @@ describe MonteCarloSet do
       gross_margins = revenue - commissions_paid
       {:revenue => revenue, :commissions_paid => commissions_paid, :gross_margins => gross_margins}
     end
+    
+    @fields = [:commissions_paid, :gross_margins, :revenue]
+    @summary_fields = [:coefficient_of_variation, :max, :mean, :min, :sd]
   end
   
   before do
@@ -55,4 +58,40 @@ describe MonteCarloSet do
     @mcs.reset!
     lambda{@mcs.process(1)}.should_not raise_error
   end
+
+  it "should expose the fields from the samples" do
+    @mcs.process(1)
+    sort_array_of_symbols(@mcs.fields).should eql(@fields)
+  end
+  
+  it "should offer a summary of the fields" do
+    @mcs.process(1)
+    summary = @mcs.summary
+    summary.should be_a(Hash)
+    sort_array_of_symbols(summary.keys).should eql(@fields)
+    summary.each do |key, value|
+      value.should be_a(Hash)
+      sort_array_of_symbols(value.keys).should eql(@summary_fields)
+    end
+  end
+  
+  it "should be able to summarize a single field" do
+    @mcs.process(2)
+    summary = @mcs.summary(:revenue)
+    summary.should be_a(Hash)
+    sort_array_of_symbols(summary.keys).should eql(@summary_fields)
+    summary[:coefficient_of_variation].should eql(@mcs.revenue.sd / @mcs.revenue.mean)
+    summary[:max].should eql(@mcs.revenue.max)
+    summary[:min].should eql(@mcs.revenue.min)
+    summary[:sd].should eql(@mcs.revenue.sd)
+  end
+  
+  it "should define summary methods on the object" do
+    @mcs.process(2)
+    @mcs.revenue_summary.should eql(@mcs.summary(:revenue))
+  end
 end
+
+def sort_array_of_symbols(array)
+  array.map {|e| e.to_s}.sort.map {|e| e.to_sym}
+end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: fathom
 version: !ruby/object:Gem::Version 
-  hash: 21
+  hash: 19
   prerelease: false
   segments: 
   - 0
   - 2
-  - 1
-  version: 0.2.1
+  - 2
+  version: 0.2.2
 platform: ruby
 authors: 
 - David
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-11-07 00:00:00 -06:00
+date: 2010-11-09 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency