Class: TrailGuide::Experiments::Base

Inherits:
Object
  • Object
show all
Defined in:
lib/trail_guide/experiments/base.rb

Direct Known Subclasses

CombinedExperiment, TrailGuide::Experiment

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(participant) ⇒ Base

Returns a new instance of Base.



227
228
229
 
# File 'lib/trail_guide/experiments/base.rb', line 227

def initialize(participant)
  @participant = TrailGuide::Experiments::Participant.new(self, participant)
end

Instance Attribute Details

#participant ⇒ Object (readonly)

Returns the value of attribute participant.



221
222
223
 
# File 'lib/trail_guide/experiments/base.rb', line 221

def participant
  @participant
end

Class Method Details

.as_json(opts = {}) ⇒ Object

export the experiment state (not config) as json



206
207
208
209
210
211
212
213
214
 
# File 'lib/trail_guide/experiments/base.rb', line 206

def as_json(opts={})
  { experiment_name => {
    started_at: started_at,
    paused_at: paused_at,
    stopped_at: stopped_at,
    winner: winner.try(:name),
    variants: variants.map(&:as_json).reduce({}) { |r,v| r.merge!(v) },
  } }
end

.calibrating? ⇒ Boolean

Returns:

  • (Boolean) 


136
137
138
 
# File 'lib/trail_guide/experiments/base.rb', line 136

def calibrating?
  enable_calibration? && start_manually? && !started?
end

.clear_winner! ⇒ Object 



146
147
148
 
# File 'lib/trail_guide/experiments/base.rb', line 146

def clear_winner!
  TrailGuide.redis.hdel(storage_key, 'winner')
end

.combined_experiments ⇒ Object 



42
43
44
 
# File 'lib/trail_guide/experiments/base.rb', line 42

def combined_experiments
  combined.map { |combo| TrailGuide.catalog.find(combo) }
end

.configuration ⇒ Object 



18
19
20
 
# File 'lib/trail_guide/experiments/base.rb', line 18

def configuration
  @configuration ||= Experiments::Config.new(self)
end

.configure(*args, &block) ⇒ Object 



22
23
24
 
# File 'lib/trail_guide/experiments/base.rb', line 22

def configure(*args, &block)
  configuration.configure(*args, &block)
end

.converted(checkpoint = nil) ⇒ Object 



191
192
193
 
# File 'lib/trail_guide/experiments/base.rb', line 191

def converted(checkpoint=nil)
  variants.sum { |var| var.converted(checkpoint) }
end

.declare_winner!(variant, context = nil) ⇒ Object 



140
141
142
143
144
 
# File 'lib/trail_guide/experiments/base.rb', line 140

def declare_winner!(variant, context=nil)
  variant = variants.find { |var| var == variant } unless variant.is_a?(Variant)
  run_callbacks(:on_winner, variant, context)
  TrailGuide.redis.hset(storage_key, 'winner', variant.name.to_s.underscore)
end

.delete!(context = nil) ⇒ Object 



173
174
175
176
177
178
179
 
# File 'lib/trail_guide/experiments/base.rb', line 173

def delete!(context=nil)
  combined.each { |combo| TrailGuide.catalog.find(combo).delete! }
  variants.each(&:delete!)
  deleted = TrailGuide.redis.del(storage_key)
  run_callbacks(:on_delete, context)
  deleted
end

.experiment_name ⇒ Object 



26
27
28
 
# File 'lib/trail_guide/experiments/base.rb', line 26

def experiment_name
  configuration.name
end

.is_combined? ⇒ Boolean

Returns:

  • (Boolean) 


38
39
40
 
# File 'lib/trail_guide/experiments/base.rb', line 38

def is_combined?
  false
end

.participants ⇒ Object 



187
188
189
 
# File 'lib/trail_guide/experiments/base.rb', line 187

def participants
  variants.sum(&:participants)
end

.pause!(context = nil) ⇒ Object 



76
77
78
79
80
81
 
# File 'lib/trail_guide/experiments/base.rb', line 76

