ab-split 1.0.0

data/lib/split/combined_experiments_helper.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+module Split
+  module CombinedExperimentsHelper
+    def ab_combined_test(metric_descriptor, control = nil, *alternatives)
+      return nil unless experiment = find_combined_experiment(metric_descriptor)
+      raise(Split::InvalidExperimentsFormatError, "Unable to find experiment #{metric_descriptor} in configuration") if experiment[:combined_experiments].nil?
+
+      alternative = nil
+      weighted_alternatives = nil
+      experiment[:combined_experiments].each do |combined_experiment|
+        if alternative.nil?
+          if control
+            alternative = ab_test(combined_experiment, control, alternatives)
+          else
+            normalized_alternatives = Split::Configuration.new.normalize_alternatives(experiment[:alternatives])
+            alternative = ab_test(combined_experiment, normalized_alternatives[0], *normalized_alternatives[1])
+          end
+        else
+          weighted_alternatives ||= experiment[:alternatives].each_with_object({}) do |alt, memo|
+            alt = Alternative.new(alt, experiment[:name]).name
+            memo[alt] = (alt == alternative ? 1 : 0)
+          end
+
+          ab_test(combined_experiment, [weighted_alternatives])
+        end
+      end
+      alternative
+    end
+
+    def find_combined_experiment(metric_descriptor)
+      raise(Split::InvalidExperimentsFormatError, 'Invalid descriptor class (String or Symbol required)') unless metric_descriptor.class == String || metric_descriptor.class == Symbol
+      raise(Split::InvalidExperimentsFormatError, 'Enable configuration') unless Split.configuration.enabled
+      raise(Split::InvalidExperimentsFormatError, 'Enable `allow_multiple_experiments`') unless Split.configuration.allow_multiple_experiments
+      Split::configuration.experiments[metric_descriptor.to_sym]
+    end
+  end
+end

data/lib/split/configuration.rb

