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.



239
240
241
 
# File 'lib/trail_guide/experiments/base.rb', line 239

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

Instance Attribute Details

#participant ⇒ Object (readonly)

Returns the value of attribute participant.



233
234
235
 
# File 'lib/trail_guide/experiments/base.rb', line 233

def participant
  @participant
end

Class Method Details

.adapter ⇒ Object 



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

def adapter
  @adapter ||= TrailGuide::Adapters::Experiments::Redis.new(self)
end

.as_json(opts = {}) ⇒ Object

export the experiment state (not config) as json



218
219
220
221
222
223
224
225
226
 
# File 'lib/trail_guide/experiments/base.rb', line 218

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) 


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

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

.clear_winner! ⇒ Object 



157
158
159
 
# File 'lib/trail_guide/experiments/base.rb', line 157

def clear_winner!
  adapter.delete(:winner)
end

.combined_experiments ⇒ Object 



47
48
49
 
# File 'lib/trail_guide/experiments/base.rb', line 47

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 



203
204
205
 
# File 'lib/trail_guide/experiments/base.rb', line 203

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

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



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

def declare_winner!(variant, context=nil)
  variant = variants.find { |var| var == variant } unless variant.is_a?(Variant)
  return false unless variant.present? && variant.experiment == self
  run_callbacks(:on_winner, variant, context)
  adapter.set(:winner, variant.name)
  variant
end

.delete!(context = nil) ⇒ Object 



184
185
186
187
188
189
190
 
# File 'lib/trail_guide/experiments/base.rb', line 184

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

.experiment_name ⇒ Object

TODO alias name once specs have solid coverage



31
32
33
 
# File 'lib/trail_guide/experiments/base.rb', line 31

def experiment_name
  configuration.name
end

.fresh? ⇒ Boolean

Returns:

  • (Boolean) 


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

def fresh?
  !started? && !scheduled? && !winner?
end

.is_combined? ⇒ Boolean

Returns:

  • (Boolean) 


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

def is_combined?
  false
end

.participants ⇒ Object 



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

def participants
  variants.sum(&:participants)
end

.pause!(context = nil) ⇒ Object 



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

def pause!(context=nil)
  return false unless running? && configuration.can_resume?
  paused = adapter.set(:paused_at, Time.now.to_i)
  run_callbacks(:on_pause, context)
  paused
end

.paused? ⇒ Boolean

Returns:

  • (Boolean) 


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

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

.paused_at ⇒ Object 



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

def paused_at
  paused = adapter.get(:paused_at)
  return Time.at(paused.to_i) if paused
end

.persisted? ⇒ Boolean

Returns:

  • (Boolean) 


174
175
176
 
# File 'lib/trail_guide/experiments/base.rb', line 174

def persisted?
  adapter.persisted?
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 



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

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

.resume!(context = nil) ⇒ Object 



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

def resume!(context=nil)
  return false unless paused? && configuration.can_resume?
  resumed = adapter.delete(:paused_at)
  run_callbacks(:on_resume, context)
  !!resumed
end

.run_callbacks(hook, *args) ⇒ Object 



51
52
53
54
55
56
57
58
59
60
61
62
 
# File 'lib/trail_guide/experiments/base.rb', line 51

def run_callbacks(hook, *args)
  return unless callbacks[hook]
  return args[0] if hook == :rollout_winner # TODO do we need to account for this case here at the class level?
  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) 


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

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

.save! ⇒ Object 



178
179
180
181
182
 
# File 'lib/trail_guide/experiments/base.rb', line 178

def save!
  combined_experiments.each(&:save!)
  variants.each(&:save!)
  adapter.setnx(:name, experiment_name)
end

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



72
73
74
75
76
77
78
79
 
# File 'lib/trail_guide/experiments/base.rb', line 72

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

.scheduled? ⇒ Boolean

Returns:

  • (Boolean) 


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

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

.start!(context = nil) ⇒ Object 



64
65
66
67
68
69
70
 
# File 'lib/trail_guide/experiments/base.rb', line 64

def start!(context=nil)
  return false if started?
  save! unless persisted?
  started = adapter.set(:started_at, Time.now.to_i)
  run_callbacks(:on_start, context)
  started
end

.started? ⇒ Boolean

Returns:

  • (Boolean) 


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

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

.started_at ⇒ Object 



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