def pause!(context=nil)
  return false unless running? && configuration.can_resume?
  paused = TrailGuide.redis.hset(storage_key, 'paused_at', Time.now.to_i)
  run_callbacks(:on_pause, context)
  paused
end

.paused? ⇒ Boolean

Returns:

  • (Boolean) 


122
123
124
125
 
# File 'lib/trail_guide/experiments/base.rb', line 122

def paused?
  time = paused_at
  time && time <= Time.now
end

.paused_at ⇒ Object 



102
103
104
105
 
# File 'lib/trail_guide/experiments/base.rb', line 102

def paused_at
  paused = TrailGuide.redis.hget(storage_key, 'paused_at')
  return Time.at(paused.to_i) if paused
end

.persisted? ⇒ Boolean

Returns:

  • (Boolean) 


163
164
165
 
# File 'lib/trail_guide/experiments/base.rb', line 163

def persisted?
  TrailGuide.redis.exists(storage_key)
end

.register! ⇒ Object 



14
15
16
 
# File 'lib/trail_guide/experiments/base.rb', line 14

def register!
  TrailGuide.catalog.register(self)
end

.reset!(context = nil) ⇒ Object 



181
182
183
184
185
 
# File 'lib/trail_guide/experiments/base.rb', line 181

def reset!(context=nil)
  reset = (delete! && save!)
  run_callbacks(:on_reset, context)
  reset
end

.resume!(context = nil) ⇒ Object 



90
91
92
93
94
95
 
# File 'lib/trail_guide/experiments/base.rb', line 90

def resume!(context=nil)
  return false unless paused? && configuration.can_resume?
  resumed = TrailGuide.redis.hdel(storage_key, 'paused_at')
  run_callbacks(:on_resume, context)
  resumed
end

.run_callbacks(hook, *args) ⇒ Object 



46
47
48
49
50
51
52
53
54
55
56
57
 
# File 'lib/trail_guide/experiments/base.rb', line 46

def run_callbacks(hook, *args)
  return unless callbacks[hook]
  return args[0] if hook == :rollout_winner
  args.unshift(self)
  callbacks[hook].each do |callback|
    if callback.respond_to?(:call)
      callback.call(*args)
    else
      send(callback, *args)
    end
  end
end

.running? ⇒ Boolean

Returns:

  • (Boolean) 


132
133
134
 
# File 'lib/trail_guide/experiments/base.rb', line 132

def running?
  started? && !paused? && !stopped?
end

.save! ⇒ Object 



167
168
169
170
171
 
# File 'lib/trail_guide/experiments/base.rb', line 167

def save!
  combined.each { |combo| TrailGuide.catalog.find(combo).save! }
  variants.each(&:save!)
  TrailGuide.redis.hsetnx(storage_key, 'name', experiment_name)
end

.schedule!(start_at, stop_at = nil, context = nil) ⇒ Object 



67
68
69
70
71
72
73
74
 
# File 'lib/trail_guide/experiments/base.rb', line 67

def schedule!(start_at, stop_at=nil, context=nil)
  return false if started?
  save! unless persisted?
  scheduled = TrailGuide.redis.hset(storage_key, 'started_at', start_at.to_i)
  TrailGuide.redis.hset(storage_key, 'stopped_at', stop_at.to_i) if stop_at
  run_callbacks(:on_schedule, start_at, stop_at, context)
  scheduled
end

.scheduled? ⇒ Boolean

Returns:

  • (Boolean) 


117
118
119
120
 
# File 'lib/trail_guide/experiments/base.rb', line 117

def scheduled?
  time = started_at
  time && time > Time.now
end

.start!(context = nil) ⇒ Object 



59
60
61
62
63
64
65
 
# File 'lib/trail_guide/experiments/base.rb', line 59

def start!(context=nil)
  return false if started?
  save! unless persisted?
  started = TrailGuide.redis.hset(storage_key, 'started_at', Time.now.to_i)
  run_callbacks(:on_start, context)
  started
end

.started? ⇒ Boolean

Returns:

  • (Boolean) 


112
113
114
115
 
# File 'lib/trail_guide/experiments/base.rb', line 112