@@ -0,0 +1,255 @@
+# frozen_string_literal: true
+module Split
+  class Configuration
+    attr_accessor :ignore_ip_addresses
+    attr_accessor :ignore_filter
+    attr_accessor :db_failover
+    attr_accessor :db_failover_on_db_error
+    attr_accessor :db_failover_allow_parameter_override
+    attr_accessor :allow_multiple_experiments
+    attr_accessor :enabled
+    attr_accessor :persistence
+    attr_accessor :persistence_cookie_length
+    attr_accessor :algorithm
+    attr_accessor :store_override
+    attr_accessor :start_manually
+    attr_accessor :reset_manually
+    attr_accessor :on_trial
+    attr_accessor :on_trial_choose
+    attr_accessor :on_trial_complete
+    attr_accessor :on_experiment_reset
+    attr_accessor :on_experiment_delete
+    attr_accessor :on_before_experiment_reset
+    attr_accessor :on_before_experiment_delete
+    attr_accessor :include_rails_helper
+    attr_accessor :beta_probability_simulations
+    attr_accessor :winning_alternative_recalculation_interval
+    attr_accessor :redis
+    attr_accessor :dashboard_pagination_default_per_page
+
+    attr_reader :experiments
+
+    attr_writer :bots
+    attr_writer :robot_regex
+
+    def bots
+      @bots ||= {
+        # Indexers
+        'AdsBot-Google' => 'Google Adwords',
+        'Baidu' => 'Chinese search engine',
+        'Baiduspider' => 'Chinese search engine',
+        'bingbot' => 'Microsoft bing bot',
+        'Butterfly' => 'Topsy Labs',
+        'Gigabot' => 'Gigabot spider',
+        'Googlebot' => 'Google spider',
+        'MJ12bot' => 'Majestic-12 spider',
+        'msnbot' => 'Microsoft bot',
+        'rogerbot' => 'SeoMoz spider',
+        'PaperLiBot' => 'PaperLi is another content curation service',
+        'Slurp' => 'Yahoo spider',
+        'Sogou' => 'Chinese search engine',
+        'spider' => 'generic web spider',
+        'UnwindFetchor' => 'Gnip crawler',
+        'WordPress' => 'WordPress spider',
+        'YandexAccessibilityBot' => 'Yandex accessibility spider',
+        'YandexBot' => 'Yandex spider',
+        'YandexMobileBot' => 'Yandex mobile spider',
+        'ZIBB' => 'ZIBB spider',
+
+        # HTTP libraries
+        'Apache-HttpClient' => 'Java http library',
+        'AppEngine-Google' => 'Google App Engine',
+        'curl' => 'curl unix CLI http client',
+        'ColdFusion' => 'ColdFusion http library',
+        'EventMachine HttpClient' => 'Ruby http library',
+        'Go http package' => 'Go http library',
+        'Go-http-client' => 'Go http library',
+        'Java' => 'Generic Java http library',
+        'libwww-perl' => 'Perl client-server library loved by script kids',
+        'lwp-trivial' => 'Another Perl library loved by script kids',
+        'Python-urllib' => 'Python http library',
+        'PycURL' => 'Python http library',
+        'Test Certificate Info' => 'C http library?',
+        'Typhoeus' => 'Ruby http library',
+        'Wget' => 'wget unix CLI http client',
+
+        # URL expanders / previewers
+        'awe.sm' => 'Awe.sm URL expander',
+        'bitlybot' => 'bit.ly bot',
+        'bot@linkfluence.net' => 'Linkfluence bot',
+        'facebookexternalhit' => 'facebook bot',
+        'Facebot' => 'Facebook crawler',
+        'Feedfetcher-Google' => 'Google Feedfetcher',
+        'https://developers.google.com/+/web/snippet' => 'Google+ Snippet Fetcher',
+        'LinkedInBot' => 'LinkedIn bot',
+        'LongURL' => 'URL expander service',
+        'NING' => 'NING - Yet Another Twitter Swarmer',
+        'Pinterest' => 'Pinterest Bot',
+        'redditbot' => 'Reddit Bot',
+        'ShortLinkTranslate' => 'Link shortener',
+        'Slackbot' => 'Slackbot link expander',
+        'TweetmemeBot' => 'TweetMeMe Crawler',
+        'Twitterbot' => 'Twitter URL expander',
+        'UnwindFetch' => 'Gnip URL expander',
+        'vkShare' => 'VKontake Sharer',
+
+        # Uptime monitoring
+        'check_http' => 'Nagios monitor',
+        'GoogleStackdriverMonitoring' => 'Google Cloud monitor',
+        'NewRelicPinger' => 'NewRelic monitor',
+        'Panopta' => 'Monitoring service',
+        'Pingdom' => 'Pingdom monitoring',
+        'SiteUptime' => 'Site monitoring services',
+        'UptimeRobot' => 'Monitoring service',
+
+        # ???
+        'DigitalPersona Fingerprint Software' => 'HP Fingerprint scanner',
+        'ShowyouBot' => 'Showyou iOS app spider',
+        'ZyBorg' => 'Zyborg? Hmmm....',
+        'ELB-HealthChecker' => 'ELB Health Check'
+      }
+    end
+
+    def experiments= experiments
+      raise InvalidExperimentsFormatError.new('Experiments must be a Hash') unless experiments.respond_to?(:keys)
+      @experiments = experiments
+    end
+
+    def disabled?
+      !enabled
+    end
+
+    def experiment_for(name)
+      if normalized_experiments
+        # TODO symbols
+        normalized_experiments[name.to_sym]
+      end
+    end
+
+    def metrics
+      return @metrics if defined?(@metrics)
+      @metrics = {}
+      if self.experiments
+        self.experiments.each do |key, value|
+          metrics = value_for(value, :metric) rescue nil
+          Array(metrics).each do |metric_name|
+            if metric_name
+              @metrics[metric_name.to_sym] ||= []
+              @metrics[metric_name.to_sym] << Split::Experiment.new(key)
+            end
+          end
+        end
+      end
+      @metrics
+    end
+
+    def normalized_experiments
+      return nil if @experiments.nil?
+
+      experiment_config = {}
+      @experiments.keys.each do |name|
+        experiment_config[name.to_sym] = {}
+      end
+
+      @experiments.each do |experiment_name, settings|
+        alternatives = if (alts = value_for(settings, :alternatives))
+                         normalize_alternatives(alts)
+                       end
+
+        experiment_data = {
+          alternatives: alternatives,
+          goals: value_for(settings, :goals),
+          metadata: value_for(settings, :metadata),
+          algorithm: value_for(settings, :algorithm),
+          resettable: value_for(settings, :resettable)
+        }
+
+        experiment_data.each do |name, value|
+          experiment_config[experiment_name.to_sym][name] = value if value != nil
+        end
+      end
+
+      experiment_config
+    end
+
+    def normalize_alternatives(alternatives)
+      given_probability, num_with_probability = alternatives.inject([0,0]) do |a,v|
+        p, n = a
+        if percent = value_for(v, :percent)
+          [p + percent, n + 1]
+        else
+          a
+        end
+      end
+
+      num_without_probability = alternatives.length - num_with_probability
+      unassigned_probability = ((100.0 - given_probability) / num_without_probability / 100.0)
+
+      if num_with_probability.nonzero?
+        alternatives = alternatives.map do |v|
+          if (name = value_for(v, :name)) && (percent = value_for(v, :percent))
+            { name => percent / 100.0 }
+          elsif name = value_for(v, :name)
+            { name => unassigned_probability }
+          else
+            { v => unassigned_probability }
+          end
+        end
+
+        [alternatives.shift, alternatives]
+      else
+        alternatives = alternatives.dup
+        [alternatives.shift, alternatives]
+      end
+    end
+
+    def robot_regex
+      @robot_regex ||= /\b(?:#{escaped_bots.join('|')})\b|\A\W*\z/i
+    end
+
+    def initialize
+      @ignore_ip_addresses = []
+      @ignore_filter = proc{ |request| is_robot? || is_ignored_ip_address? }
+      @db_failover = false
+      @db_failover_on_db_error = proc{|error|} # e.g. use Rails logger here
+      @on_experiment_reset = proc{|experiment|}
+      @on_experiment_delete = proc{|experiment|}
+      @on_before_experiment_reset = proc{|experiment|}
+      @on_before_experiment_delete = proc{|experiment|}
+      @db_failover_allow_parameter_override = false
+      @allow_multiple_experiments = false
+      @enabled = true
+      @experiments = {}
+      @persistence = Split::Persistence::SessionAdapter
+      @persistence_cookie_length = 31536000 # One year from now
+      @algorithm = Split::Algorithms::WeightedSample
+      @include_rails_helper = true
+      @beta_probability_simulations = 10000
+      @winning_alternative_recalculation_interval = 60 * 60 * 24 # 1 day
+      @redis = ENV.fetch(ENV.fetch('REDIS_PROVIDER', 'REDIS_URL'), 'redis://localhost:6379')
+      @dashboard_pagination_default_per_page = 10
+    end
+
+    def redis_url=(value)
+      warn '[DEPRECATED] `redis_url=` is deprecated in favor of `redis=`'
+      self.redis = value
+    end
+
+    def redis_url
+      warn '[DEPRECATED] `redis_url` is deprecated in favor of `redis`'
+      self.redis
+    end
+
+    private
+
+    def value_for(hash, key)
+      if hash.kind_of?(Hash)
+        hash.has_key?(key.to_s) ? hash[key.to_s] : hash[key.to_sym]
+      end
+    end
+
+    def escaped_bots
+      bots.map { |key, _| Regexp.escape(key) }
+    end
+  end
+end

data/lib/split/dashboard.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+require 'sinatra/base'
+require 'split'
+require 'bigdecimal'
+require 'split/dashboard/helpers'
+require 'split/dashboard/pagination_helpers'
+
+module Split
+  class Dashboard < Sinatra::Base
+    dir = File.dirname(File.expand_path(__FILE__))
+
+    set :views,  "#{dir}/dashboard/views"
+    set :public_folder, "#{dir}/dashboard/public"
+    set :static, true
+    set :method_override, true
+
+    helpers Split::DashboardHelpers
+    helpers Split::DashboardPaginationHelpers
+
+    get '/' do
+      # Display experiments without a winner at the top of the dashboard
+      @experiments = Split::ExperimentCatalog.all_active_first
+
+      @metrics = Split::Metric.all
+
+      # Display Rails Environment mode (or Rack version if not using Rails)
+      if Object.const_defined?('Rails')
+        @current_env = Rails.env.titlecase
+      else
+        @current_env = "Rack: #{Rack.version}"
+      end
+      erb :index
+    end
+
+    post '/force_alternative' do
+      experiment = Split::ExperimentCatalog.find(params[:experiment])
+      alternative = Split::Alternative.new(params[:alternative], experiment.name)
+      alternative.increment_participation
+      Split::User.new(self)[experiment.key] = alternative.name
+      redirect url('/')
+    end
+
+    post '/experiment' do
+      @experiment = Split::ExperimentCatalog.find(params[:experiment])
+      @alternative = Split::Alternative.new(params[:alternative], params[:experiment])
+      @experiment.winner = @alternative.name
+      redirect url('/')
+    end
+
+    post '/start' do
+      @experiment = Split::ExperimentCatalog.find(params[:experiment])
+      @experiment.start
+      redirect url('/')
+    end
+
+    post '/reset' do
+      @experiment = Split::ExperimentCatalog.find(params[:experiment])
+      @experiment.reset
+      redirect url('/')
+    end
+
+    post '/reopen' do
+      @experiment = Split::ExperimentCatalog.find(params[:experiment])
+      @experiment.reset_winner
+      redirect url('/')
+    end
+
+    delete '/experiment' do
+      @experiment = Split::ExperimentCatalog.find(params[:experiment])
+      @experiment.delete
+      redirect url('/')
+    end
+  end
+end

data/lib/split/dashboard/helpers.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+module Split
+  module DashboardHelpers
+    def h(text)
+      Rack::Utils.escape_html(text)
+    end
+
+    def url(*path_parts)
+      [ path_prefix, path_parts ].join("/").squeeze('/')
+    end
+
+    def path_prefix
+      request.env['SCRIPT_NAME']
+    end
+
+    def number_to_percentage(number, precision = 2)
+      round(number * 100)
+    end
+
+    def round(number, precision = 2)
+      begin
+        BigDecimal(number.to_s)
+      rescue ArgumentError
+        BigDecimal(0)
+      end.round(precision).to_f
+    end
+
+    def confidence_level(z_score)
+      return z_score if z_score.is_a? String
+
+      z = round(z_score.to_s.to_f, 3).abs
+
+      if z >= 2.58
+        '99% confidence'
+      elsif z >= 1.96
+        '95% confidence'
+      elsif z >= 1.65
+        '90% confidence'
+      else
+        'Insufficient confidence'
+      end
+
+    end
+  end
+end

data/lib/split/dashboard/pagination_helpers.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+require 'split/dashboard/paginator'
+
+module Split
+  module DashboardPaginationHelpers
+    def pagination_per
+      default_per_page = Split.configuration.dashboard_pagination_default_per_page
+      @pagination_per ||= (params[:per] || default_per_page).to_i
+    end
+
+    def page_number
+      @page_number ||= (params[:page] || 1).to_i
+    end
+
+    def paginated(collection)
+      Split::DashboardPaginator.new(collection, page_number, pagination_per).paginate
+    end
+
+    def pagination(collection)
+      html = []
+      html << first_page_tag if show_first_page_tag?
+      html << ellipsis_tag if show_first_ellipsis_tag?
+      html << prev_page_tag if show_prev_page_tag?
+      html << current_page_tag
+      html << next_page_tag if show_next_page_tag?(collection)
+      html << ellipsis_tag if show_last_ellipsis_tag?(collection)
+      html << last_page_tag(collection) if show_last_page_tag?(collection)
+      html.join
+    end
+
+    private
+
+    def show_first_page_tag?
+      page_number > 2
+    end
+
+    def first_page_tag
+      %Q(<a href="#{url.chop}?page=1&per=#{pagination_per}">1</a>)
+    end
+
+    def show_first_ellipsis_tag?
+      page_number >= 4
+    end
+
+    def ellipsis_tag
+      '<span>...</span>'
+    end
+
+    def show_prev_page_tag?
+      page_number > 1
+    end
+
+    def prev_page_tag
+      %Q(<a href="#{url.chop}?page=#{page_number - 1}&per=#{pagination_per}">#{page_number - 1}</a>)
+    end
+
+    def current_page_tag
+      "<span><b>#{page_number}</b></span>"
+    end
+
+    def show_next_page_tag?(collection)
+      (page_number * pagination_per) < collection.count
+    end
+
+    def next_page_tag
+      %Q(<a href="#{url.chop}?page=#{page_number + 1}&per=#{pagination_per}">#{page_number + 1}</a>)
+    end
+
+    def show_last_ellipsis_tag?(collection)
+      (total_pages(collection) - page_number) >= 3
+    end
+
+    def total_pages(collection)
+      collection.count / pagination_per + ((collection.count % pagination_per).zero? ? 0 : 1)
+    end
+
+    def show_last_page_tag?(collection)
+      page_number < (total_pages(collection) - 1)
+    end
+
+    def last_page_tag(collection)
+      total = total_pages(collection)
+      %Q(<a href="#{url.chop}?page=#{total}&per=#{pagination_per}">#{total}</a>)
+    end
+  end
+end