trailguide 0.1.13 → 0.1.14

data/lib/trail_guide/experiment.rb

@@ -1,242 +1,9 @@
-require "trail_guide/experiment_config"
+require "trail_guide/experiments/base"
 
 module TrailGuide
-  class Experiment
-    class << self
-      delegate :metric, :algorithm, :control, :goals, :callbacks,
-        :allow_multiple_conversions?, :allow_multiple_goals?, to: :configuration
-      alias_method :funnels, :goals
-
-      def inherited(child)
-        TrailGuide::Catalog.register(child)
-      end
-
-      def configuration
-        @configuration ||= ExperimentConfig.new(self)
-      end
-
-      def configure(*args, &block)
-        configuration.configure(*args, &block)
-      end
-
-      def resettable?
-        !configuration.reset_manually
-      end
-
-      def experiment_name
-        configuration.name
-      end
-
-      def variants(include_control=true)
-        if include_control
-          configuration.variants
-        else
-          configuration.variants.select { |var| !var.control? }
-        end
-      end
-
-      def run_callbacks(hook, *args)
-        return unless callbacks[hook]
-        args.unshift(self)
-        callbacks[hook].each do |callback|
-          if callback.respond_to?(:call)
-            callback.call(*args)
-          else
-            send(callback, *args)
-          end
-        end
-      end
-
-      def start!
-        return false if started?
-        save! unless persisted?
-        started = TrailGuide.redis.hset(storage_key, 'started_at', Time.now.to_i)
-        run_callbacks(:on_start)
-        started
-      end
-
-      def stop!
-        return false unless running?
-        stopped = TrailGuide.redis.hset(storage_key, 'stopped_at', Time.now.to_i)
-        run_callbacks(:on_stop)
-        stopped
-      end
-
-      def resume!
-        return false unless started? && stopped?
-        restarted = TrailGuide.redis.hdel(storage_key, 'stopped_at')
-        run_callbacks(:on_resume)
-        restarted
-      end
-
-      def started_at
-        started = TrailGuide.redis.hget(storage_key, 'started_at')
-        return Time.at(started.to_i) if started
-      end
-
-      def stopped_at
-        stopped = TrailGuide.redis.hget(storage_key, 'stopped_at')
-        return Time.at(stopped.to_i) if stopped
-      end
-
-      def started?
-        !!started_at
-      end
-
-      def stopped?
-        !!stopped_at
-      end
-
-      def running?
-        started? && !stopped?
-      end
-
-      def declare_winner!(variant)
-        variant = variant.name if variant.is_a?(Variant)
-        TrailGuide.redis.hset(storage_key, 'winner', variant.to_s.underscore)
-      end
-
-      def clear_winner!
-        TrailGuide.redis.hdel(storage_key, 'winner')
-      end
-
-      def winner
-        winner = TrailGuide.redis.hget(storage_key, 'winner')
-        return variants.find { |var| var == winner } if winner
-      end
-
-      def winner?
-        TrailGuide.redis.hexists(storage_key, 'winner')
-      end
-
-      def persisted?
-        TrailGuide.redis.exists(storage_key)
-      end
-
-      def save!
-        variants.each(&:save!)
-        TrailGuide.redis.hsetnx(storage_key, 'name', experiment_name)
-      end
-
-      def delete!
-        variants.each(&:delete!)
-        deleted = TrailGuide.redis.del(storage_key)
-        run_callbacks(:on_delete)
-        deleted
-      end
-
-      def reset!
-        reset = (delete! && save!)
-        run_callbacks(:on_reset)
-        reset
-      end
-
-      def as_json(opts={})
-        { experiment_name => {
-          configuration: {
-            metric: metric,
-            algorithm: algorithm.name,
-            variants: variants.as_json,
-            goals: goals.as_json,
-            resettable: resettable?,
-            allow_multiple_conversions: allow_multiple_conversions?,
-            allow_multiple_goals: allow_multiple_goals?
-          },
-          statistics: {
-            # TODO expand on this for variants/goals
-            participants: variants.sum(&:participants),
-            converted: variants.sum(&:converted)
-          }
-        } }
-      end
-
-      def storage_key
-        experiment_name
-      end
-    end
-
-    attr_reader :participant
-    delegate :configuration, :experiment_name, :variants, :control, :funnels,
-      :storage_key, :running?, :started?, :started_at, :start!, :resettable?,
-      :winner?, :winner, :allow_multiple_conversions?, :allow_multiple_goals?,
-      :callbacks, to: :class
-
-    def initialize(participant)
-      @participant = participant
-    end
-
-    def algorithm
-      @algorithm ||= self.class.algorithm.new(self)
-    end
-
-    def choose!(override: nil, metadata: nil, **opts)
-      return control if TrailGuide.configuration.disabled
-
-      variant = choose_variant!(override: override, metadata: metadata, **opts)
-      participant.participating!(variant) unless override.present? && !configuration.store_override
-      run_callbacks(:on_use, variant, metadata)
-      variant
-    end
-
-    def choose_variant!(override: nil, excluded: false, metadata: nil)
-      return control if TrailGuide.configuration.disabled
-      if override.present?
-        variant = variants.find { |var| var == override }
-        return variant unless configuration.track_override && running?
-      else
-        return winner if winner?
-        return control if excluded
-        return control if !started? && configuration.start_manually
-        start! unless started?
-        return control unless running?
-        return variants.find { |var| var == participant[storage_key] } if participating?
-        return control unless TrailGuide.configuration.allow_multiple_experiments == true || !participant.participating_in_active_experiments?(TrailGuide.configuration.allow_multiple_experiments == false) 
-
-        variant = algorithm.choose!(metadata: metadata)
-      end
-
-      variant.increment_participation!
-      run_callbacks(:on_choose, variant, metadata)
-      variant
-    end
-
-    def convert!(checkpoint=nil, metadata: nil)
-      return false unless participating?
-      raise InvalidGoalError, "Invalid goal checkpoint `#{checkpoint}` for `#{experiment_name}`." unless checkpoint.present? || funnels.empty?
-      raise InvalidGoalError, "Invalid goal checkpoint `#{checkpoint}` for `#{experiment_name}`." unless checkpoint.nil? || funnels.any? { |funnel| funnel == checkpoint.to_s.underscore.to_sym }
-      # TODO eventually allow progressing through funnel checkpoints towards goals
-      if converted?(checkpoint)
-        return false unless allow_multiple_conversions?
-      elsif converted?
-        return false unless allow_multiple_goals?
-      end
-
-      variant = variants.find { |var| var == participant[storage_key] }
-      # TODO eventually only reset if we're at the final goal in a funnel
-      participant.converted!(variant, checkpoint, reset: resettable?)
-      variant.increment_conversion!(checkpoint)
-      run_callbacks(:on_convert, variant, checkpoint, metadata)
-      variant
-    end
-
-    def participating?
-      participant.participating?(self)
-    end
-
-    def converted?(checkpoint=nil)
-      participant.converted?(self, checkpoint)
-    end
-
-    def run_callbacks(hook, *args)
-      return unless callbacks[hook]
-      args.unshift(self)
-      callbacks[hook].each do |callback|
-        if callback.respond_to?(:call)
-          callback.call(*args)
-        else
-          send(callback, *args)
-        end
-      end
+  class Experiment < Experiments::Base
+    def self.inherited(child)
+      TrailGuide.catalog.register(child)
     end
   end
 end