def started?
  time = started_at
  time && time <= Time.now
end

.started_at ⇒ Object 



97
98
99
100
 
# File 'lib/trail_guide/experiments/base.rb', line 97

def started_at
  started = TrailGuide.redis.hget(storage_key, 'started_at')
  return Time.at(started.to_i) if started
end

.stop!(context = nil) ⇒ Object 



83
84
85
86
87
88
 
# File 'lib/trail_guide/experiments/base.rb', line 83

def stop!(context=nil)
  return false unless started? && !stopped?
  stopped = TrailGuide.redis.hset(storage_key, 'stopped_at', Time.now.to_i)
  run_callbacks(:on_stop, context)
  stopped
end

.stopped? ⇒ Boolean

Returns:

  • (Boolean) 


127
128
129
130
 
# File 'lib/trail_guide/experiments/base.rb', line 127

def stopped?
  time = stopped_at
  time && time <= Time.now
end

.stopped_at ⇒ Object 



107
108
109
110
 
# File 'lib/trail_guide/experiments/base.rb', line 107

def stopped_at
  stopped = TrailGuide.redis.hget(storage_key, 'stopped_at')
  return Time.at(stopped.to_i) if stopped
end

.storage_key ⇒ Object 



216
217
218
 
# File 'lib/trail_guide/experiments/base.rb', line 216

def storage_key
  configuration.name
end

.target_sample_size_reached? ⇒ Boolean

Returns:

  • (Boolean) 


199
200
201
202
203
 
# File 'lib/trail_guide/experiments/base.rb', line 199

def target_sample_size_reached?
  return true unless configuration.target_sample_size
  return true if participants >= configuration.target_sample_size
  return false
end

.unconverted ⇒ Object 



195
196
197
 
# File 'lib/trail_guide/experiments/base.rb', line 195

def unconverted
  participants - converted
end

.variants(include_control = true) ⇒ Object 



30
31
32
33
34
35
36
 
# File 'lib/trail_guide/experiments/base.rb', line 30

def variants(include_control=true)
  if include_control
    configuration.variants
  else
    configuration.variants.select { |var| !var.control? }
  end
end

.winner ⇒ Object 



150
151
152
153
 
# File 'lib/trail_guide/experiments/base.rb', line 150

def winner
  winner = TrailGuide.redis.hget(storage_key, 'winner')
  return variants.find { |var| var == winner } if winner
end

.winner? ⇒ Boolean

Returns:

  • (Boolean) 


155
156
157
158
159
160
161
 
# File 'lib/trail_guide/experiments/base.rb', line 155

def winner?
  if combined?
    combined.all? { |combo| TrailGuide.catalog.find(combo).winner? }
  else
    TrailGuide.redis.hexists(storage_key, 'winner')
  end
end

Instance Method Details

#algorithm ⇒ Object 



231
232
233
 
# File 'lib/trail_guide/experiments/base.rb', line 231

def algorithm
  @algorithm ||= self.class.algorithm.new(self)
end

#algorithm_choose!(metadata: nil) ⇒ Object 



312
313
314
 
# File 'lib/trail_guide/experiments/base.rb', line 312

def algorithm_choose!(metadata: nil)
  algorithm.choose!(metadata: metadata)
end

#allow_conversion?(variant, checkpoint = nil, metadata = nil) ⇒ Boolean

Returns:

  • (Boolean) 


369
370
371
372
373
374
375
376
 
# File 'lib/trail_guide/experiments/base.rb', line 369

def allow_conversion?(variant, checkpoint=nil, metadata=nil)
  if checkpoint.nil?
    return true if callbacks[:allow_conversion].empty?
    run_callbacks(:allow_conversion, true, checkpoint, variant, participant, metadata)
  else
    checkpoint.allow_conversion?(self, variant, metadata)
  end
end

#allow_participation?(metadata = nil) ⇒ Boolean

Returns:

  • (Boolean) 


364
365
366
367
 
# File 'lib/trail_guide/experiments/base.rb', line 364

def allow_participation?(metadata=nil)
  return true if callbacks[:allow_participation].empty?
  run_callbacks(:allow_participation, true, participant, metadata)