def started_at
  started = adapter.get(:started_at)
  return Time.at(started.to_i) if started
end

.stop!(context = nil) ⇒ Object 



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

def stop!(context=nil)
  return false unless started? && !stopped?
  stopped = adapter.set(:stopped_at, Time.now.to_i)
  run_callbacks(:on_stop, context)
  stopped
end

.stopped? ⇒ Boolean

Returns:

  • (Boolean) 


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

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

.stopped_at ⇒ Object 



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

def stopped_at
  stopped = adapter.get(:stopped_at)
  return Time.at(stopped.to_i) if stopped
end

.storage_key ⇒ Object 



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

def storage_key
  configuration.name
end

.target_sample_size_reached? ⇒ Boolean

Returns:

  • (Boolean) 


211
212
213
214
215
 
# File 'lib/trail_guide/experiments/base.rb', line 211

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 



207
208
209
 
# File 'lib/trail_guide/experiments/base.rb', line 207

def unconverted
  participants - converted
end

.variants(include_control = true) ⇒ Object 



35
36
37
38
39
40
41
 
# File 'lib/trail_guide/experiments/base.rb', line 35

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

.winner ⇒ Object 



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

def winner
  winner = adapter.get(:winner)
  return variants.find { |var| var == winner } if winner
end

.winner? ⇒ Boolean

Returns:

  • (Boolean) 


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

def winner?
  if combined?
    combined.all? { |combo| TrailGuide.catalog.find(combo).winner? }
  else
    adapter.exists?(:winner)
  end
end

Instance Method Details

#algorithm ⇒ Object 



243
244
245
 
# File 'lib/trail_guide/experiments/base.rb', line 243

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

#algorithm_choose!(metadata: nil) ⇒ Object 



328
329
330
 
# File 'lib/trail_guide/experiments/base.rb', line 328

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

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

Returns:

  • (Boolean) 


385
386
387
388
389
390
391
392
393
 
# File 'lib/trail_guide/experiments/base.rb', line 385

def allow_conversion?(variant, checkpoint=nil, metadata=nil)
  if checkpoint.nil?
    return true if callbacks[:allow_conversion].empty?
    # TODO why pass checkpoint through here if checkpoints are handled by their own method? it will always be nil here given current logic
    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) 


380
381
382
383
 
# File 'lib/trail_guide/experiments/base.rb', line 380

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

#calibrating? ⇒ Boolean

Returns:

  • (Boolean) 


469
470
471
 
# File 'lib/trail_guide/experiments/base.rb', line 469

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

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



252
253
254
255
256
257
258
259
260
261
262
 
# File 'lib/trail_guide/experiments/base.rb', line 252

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 



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
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
 
# File 'lib/trail_guide/experiments/base.rb', line 264

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?

  # only re-use the variant for experiments that store participation,
  # all other (i.e. content-based) experiments should re-select and
  # re-assign on enrollment
  if configuration.sticky_assignment? && 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 



417
418
419
420
421
 
# File 'lib/trail_guide/experiments/base.rb', line 417

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

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



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
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
 
# File 'lib/trail_guide/experiments/base.rb', line 332

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) 


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

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

#paused_at ⇒ Object 



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

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

#run_callbacks(hook, *args) ⇒ Object 



395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
 
# File 'lib/trail_guide/experiments/base.rb', line 395

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) 


465
466
467
 
# File 'lib/trail_guide/experiments/base.rb', line 465

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

#scheduled? ⇒ Boolean

Returns:

  • (Boolean) 


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

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



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

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

#started? ⇒ Boolean

Returns:

  • (Boolean) 


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

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

#started_at ⇒ Object 



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

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

#stopped? ⇒ Boolean

Returns:

  • (Boolean) 


461
462
463
 
# File 'lib/trail_guide/experiments/base.rb', line 461

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

#stopped_at ⇒ Object 



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

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

#winner ⇒ Object 



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

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

#winner? ⇒ Boolean

Returns:

  • (Boolean) 


473
474
475
476
 
# File 'lib/trail_guide/experiments/base.rb', line 473

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

#winning_variant ⇒ Object 



247
248
249
250
 
# File 'lib/trail_guide/experiments/base.rb', line 247

def winning_variant
  return nil unless winner?
  run_callbacks(:rollout_winner, winner, participant)
end