data/lib/trail_guide/experiments/base.rb

@@ -0,0 +1,268 @@
+require "trail_guide/experiments/config"
+
+module TrailGuide
+  module Experiments
+    class Base
+      class << self
+        delegate :metric, :algorithm, :control, :goals, :callbacks, :combined,
+          :combined?, :allow_multiple_conversions?, :allow_multiple_goals?,
+          :track_winner_conversions?, to: :configuration
+        alias_method :funnels, :goals
+
+        def configuration
+          @configuration ||= Experiments::Config.new(self)
+        end
+
+        def configure(*args, &block)
+          configuration.configure(*args, &block)
+        end
+
+        def resettable?
+          !configuration.reset_manually
+        end
+
+        def experiment_name
+          configuration.name
+        end
+
+        def variants(include_control=true)
+          if include_control
+            configuration.variants
+          else
+            configuration.variants.select { |var| !var.control? }
+          end
+        end
+
+        def run_callbacks(hook, *args)
+          return unless callbacks[hook]
+          return args[0] if hook == :return_winner
+          args.unshift(self)
+          callbacks[hook].each do |callback|
+            if callback.respond_to?(:call)
+              callback.call(*args)
+            else
+              send(callback, *args)
+            end
+          end
+        end
+
+        def start!
+          return false if started?
+          save! unless persisted?
+          started = TrailGuide.redis.hset(storage_key, 'started_at', Time.now.to_i)
+          run_callbacks(:on_start)
+          started
+        end
+
+        def stop!
+          return false unless running?
+          stopped = TrailGuide.redis.hset(storage_key, 'stopped_at', Time.now.to_i)
+          run_callbacks(:on_stop)
+          stopped
+        end
+
+        def resume!
+          return false unless started? && stopped?
+          restarted = TrailGuide.redis.hdel(storage_key, 'stopped_at')
+          run_callbacks(:on_resume)
+          restarted
+        end
+
+        def started_at
+          started = TrailGuide.redis.hget(storage_key, 'started_at')
+          return Time.at(started.to_i) if started
+        end
+
+        def stopped_at
+          stopped = TrailGuide.redis.hget(storage_key, 'stopped_at')
+          return Time.at(stopped.to_i) if stopped
+        end
+
+        def started?
+          !!started_at
+        end
+
+        def stopped?
+          !!stopped_at
+        end
+
+        def running?
+          started? && !stopped?
+        end
+
+        def declare_winner!(variant)
+          variant = variants.find { |var| var == variant } unless variant.is_a?(Variant)
+          run_callbacks(:on_winner, variant)
+          TrailGuide.redis.hset(storage_key, 'winner', variant.name.to_s.underscore)
+        end
+
+        def clear_winner!
+          TrailGuide.redis.hdel(storage_key, 'winner')
+        end
+
+        def winner
+          winner = TrailGuide.redis.hget(storage_key, 'winner')
+          return variants.find { |var| var == winner } if winner
+        end
+
+        def winner?
+          TrailGuide.redis.hexists(storage_key, 'winner')
+        end
+
+        def persisted?
+          TrailGuide.redis.exists(storage_key)
+        end
+
+        def save!
+          combined.each { |combo| TrailGuide.catalog.find(combo).save! }
+          variants.each(&:save!)
+          TrailGuide.redis.hsetnx(storage_key, 'name', experiment_name)
+        end
+
+        def delete!
+          combined.each { |combo| TrailGuide.catalog.find(combo).delete! }
+          variants.each(&:delete!)
+          deleted = TrailGuide.redis.del(storage_key)
+          run_callbacks(:on_delete)
+          deleted
+        end
+
+        def reset!
+          reset = (delete! && save!)
+          run_callbacks(:on_reset)
+          reset
+        end
+
+        def as_json(opts={})
+          { experiment_name => {
+            configuration: {
+              metric: metric,
+              algorithm: algorithm.name,
+              variants: variants.as_json,
+              goals: goals.as_json,
+              resettable: resettable?,
+              allow_multiple_conversions: allow_multiple_conversions?,
+              allow_multiple_goals: allow_multiple_goals?
+            },
+            statistics: {
+              # TODO expand on this for variants/goals
+              participants: variants.sum(&:participants),
+              converted: variants.sum(&:converted)
+            }
+          } }
+        end
+
+        def storage_key
+          configuration.name
+        end
+      end
+
+      attr_reader :participant
+      delegate :configuration, :experiment_name, :variants, :control, :funnels,
+        :storage_key, :running?, :started?, :started_at, :start!, :resettable?,
+        :winner?, :allow_multiple_conversions?, :allow_multiple_goals?,
+        :track_winner_conversions?, :callbacks, to: :class
+
+      def initialize(participant)
+        @participant = participant
+      end
+
+      def algorithm
+        @algorithm ||= self.class.algorithm.new(self)
+      end
+
+      def winner
+        run_callbacks(:return_winner, self.class.winner)
+      end
+
+      def choose!(override: nil, metadata: nil, **opts)
+        return control if TrailGuide.configuration.disabled
+
+        variant = choose_variant!(override: override, metadata: metadata, **opts)
+        participant.participating!(variant) unless override.present? && !configuration.store_override
+        run_callbacks(:on_use, variant, metadata)
+        variant
+      end
+
+      def choose_variant!(override: nil, excluded: false, metadata: nil)
+        return control if TrailGuide.configuration.disabled
+        if override.present?
+          variant = variants.find { |var| var == override }
+          return variant unless configuration.track_override && running?
+        else
+          if winner?
+            variant = winner
+            return variant unless track_winner_conversions? && running?
+          else
+            return control if excluded
+            return control if !started? && configuration.start_manually
+            start! unless started?
+            return control unless running?
+            return variants.find { |var| var == participant[storage_key] } if participating?
+            return control unless TrailGuide.configuration.allow_multiple_experiments == true || !participant.participating_in_active_experiments?(TrailGuide.configuration.allow_multiple_experiments == false) 
+
+            variant = algorithm_choose!(metadata: metadata)
+          end
+        end
+
+        variant.increment_participation!
+        run_callbacks(:on_choose, variant, metadata)
+        variant
+      end
+
+      def algorithm_choose!(metadata: nil)
+        algorithm.choose!(metadata: metadata)
+      end
+
+      def convert!(checkpoint=nil, metadata: nil)
+        return false if !running? || (winner? && !track_winner_conversions?)
+        return false unless participating?
+        raise InvalidGoalError, "Invalid goal checkpoint `#{checkpoint}` for `#{experiment_name}`." unless checkpoint.present? || funnels.empty?
+        raise InvalidGoalError, "Invalid goal checkpoint `#{checkpoint}` for `#{experiment_name}`." unless checkpoint.nil? || funnels.any? { |funnel| funnel == checkpoint.to_s.underscore.to_sym }
+        # TODO eventually allow progressing through funnel checkpoints towards goals
+        if converted?(checkpoint)
+          return false unless allow_multiple_conversions?
+        elsif converted?
+          return false unless allow_multiple_goals?
+        end
+
+        variant = variants.find { |var| var == participant[storage_key] }
+        # TODO eventually only reset if we're at the final goal in a funnel
+        participant.converted!(variant, checkpoint, reset: resettable?)
+        variant.increment_conversion!(checkpoint)
+        run_callbacks(:on_convert, variant, checkpoint, metadata)
+        variant
+      end
+
+      def participating?
+        participant.participating?(self)
+      end
+
+      def converted?(checkpoint=nil)
+        participant.converted?(self, checkpoint)
+      end
+
+      def run_callbacks(hook, *args)
+        return unless callbacks[hook]
+        if hook == :return_winner
+          callbacks[hook].reduce(args[0]) do |winner, callback|
+            if callback.respond_to?(:call)
+              callback.call(self, winner)
+            else
+              send(callback, self, winner)
+            end
+          end
+        else
+          args.unshift(self)
+          callbacks[hook].each do |callback|
+            if callback.respond_to?(:call)
+              callback.call(*args)
+            else
+              send(callback, *args)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/trail_guide/experiments/combined_config.rb