end

#calibrating? ⇒ Boolean

Returns:

  • (Boolean) 


452
453
454
 
# File 'lib/trail_guide/experiments/base.rb', line 452

def calibrating?
  enable_calibration? && start_manually? && !started?
end

#choose!(override: nil, metadata: nil, **opts) ⇒ Object 



239
240
241
242
243
244
245
246
247
248
249
 
# File 'lib/trail_guide/experiments/base.rb', line 239

def choose!(override: nil, metadata: nil, **opts)
  return control if TrailGuide.configuration.disabled

  variant = choose_variant!(override: override, metadata: metadata, **opts)
  run_callbacks(:on_use, variant, participant, metadata)
  variant
rescue Errno::ECONNREFUSED, Redis::BaseError, SocketError => e
  run_callbacks(:on_redis_failover, e)
  return variants.find { |var| var == override } || control if override.present?
  return control
end

#choose_variant!(override: nil, excluded: false, metadata: nil) ⇒ Object 



251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
 
# File 'lib/trail_guide/experiments/base.rb', line 251

def choose_variant!(override: nil, excluded: false, metadata: nil)
  return control if TrailGuide.configuration.disabled

  if override.present?
    variant = variants.find { |var| var == override } || control
    if running? && !is_combined?
      variant.increment_participation! if configuration.track_override
      participant.participating!(variant) if configuration.store_override
    end
    return variant
  end

  if winner?
    variant = winning_variant
    if track_winner_conversions? && running?
      variant.increment_participation! unless participant.variant == variant
      participant.exit! if participant.participating? && participant.variant != variant
      participant.participating!(variant)
    end
    return variant
  end

  return control if excluded || stopped?

  if !started? && start_manually?
    if enable_calibration?
      unless participant.variant == control
        control.increment_participation!
        parent.control.increment_participation! if is_combined?
      end

      if participant.participating? && participant.variant != control
        participant.exit!
        parent.participant.exit! if is_combined?
      end

      participant.participating!(control)
      parent.participant.participating!(parent.control) if is_combined?
    end
    return control
  end

  start! unless started? || scheduled?
  return control unless running?

  if participant.participating?
    variant = participant.variant
    participant.participating!(variant)
    return variant
  end

  return control unless is_combined? || TrailGuide.configuration.allow_multiple_experiments == true || !participant.participating_in_active_experiments?(TrailGuide.configuration.allow_multiple_experiments == false)
  return control unless allow_participation?(metadata)

  variant = algorithm_choose!(metadata: metadata)
  variant.increment_participation!
  participant.participating!(variant)
  run_callbacks(:on_choose, variant, participant, metadata)
  variant
end

#combined_experiments ⇒ Object 



400
401
402
403
404
 
# File 'lib/trail_guide/experiments/base.rb', line 400

def combined_experiments
  @combined_experiments ||= self.class.combined_experiments.map do |combo|
    combo.new(participant.participant)
  end
end

#convert!(checkpoint = nil, metadata: nil) ⇒ Object 



316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
 
# File 'lib/trail_guide/experiments/base.rb', line 316

def convert!(checkpoint=nil, metadata: nil)
  if !started?
    return false unless enable_calibration?
    variant = participant.variant
    return false unless variant.present? && variant == control
  else
    return false unless running?
    variant = participant.variant
    return false unless variant.present?

    if winner?
      return false unless track_winner_conversions? && variant == winner
    end
  end

  if checkpoint.nil?
    raise InvalidGoalError, "You must provide a valid goal checkpoint for `#{experiment_name}`." unless goals.empty?
  else
    goal = goals.find { |g| g == checkpoint }
    raise InvalidGoalError, "Invalid goal checkpoint `#{checkpoint}` for `#{experiment_name}`." if goal.nil?
    checkpoint = goal
  end

  # TODO eventually allow progressing through funnel checkpoints towards goals
  if participant.converted?(checkpoint)
    return false unless (checkpoint.nil? && allow_multiple_conversions?) || (checkpoint.present? && checkpoint.allow_multiple_conversions?)
  elsif participant.converted?
    return false unless allow_multiple_goals?
  end
  return false unless allow_conversion?(variant, checkpoint, metadata)

  # TODO only reset if !reset_manually? AND they've converted all goals if
  # allow_multiple_goals? is set
  # TODO what should happen when allow_multiple_conversions? and !reset_manually?
  # TODO eventually only reset if we're at the final goal in a funnel
  participant.converted!(variant, checkpoint, reset: !reset_manually?)
  variant.increment_conversion!(checkpoint)
  if checkpoint.nil?
    run_callbacks(:on_convert, checkpoint, variant, participant, metadata)
  else
    checkpoint.run_callbacks(:on_convert, self, variant, participant, metadata)
  end
  variant
