planout 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 81d07087a7e4796827f84836ff455d897bb2cc9d
+  data.tar.gz: e859012c622ca1377b99005011209b9086216fda
+SHA512:
+  metadata.gz: 6b9c798846c42b70a9e58b34817f0637086e06c0327e17e337faf5296ecf19b72fdc6682e622ac4fb1c4ad37f3245346e978839ce2de255cb5e44c68e53a63d7
+  data.tar.gz: f53ebe3dd097c406ecb793a70b82f8f22e7c51b525c8e2386e021d023e4ab1719535607386334382e52c98e8800378c082cbbe0c7ca8a3377808cb3a145f1306

data/.gitignore

@@ -0,0 +1,16 @@
+/.bundle/
+/backup/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log
+.DS_Store

data/Gemfile

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

data/LICENSE

@@ -0,0 +1,30 @@
+BSD License
+
+For PlanOut software
+
+Copyright (c) 2014, Facebook, Inc. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+ * Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+ * Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+ * Neither the name Facebook nor the names of its contributors may be used to
+   endorse or promote products derived from this software without specific
+   prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,74 @@
+## Overview
+This is a rough implementation of the Experiment / logging infrasture for running PlanOut experiments, with all the random assignment operators available in Python. This port is nearly a line-by-line port, and produces assignments that are completely consistent with those produced by the Python reference implementation.
+
+## Installation
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'planout'
+```
+
+And then execute:
+```bash
+$ bundle
+```
+
+Or install it yourself as:
+```bash
+$ gem install planout
+```
+
+## How it works
+
+This defines a simple experiment that randomly assigns three variables, foo, bar, and baz.
+`foo` and `baz` use `userid` as input, while `bar` uses a pair, namely `userid` combined with the value of `foo` from the prior step.
+```Ruby
+class VotingExperiment < SimpleExperiment
+  # Experiment#assign takes params and an input array
+  def assign(params, **inputs)
+    userid = inputs[:userid]
+
+    params[:button_color] = UniformChoice.new({
+      choices: ['ff0000', '#00ff00'],
+      unit: userid
+    })
+
+    params[:button_text] = UniformChoice.new({
+      choices: ["I'm voting", "I'm a voter"],
+      unit: userid,
+      salt:'x'
+    })
+  end
+end
+```
+
+Then, we can examine the assignments produced for a few input userids. Note that since exposure logging is enabled by default, all of the experiments' inputs, configuration information, timestamp, and parameter assignments are pooped out via the Logger class.
+
+```ruby
+my_exp = VotingExperiment.new(userid: 14)
+my_button_color = my_exp.get(:button_color)
+button_text = my_exp.get(:button_text)
+puts "button color is #{my_button_color} and button text is #{button_text}."
+```
+
+The output of the Ruby script looks something like this:
+
+```ruby
+logged data: {"name":"VotingExperiment","time":1404944726,"salt":"VotingExperiment","inputs":{"userid":14},"params":{"button_color":"ff0000","button_text":"I'm a voter"},"event":"exposure"}
+
+button color is ff0000 and button text is I'm a voter.
+```
+## Examples
+
+For examples please refer to the `examples` directory.
+
+## Running the tests
+Make sure you're in the ruby implementation directory of PlanOut and run
+
+`rake` or `rake test`
+
+to run the entire test suite.
+
+If you wish to run a specific test, run
+
+`rake test TEST=test/testname.rb` or even better `ruby test/testname.rb`

data/Rakefile

@@ -0,0 +1,8 @@
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.test_files = FileList['test/**/*_test.rb']
+end
+
+task default: :test

data/examples/planout/voting_experiment.rb

@@ -0,0 +1,31 @@
+require_relative '../../lib/planout/simple_experiment'
+
+module Planout
+  class VotingExperiment < SimpleExperiment
+    def setup; end
+
+    def assign(params, **inputs)
+      userid = inputs[:userid]
+      params[:button_color] = UniformChoice.new({
+        choices: ['ff0000', '00ff00'],
+        unit: userid
+      })
+
+      params[:button_text] = UniformChoice.new({
+        choices: ["I'm voting", "I'm a voter"],
+        unit: userid,
+        salt:'x'
+      })
+    end
+  end
+
+  if __FILE__ == $0
+    (14..16).each do |i|
+      my_exp = VotingExperiment.new(userid:i)
+      # toggling the above disables or re-enables auto-logging
+      #my_exp.auto_exposure_log = false
+      puts "\ngetting assignment for user #{i} note: first time triggers a log event"
+      puts "button color is #{my_exp.get(:button_color)} and button text is #{my_exp.get(:button_text)}"
+    end
+  end
+end

data/lib/planout.rb

@@ -0,0 +1,16 @@
+require_relative 'planout/operator'
+require_relative 'planout/op_simple'
+require_relative 'planout/op_random'
+require_relative 'planout/random_float'
+require_relative 'planout/random_integer'
+require_relative 'planout/bernoulli_trial'
+require_relative 'planout/weighted_choice'
+require_relative 'planout/uniform_choice'
+require_relative 'planout/assignment'
+require_relative 'planout/experiment'
+require_relative 'planout/simple_experiment'
+require_relative 'planout/version'
+
+module Planout
+
+end

data/lib/planout/assignment.rb

@@ -0,0 +1,41 @@
+module Planout
+  class Assignment
+    attr_accessor :experiment_salt, :data
+
+    def initialize(experiment_salt)
+      @experiment_salt = experiment_salt
+      @data = {}
+    end
+
+    def evaluate(data)
+      data
+    end
+
+    def get(var, default = nil)
+      @data[var.to_sym] || default
+    end
+
+    # in python this would be defined as __setattr__ or __setitem__
+    # not sure how to do this in Ruby.
+    def set(name, value)
+      if value.is_a? Operator
+        value.args[:salt] = name if !value.args.has_key?(:salt)
+        @data[name.to_sym] = value.execute(self)
+      else
+        @data[name.to_sym] = value
+      end
+    end
+
+    def [](x)
+      get(x)
+    end
+
+    def []=(x,y)
+      set(x,y)
+    end
+
+    def get_params
+      @data
+    end
+  end
+end

data/lib/planout/bernoulli_trial.rb

@@ -0,0 +1,11 @@
+require_relative 'op_random'
+
+module Planout
+  class BernoulliTrial < OpRandom
+    def simple_execute
+      p = @parameters[:p]
+      rand_val = get_uniform(0.0, 1.0)
+      (rand_val <= p) ? 1 : 0
+    end
+  end
+end

data/lib/planout/experiment.rb

@@ -0,0 +1,112 @@
+require 'logger'
+require 'json'
+
+module Planout
+  class Experiment
+    attr_accessor :auto_exposure_log
+
+    def initialize(**inputs)
+      @inputs = inputs
+      @exposure_logged = false
+      @_salt = nil
+      @in_experiment = true
+      @name = self.class.name
+      @auto_exposure_log = true
+
+      setup  # sets name, salt, etc.
+
+      @assignment = Assignment.new(salt)
+      @assigned = false
+
+      @logger = nil
+      setup
+    end
+
+    def _assign
+      configure_logger
+      assign(@assignment, **@inputs)
+      @in_experiment = @assignment.get(:in_experiment, @in_experiment)
+      @assigned = true
+    end
+
+    def setup
+      nil
+    end
+
+    def salt=(value)
+      @_salt = value
+    end
+
+    def salt
+      @_salt || @name
+    end
+
+    def auto_exposure_log=(value)
+      @auto_exposure_log = value
+    end
+
+    def configure_logger
+      nil
+    end
+
+    def requires_assignment
+      _assign if !@assigned
+    end
+
+    def is_logged?
+      @logged
+    end
+
+    def requires_exposure_logging
+      log_exposure if @auto_exposure_log && @in_experiment && !@exposure_logged
+    end
+
+    def get_params
+      requires_assignment
+      requires_exposure_logging
+      @assignment.get_params
+    end
+
+    def get(name, default = nil)
+      requires_assignment
+      requires_exposure_logging
+      @assignment.get(name, default)
+    end
+
+    def assign(params, *inputs)
+      # up to child class to implement
+      nil
+    end
+
+    def log_event(event_type, extras = nil)
+      if extras.nil?
+        extra_payload = {event: event_type}
+      else
+        extra_payload = {
+          event: event_type,
+          extra_data: extras.clone
+        }
+      end
+
+      log(as_blob(extra_payload))
+    end
+
+    def log_exposure(extras = nil)
+      @exposure_logged = true
+      log_event(:exposure, extras)
+    end
+
+    def as_blob(extras = {})
+      d = {
+        name: @name,
+        time: Time.now.to_i,
+        salt: salt,
+        inputs: @inputs,
+        params: @assignment.data
+      }
+
+      d.merge!(extras)
+    end
+  end
+
+end

data/lib/planout/op_random.rb

@@ -0,0 +1,28 @@
+require_relative 'op_simple'
+
+module Planout
+  class OpRandom < OpSimple
+    LongScale = Float(0xFFFFFFFFFFFFFFF)
+
+    def get_unit(appended_unit = nil)
+      unit = @parameters[:unit]
+      unit = [unit] if !unit.is_a? Array
+      unit += appended_unit if appended_unit != nil
+      unit
+    end
+
+    def get_hash(appended_unit = nil)
+      salt = @parameters[:salt]
+      salty = "#{@mapper.experiment_salt}.#{salt}"
+      unit_str = get_unit(appended_unit).join('.')
+      x = "#{salty}.#{unit_str}"
+      last_hex = (Digest::SHA1.hexdigest(x))[0..14]
+      last_hex.to_i(16)
+    end
+
+    def get_uniform(min_val = 0.0, max_val = 1.0, appended_unit = nil)
+      zero_to_one = self.get_hash(appended_unit)/LongScale
+      min_val + (max_val-min_val) * zero_to_one
+    end
+  end
+end

data/lib/planout/op_simple.rb

@@ -0,0 +1,20 @@
+require_relative 'operator'
+
+module Planout
+  class OpSimple < Operator
+    def execute(mapper)
+      @mapper = mapper
+      @parameters = {}
+
+      @args.each do |key, value|
+        @parameters[key] = mapper.evaluate(value)
+      end
+
+      simple_execute
+    end
+
+    def simple_execute
+      -1
+    end
+  end
+end

data/lib/planout/operator.rb

@@ -0,0 +1,14 @@
+require 'digest/sha1'
+
+module Planout
+  class Operator
+    attr_accessor :args
+    def initialize(parameters)
+      @args = parameters
+    end
+
+    def execute(mapper)
+      mapper.experiment_salt
+    end
+  end
+end

data/lib/planout/random_float.rb

@@ -0,0 +1,11 @@
+require_relative 'op_random'
+
+module Planout
+  class RandomFloat < OpRandom
+    def simple_execute
+      min_val = @parameters.fetch(:min, 0)
+      max_val = @parameters.fetch(:max, 1)
+      get_uniform(min_val, max_val)
+    end
+  end
+end

data/lib/planout/random_integer.rb

@@ -0,0 +1,11 @@
+require_relative 'op_random'
+
+module Planout
+  class RandomInteger < OpRandom
+    def simple_execute
+      min_val = @parameters.fetch(:min, 0)
+      max_val = @parameters.fetch(:max, 1)
+      min_val + get_hash() % (max_val - min_val + 1)
+    end
+  end
+end

data/lib/planout/simple_experiment.rb

@@ -0,0 +1,17 @@
+require_relative 'experiment'
+
+module Planout
+  class SimpleExperiment < Experiment
+    def configure_logger
+      @logger = Logger.new(STDOUT)
+      #@loger.level = Logger::WARN
+      @logger.formatter = proc do |severity, datetime, progname, msg|
+        "logged data: #{msg}\n"
+      end
+    end
+
+    def log(data)
+      @logger.info(JSON.dump(data))
+    end
+  end
+end

data/lib/planout/uniform_choice.rb

@@ -0,0 +1,12 @@
+require_relative 'op_random'
+
+module Planout
+  class UniformChoice < OpRandom
+    def simple_execute
+      choices = @parameters[:choices]
+      return [] if choices.length() == 0
+      rand_index = get_hash() % choices.length()
+      choices[rand_index]
+    end
+  end
+end

data/lib/planout/version.rb

@@ -0,0 +1,3 @@
+module Planout
+  VERSION = '0.0.1'
+end

data/lib/planout/weighted_choice.rb

@@ -0,0 +1,26 @@
+require_relative 'op_random'
+
+module Planout
+  class WeightedChoice < OpRandom
+    def simple_execute
+      choices = @parameters[:choices]
+      weights = @parameters[:weights]
+
+      return [] if choices.length() == 0
+
+      cum_weights = choices.zip(weights)
+      cum_sum = 0.0
+
+      cum_weights.each do |choice, weight|
+        cum_sum += weight
+        cum_weights[choice] = cum_sum
+      end
+
+      stop_value = get_uniform(0.0, cum_sum)
+
+      cum_weights.each do |choice, cum_weight|
+        choice if stop_value <= cum_weight
+      end
+    end
+  end
+end

data/planout.gemspec

@@ -0,0 +1,24 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'planout/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "planout"
+  spec.version       = Planout::VERSION
+  spec.authors       = ["Mohnish Thallavajhula"]
+  spec.email         = ["i@mohni.sh"]
+  spec.summary       = %q{PlanOut is a framework and programming language for online field experimentation.}
+  spec.description   = %q{PlanOut is a framework and programming language for online field experimentation. PlanOut was created to make it easy to run and iterate on sophisticated experiments, while satisfying the constraints of deployed Internet services with many users.}
+  spec.homepage      = "https://facebook.github.io/planout"
+  spec.license       = "BSD"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.7"
+  spec.add_development_dependency "minitest", "~> 5.5"
+  spec.add_development_dependency "rake", "~> 10.0"
+end

data/test/planout/assignment_test.rb

@@ -0,0 +1,42 @@
+require_relative '../test_helper'
+
+module Planout
+  class AssignmentTest < Minitest::Test
+    def setup
+      @assignment = Assignment.new('mtsalt')
+    end
+
+    def test_salt
+      assert_equal('mtsalt', @assignment.experiment_salt)
+    end
+
+    def test_evaluate
+      assert_equal(1, @assignment.evaluate(1))
+      assert_equal(2, @assignment.evaluate(2))
+    end
+
+    def test_set
+      @assignment.set(:color, 'green')
+      @assignment.set('platform', 'ios')
+      @assignment.set('foo', UniformChoice.new({ unit: 1, choices: ['x', 'y'] }))
+      assert_equal('green', @assignment.data[:color])
+      assert_equal('ios', @assignment.data[:platform])
+      assert_equal('y', @assignment.data[:foo])
+    end
+
+    def test_get
+      @assignment.set(:button_text, 'Click Me!')
+      @assignment.set(:gender, 'f')
+      assert_equal('Click Me!', @assignment.get('button_text'))
+      assert_equal('f', @assignment.get('gender'))
+      assert_equal(10, @assignment.get('missing_key', 10))
+      assert_nil(@assignment.get('missing_key'))
+    end
+
+    def test_get_params
+      @assignment.set('foo', 'bar')
+      @assignment.set(:baz, 'qux')
+      assert_equal({ foo: 'bar', baz: 'qux' }, @assignment.get_params)
+    end
+  end
+end

data/test/planout/experiment_test.rb

@@ -0,0 +1,33 @@
+require_relative '../test_helper'
+require_relative '../../examples/planout/voting_experiment'
+
+module Planout
+  class ExperimentTest < Minitest::Test
+    def setup
+      @voting_experiment = VotingExperiment.new(userid: 14)
+      @voting_experiment2 = VotingExperiment.new(userid: 15)
+      @voting_experiment.auto_exposure_log = false
+      @voting_experiment2.auto_exposure_log = false
+    end
+
+    def test_get_attributes
+      assert_equal('ff0000', @voting_experiment.get(:button_color))
+      assert_equal(1, @voting_experiment.get(:missing_key, 1))
+      assert_equal('ff0000', @voting_experiment2.get(:button_color))
+      assert_equal("I'm voting", @voting_experiment.get(:button_text))
+      assert_equal("I'm a voter", @voting_experiment2.get(:button_text))
+    end
+
+    def test_get_params
+      assert_equal({ button_color: 'ff0000', button_text: "I'm voting" }, @voting_experiment.get_params)
+      assert_equal({ button_color: 'ff0000', button_text: "I'm a voter" }, @voting_experiment2.get_params)
+    end
+
+    def test_as_blob
+      result = @voting_experiment.as_blob
+      assert_equal('Planout::VotingExperiment', result[:name])
+      assert_equal('Planout::VotingExperiment', result[:salt])
+      assert_equal({ userid: 14 }, result[:inputs])
+    end
+  end
+end

data/test/planout/operator_test.rb

@@ -0,0 +1,16 @@
+require_relative '../test_helper'
+
+module Planout
+  class OperatorTest < Minitest::Test
+    def setup
+      @operator = Operator.new({ foo: 'bar' })
+      @op_simple = OpSimple.new({ bar: 'qux' })
+    end
+
+    def test_execute
+      a = Assignment.new('mtsalt')
+      assert_equal('mtsalt', @operator.execute(a))
+      assert_equal(-1, @op_simple.execute(a))
+    end
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,2 @@
+require 'minitest/autorun'
+require_relative '../lib/planout'

metadata

@@ -0,0 +1,116 @@
+--- !ruby/object:Gem::Specification
+name: planout
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Mohnish Thallavajhula
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-12-21 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.5'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+description: PlanOut is a framework and programming language for online field experimentation.
+  PlanOut was created to make it easy to run and iterate on sophisticated experiments,
+  while satisfying the constraints of deployed Internet services with many users.
+email:
+- i@mohni.sh
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- examples/planout/voting_experiment.rb
+- lib/planout.rb
+- lib/planout/assignment.rb
+- lib/planout/bernoulli_trial.rb
+- lib/planout/experiment.rb
+- lib/planout/op_random.rb
+- lib/planout/op_simple.rb
+- lib/planout/operator.rb
+- lib/planout/random_float.rb
+- lib/planout/random_integer.rb
+- lib/planout/simple_experiment.rb
+- lib/planout/uniform_choice.rb
+- lib/planout/version.rb
+- lib/planout/weighted_choice.rb
+- planout.gemspec
+- test/planout/assignment_test.rb
+- test/planout/experiment_test.rb
+- test/planout/operator_test.rb
+- test/test_helper.rb
+homepage: https://facebook.github.io/planout
+licenses:
+- BSD
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: PlanOut is a framework and programming language for online field experimentation.
+test_files:
+- test/planout/assignment_test.rb
+- test/planout/experiment_test.rb
+- test/planout/operator_test.rb
+- test/test_helper.rb