@@ -0,0 +1,12 @@
+require "trail_guide/experiments/config"
+
+module TrailGuide
+  module Experiments
+    class CombinedConfig < Config
+      def initialize(experiment, *args, **opts, &block)
+        args.push(:parent)
+        super(experiment, *args, **opts, &block)
+      end
+    end
+  end
+end

data/lib/trail_guide/experiments/config.rb

@@ -0,0 +1,158 @@
+module TrailGuide
+  module Experiments
+    class Config < Canfig::Config
+      ENGINE_CONFIG_KEYS = [
+        :start_manually, :reset_manually, :store_override, :track_override,
+        :algorithm, :allow_multiple_conversions, :allow_multiple_goals,
+        :track_winner_conversions
+      ].freeze
+
+      def self.engine_config
+        ENGINE_CONFIG_KEYS.map do |key|
+          [key, TrailGuide.configuration.send(key.to_sym)]
+        end.to_h
+      end
+
+      def self.default_config
+        { name: nil, metric: nil, variants: [], goals: [], combined: [] }
+      end
+
+      def self.callbacks_config
+        {
+          callbacks: {
+            on_choose:      [TrailGuide.configuration.on_experiment_choose].flatten.compact,
+            on_use:         [TrailGuide.configuration.on_experiment_use].flatten.compact,
+            on_convert:     [TrailGuide.configuration.on_experiment_convert].flatten.compact,
+            on_start:       [TrailGuide.configuration.on_experiment_start].flatten.compact,
+            on_stop:        [TrailGuide.configuration.on_experiment_stop].flatten.compact,
+            on_resume:      [TrailGuide.configuration.on_experiment_resume].flatten.compact,
+            on_winner:      [TrailGuide.configuration.on_experiment_winner].flatten.compact,
+            on_reset:       [TrailGuide.configuration.on_experiment_reset].flatten.compact,
+            on_delete:      [TrailGuide.configuration.on_experiment_delete].flatten.compact,
+            return_winner:  [TrailGuide.configuration.return_experiment_winner].flatten.compact,
+          }
+        }
+      end
+
+      attr_reader :experiment
+
+      def initialize(experiment, *args, **opts, &block)
+        @experiment = experiment
+        opts = opts.merge(self.class.engine_config)
+        opts = opts.merge(self.class.default_config)
+        opts = opts.merge(self.class.callbacks_config)
+        super(*args, **opts, &block)
+      end
+
+      def resettable?
+        !reset_manually
+      end
+
+      def allow_multiple_conversions?
+        allow_multiple_conversions
+      end
+
+      def allow_multiple_goals?
+        allow_multiple_goals
+      end
+
+      def track_winner_conversions?
+        track_winner_conversions
+      end
+
+      def name
+        @name ||= (self[:name] || experiment.name).try(:to_s).try(:underscore).try(:to_sym)
+      end
+
+      def metric
+        @metric ||= (self[:metric] || name).try(:to_s).try(:underscore).try(:to_sym)
+      end
+
+      def algorithm
+        @algorithm ||= TrailGuide::Algorithms.algorithm(self[:algorithm])
+      end
+
+      def variant(varname, metadata: {}, weight: 1, control: false)
+        raise ArgumentError, "The variant `#{varname}` already exists in the experiment `#{name}`" if variants.any? { |var| var == varname }
+        control = true if variants.empty?
+        variants.each(&:variant!) if control
+        variant = Variant.new(experiment, varname, metadata: metadata, weight: weight, control: control)
+        variants << variant
+        variant
+      end
+
+      def control
+        return variants.find { |var| var.control? } || variants.first
+      end
+
+      def control=(name)
+        variants.each(&:variant!)
+        var_idx = variants.index { |var| var == name }
+
+        if var_idx.nil?
+          variant = Variant.new(experiment, name, control: true)
+          variants.push(variant)
+        else
+          variant = variants[var_idx]
+          variant.control!
+        end
+
+        variant
+      end
+
+      def goal(name)
+        goals << name.to_s.underscore.to_sym
+      end
+      alias_method :funnel, :goal
+
+      def goals
+        self[:goals]
+      end
+      alias_method :funnels, :goals
+
+      def combined?
+        !combined.empty?
+      end
+
+      def on_choose(meth=nil, &block)
+        callbacks[:on_choose] << (meth || block)
+      end
+
+      def on_use(meth=nil, &block)
+        callbacks[:on_use] << (meth || block)
+      end
+
+      def on_convert(meth=nil, &block)
+        callbacks[:on_convert] << (meth || block)
+      end
+
+      def on_start(meth=nil, &block)
+        callbacks[:on_start] << (meth || block)
+      end
+
+      def on_stop(meth=nil, &block)
+        callbacks[:on_stop] << (meth || block)
+      end
+
+      def on_resume(meth=nil, &block)
+        callbacks[:on_resume] << (meth || block)
+      end
+
+      def on_winner(meth=nil, &block)
+        callbacks[:on_winner] << (meth || block)
+      end
+
+      def on_reset(meth=nil, &block)
+        callbacks[:on_reset] << (meth || block)
+      end
+
+      def on_delete(meth=nil, &block)
+        callbacks[:on_delete] << (meth || block)
+      end
+
+      def return_winner(meth=nil, &block)
+        callbacks[:return_winner] << (meth || block)
+      end
+    end
+  end
+end

data/lib/trail_guide/helper.rb

@@ -121,7 +121,7 @@ module TrailGuide
       end
 
       def experiments
-        @experiments ||= TrailGuide::Catalog.select(metric).map do |experiment|
+        @experiments ||= TrailGuide.catalog.select(metric).map do |experiment|
           experiment.new(participant)
         end
       end