rescue Errno::ECONNREFUSED, Redis::BaseError, SocketError => e
  run_callbacks(:on_redis_failover, e)
  return false
end

#paused? ⇒ Boolean

Returns:

  • (Boolean) 


440
441
442
 
# File 'lib/trail_guide/experiments/base.rb', line 440

def paused?
  paused_at && paused_at <= Time.now
end

#paused_at ⇒ Object 



420
421
422
 
# File 'lib/trail_guide/experiments/base.rb', line 420

def paused_at
  @paused_at ||= self.class.paused_at
end

#run_callbacks(hook, *args) ⇒ Object 



378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
 
# File 'lib/trail_guide/experiments/base.rb', line 378

def run_callbacks(hook, *args)
  return unless callbacks[hook]
  if [:allow_participation, :allow_conversion, :rollout_winner].include?(hook)
    callbacks[hook].reduce(args.slice!(0,1)[0]) do |result, callback|
      if callback.respond_to?(:call)
        callback.call(self, result, *args)
      else
        send(callback, self, result, *args)
      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

#running? ⇒ Boolean

Returns:

  • (Boolean) 


448
449
450
 
# File 'lib/trail_guide/experiments/base.rb', line 448

def running?
  started? && !paused? && !stopped?
end

#scheduled? ⇒ Boolean

Returns:

  • (Boolean) 


432
433
434
 
# File 'lib/trail_guide/experiments/base.rb', line 432

def scheduled?
  started_at && started_at > Time.now
end

#start! ⇒ Object

MEMOIZATOIN ### This is a lot of seemingly unnecessary duplication, but it really helps to cut down on the number of redis requests while still being thread-safe by memoizing these methods/values here at the instance level



411
412
413
414
 
# File 'lib/trail_guide/experiments/base.rb', line 411

def start!
  @started_at = nil
  self.class.start!
end

#started? ⇒ Boolean

Returns:

  • (Boolean) 


436
437
438
 
# File 'lib/trail_guide/experiments/base.rb', line 436

def started?
  started_at && started_at <= Time.now
end

#started_at ⇒ Object 



416
417
418
 
# File 'lib/trail_guide/experiments/base.rb', line 416

def started_at
  @started_at ||= self.class.started_at
end

#stopped? ⇒ Boolean

Returns:

  • (Boolean) 


444
445
446
 
# File 'lib/trail_guide/experiments/base.rb', line 444

def stopped?
  stopped_at && stopped_at <= Time.now
end

#stopped_at ⇒ Object 



424
425
426
 
# File 'lib/trail_guide/experiments/base.rb', line 424

def stopped_at
  @stopped_at ||= self.class.stopped_at
end

#winner ⇒ Object 



428
429
430
 
# File 'lib/trail_guide/experiments/base.rb', line 428

def winner
  @winner ||= self.class.winner
end

#winner? ⇒ Boolean

Returns:

  • (Boolean) 


456
457
458
459
 
# File 'lib/trail_guide/experiments/base.rb', line 456

def winner?
  return @has_winner unless @has_winner.nil?
  @has_winner = self.class.winner?
end

#winning_variant ⇒ Object 



235
236
237
 
# File 'lib/trail_guide/experiments/base.rb', line 235

def winning_variant
  run_callbacks(:rollout_winner, self.class.winner, participant)
end