pick_me_too 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ac4906dd27b93c363b8e9af9e82ffe636c3149519d79654a7b8a2f0a2bdfdf25
+  data.tar.gz: a902f070e98dc4fab62695fe7e556e499ad33c3d1dd2b0dc21764923b37f310f
+SHA512:
+  metadata.gz: 73f4816247afc780c1dae9c5399fbc1280db8795d191f575fd4829d39ea8b5f39f61974d9953a0883f25160dcd256feabefe0e75ddc323728523c9fa3a2c997c
+  data.tar.gz: ef409f69716637d562c45b52d2ea71843e2bfb3fe568d2dfd82447084a27cd93cae9fdf99f1a4decbe37036db1639d2332fe6debfb13ed5f268c5dffae632456

data/.gitignore

@@ -0,0 +1,4 @@
+.byebug_history
+*.swp
+.ruby-version
+

data/CHANGES.md

@@ -0,0 +1,4 @@
+# Change Log
+
+## 1.0.0 *2022-8-14*
+* initial release

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 David Fairchild Houghton
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,101 @@
+# pick_me_too
+
+Pick things randomly from a list of things with specified frequencies.
+
+This is what is known as an [urn model](https://en.wikipedia.org/wiki/Urn_problem).
+
+# Synopsis
+
+```ruby
+require 'pick_me_too'
+
+# optionally make a seeded random number sequence
+rng = Random.new 1
+
+# make a picker that uses this
+picker = PickMeToo.new([["prevention", 1], ["cure", 16]], -> { rng.rand })
+
+counter = Hash.new 0
+32.times { counter[picker.pick] += 1 }
+counter
+# => {"cure"=>29, "prevention"=>3}
+
+# you can also use a hash to map items to frequencies
+# frequencies don't need to be whole numbers
+# items don't need to be strings
+
+rng = Random.new 1
+picker = PickMeToo.new({foo: 1, bar: 2, baz: 0.5}, -> { rng.rand })
+counter = Hash.new 0
+32.times { counter[picker.pick] += 1 }
+counter
+# => {:foo=>13, :bar=>12, :baz=>7}
+
+# you don't need to provide your own random number sequence
+picker = PickMeToo({a: 1, b: 2, c: 3})
+# ...
+```
+
+# What is this for?
+
+Suppose you are simulating some phenomenon, wandering monsters in a dungeon, say, weather on particular day, or
+the vowel in a random syllable in a random word in a random language. These things are representable as a list
+of frequencies:
+- goblin, 10; orc: 5; centipede: 15; ...
+- sunny: 10; rainy: 5; cloudy: 15; ...
+- a: 10; u: 5; e: 15; ...
+
+What you need is something that will randomly pick these things for you with the frequencies you specify.
+
+One way to do this would be to make an array, filling it with the items according to the frequencies specified
+and then pick randomly from the array:
+
+```ruby
+  monsters = %i[goblin] * 10 + %i[orc] * 5 + %i[centipede] * 15
+  monster = monsters[(monsters.length * rand).floor]
+```
+
+This is inefficient or impossible if the frequencies are huge or excessively precise. Say you want pi orcs in your list and e goblins.
+
+`PickMeToo` requires just one item of each type. It converts the frequencies to probabilities and walks a tree of numeric comparisons to
+choose an item given a random number. The tree of comparisons is optimized so, for example, if one item represents 50% or more of the
+frequencies it will be selected with a single comparison.
+
+
+# API
+
+## `PickMeToo`
+
+This is the "[urn](https://en.wikipedia.org/wiki/Urn_problem)" containing the items selected.
+
+## `PickMeToo.new(frequences, [rnd])`
+
+"Fill" the urn.
+
+The required `frequencies` parameter must be something that is effectivly a list of pairs:
+things to pick paired with their frequency. The "frequency" is just any positive number.
+
+The optional `rnd` parameter is a `Proc` that when called returns a number, ideally in the interval
+[0, 1]. This parameter allows you to provided a seeded random number generator, so the choices
+occur in a predictable sequence, which is useful for testing.
+
+This constructor method will raise a `PickMeToo::Error` if
+- there are no pairs in the frequency list
+- any of the frequencies is non-positive
+- any of the items in the list isn't something followed by a number
+
+## `PickMeToo#pick()`
+
+Draw an item from the urn.
+
+# Installation
+
+`pick_me_too` is available as a gem, so one installs it as one does gems.
+
+# License
+
+MIT. See the LICENSE file alongside this README.
+
+# Acknowledgements
+
+My son Jude helped me contemplate how to balance the probability tree.

data/Rakefile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.test_files = FileList['test/*_test.rb']
+end
+
+task default: :test

data/lib/pick_me_too.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+##
+# An "urn" from which you can pick things with specified frequencies.
+# 
+#   require 'pick_me_too'
+#
+#   wandering_monsters = PickMeToo.new({goblin: 10, bugbear: 2, orc: 5, spider: 3, troll: 1})
+#   10.times.map { wandering_monsters.pick }
+#   # => [:goblin, :orc, :bugbear, :orc, :goblin, :bugbear, :goblin, :goblin, :orc, :goblin]
+#
+#   irrational = PickMeToo.new({e: Math::E, pi: Math::PI})
+#   to.times.map { irrational.pick }
+#   # => [:e, :e, :e, :pi, :e, :e, :e, :pi, :pi, :e]
+#
+# Items once picked are "placed back in the urn", so if you pick a cat this doesn't reduce the
+# probability the next thing you pick is also a cat, and the urn will never be picked empty. (And of course
+# this is all a metaphor.)
+class PickMeToo
+  VERSION = '1.0.0'
+
+  class Error < StandardError; end
+
+  ##
+  # "Fill" the urn.
+  #
+  # The required frequencies parameter must be something that is effectivly a list of pairs:
+  # things to pick paired with their frequency. The "frequency" is just any positive number.
+  #
+  # The optional rnd parameter is a Proc that when called returns a number, ideally in the interval
+  # [0, 1]. This parameter allows you to provided a seeded random number generator, so the choices
+  # occur in a predictable sequence, which is useful for testing.
+  #
+  # This constructor method will raise a `PickMeToo::Error` if
+  # - there are no pairs in the frequency list
+  # - any of the frequencies is non-positive
+  # - any of the items in the list isn't something followed by a number
+  def initialize(frequencies, rnd = -> { rand })
+    @rnd = rnd
+    frequencies = prepare(Array(frequencies))
+    @objects = frequencies.map(&:first)
+    if @objects.length == 1
+      @picker = ->(_p) { 0 }
+    else
+      frequencies = frequencies.map(&:last)
+      balanced_binary_tree = bifurcate(frequencies.dup)
+      probability_tree = probabilities(frequencies, balanced_binary_tree)
+      # compile everything into a nested ternary expression
+      @picker = eval "->(p) { #{ternerize(probability_tree)} }"
+    end
+  end
+
+  ##
+  # Pick an item from the urn.
+  def pick
+    @objects[@picker.call(@rnd.call)]
+  end
+
+  private
+
+  # sanity check and normalization of frequencies
+  def prepare(frequencies)
+    raise Error, 'no frequencies given' unless frequencies.any?
+    unless frequencies.all? { |f| f.is_a?(Array) && f.length == 2 && f[1].is_a?(Numeric) }
+      raise Error, 'all frequencies must be two-member arrays the second member of which is Numeric'
+    end
+
+    good, bad = frequencies.partition { |*, n| n.positive? }
+    raise Error, "the following have non-positive frequencies: #{bad.inspect}" if bad.any?
+
+    total = good.map(&:last).sum.to_f
+    good.map { |o, n| [o, n / total] }
+  end
+
+  # reduce the probability tree to nested ternary expressions
+  def ternerize(ptree)
+    p, left, right = ptree.values_at :p, :left, :right
+    left = left.is_a?(Numeric) ? left : ternerize(left)
+    right = right.is_a?(Numeric) ? right : ternerize(right)
+    "(p > #{p} ? #{right} : #{left})"
+  end
+
+  def probabilities(frequencies, tree)
+    tree = sum_probabilities(tree, 0)
+    replace_frequencies_with_indices(tree, frequencies.each_with_index.to_a)
+    tree
+  end
+
+  def replace_frequencies_with_indices(tree, frequencies)
+    left, right = tree.values_at :left, :right
+    if left.is_a?(Numeric)
+      i = frequencies.index { |v,| v == left }
+      *, i = frequencies.slice!(i)
+      tree[:left] = i
+    else
+      replace_frequencies_with_indices(left, frequencies)
+    end
+    if right.is_a?(Numeric)
+      i = frequencies.index { |v,| v == right }
+      *, i = frequencies.slice!(i)
+      tree[:right] = i
+    else
+      replace_frequencies_with_indices(right, frequencies)
+    end
+  end
+
+  # convert the frequency numbers to probabilities
+  def sum_probabilities(tree, base)
+    left, right = tree
+    p = left.flatten.sum + base
+    left = left.length == 1 ? left.first : sum_probabilities(left, base)
+    right = right.length == 1 ? right.first : sum_probabilities(right, p)
+    { p: p, left: left, right: right }
+  end
+
+  # distribute the frequencies so their as balanced as possible
+  # the better to reduce expected length of the binary search
+  def bifurcate(nums)
+    return nums if nums.length < 2
+
+    max = total = 0
+    max_index = -1
+    # make one loop find all these things
+    nums.each_with_index do |n, i|
+      total += n
+      if n > max
+        max = n
+        max_index = i
+      end
+    end
+    half = total / 2.0
+    right = [nums.slice!(max_index)]
+    if max >= half
+      [bifurcate(nums), right]
+    else
+      gap = half - max
+      while rv = fit_gap(gap, nums)
+        removed, remaining_gap = rv
+        right << removed
+        break unless gap = remaining_gap
+      end
+      [bifurcate(nums), bifurcate(right)]
+    end
+  end
+
+  # look for the frequency best suited to balance the two branches
+  def fit_gap(gap, nums)
+    best_index = 0
+    best_fit = (gap - nums[0]).abs
+    nums.each_with_index.drop(1).each do |n, i|
+      fit = (gap - n).abs
+      if fit < best_fit
+        best_index = i
+        best_fit = fit
+      end
+    end
+    if nums[best_index] < gap * 2
+      n = nums.slice!(best_index)
+      [n, n < gap ? gap - n : nil]
+    end
+  end
+end

data/pick_me_too.gemspec

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+lib = File.expand_path('lib', __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'pick_me_too'
+
+Gem::Specification.new do |s|
+  s.name        = 'pick_me_too'
+  s.version     = PickMeToo::VERSION
+  s.summary     = 'Randomly select items from a list with specified frequencies'
+  s.description = <<-DESC.strip.gsub(/\s+/, ' ')
+    PickMeToo is a Ruby urn model. It allows you to generate
+    an "urn" from which you can randomly sample items with
+    specified frequencies. This facilitates modeling things that occur
+    with known frequencies, like weather or wandering monsters.
+  DESC
+  s.authors     = ['David F. Houghton']
+  s.email       = 'dfhoughton@gmail.com'
+  s.homepage    =
+    'https://github.com/dfhoughton/pick_me_too'
+  s.license = 'MIT'
+  s.required_ruby_version = '>= 2.5.3'
+  s.files                 = `git ls-files -z`.split("\x0")
+  s.test_files            = s.files.grep(%r{^(test|spec|features)/})
+  s.require_paths         = ['lib']
+
+  s.add_development_dependency 'bundler', '~> 1.7'
+  s.add_development_dependency 'byebug', '~> 9.1.0'
+  s.add_development_dependency 'json', '~> 2'
+  s.add_development_dependency 'minitest', '~> 5'
+  s.add_development_dependency 'rake', '~> 10.0'
+end

data/test/basic_test.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require 'minitest/autorun'
+
+require 'pick_me_too'
+require 'byebug'
+
+# :stopdoc:
+
+class BasicTest < Minitest::Test
+  def test_basic
+    rnd = Random.new 1
+    picker = PickMeToo.new([['cat', 2], ['dog', 1]], -> { rnd.rand })
+    counter = Hash.new(0)
+    3000.times { counter[picker.pick] += 1 }
+    assert_equal 2, (counter['cat'] / 1000.0).round, 'right number of cats'
+    assert_equal 1, (counter['dog'] / 1000.0).round, 'right number of dogs'
+  end
+
+  def test_hash
+    rnd = Random.new 1
+    picker = PickMeToo.new({'cat' => 2, 'dog' => 1}, -> { rnd.rand })
+    counter = Hash.new(0)
+    3000.times { counter[picker.pick] += 1 }
+    assert_equal 2, (counter['cat'] / 1000.0).round, 'right number of cats'
+    assert_equal 1, (counter['dog'] / 1000.0).round, 'right number of dogs'
+  end
+
+  def test_bigger
+    rnd = Random.new 1
+    frequencies = [['cat', 1], ['dog', 2], ['horse', 3], ['camel', 4], ['lizard', 5], ['fish', 6]]
+    picker = PickMeToo.new(frequencies, -> { rnd.rand })
+    counter = Hash.new(0)
+    (frequencies.map(&:last).sum * 1000).times { counter[picker.pick] += 1 }
+    frequencies.each do |key, n|
+      assert_equal n, (counter[key] / 1000.0).round, "right number of #{key}"
+    end
+  end
+
+  def test_degenerate
+    rnd = Random.new 1
+    picker = PickMeToo.new([['cat', 2]], -> { rnd.rand })
+    counter = Hash.new(0)
+    3000.times { counter[picker.pick] += 1 }
+    assert_equal 3.0, counter['cat'] / 1000.0, 'right number of cats'
+  end
+
+  def test_no_frequencies_error
+    assert_raises(PickMeToo::Error, 'no frequencies given') do
+      PickMeToo.new([])
+    end
+  end
+
+  def test_any_negative_frequency
+    assert_raises(PickMeToo::Error, "the following have non-positive frequencies: #{[['bar', -1]].inspect}") do
+      PickMeToo.new([['foo', 1], ['bar', -1]])
+    end
+  end
+
+  def test_all_tuples
+    assert_raises(PickMeToo::Error,
+                  'all frequencies must be two-member arrays the second member of which is Numeric') do
+      PickMeToo.new([['foo', nil, 1]])
+    end
+  end
+
+  def test_frequency_required
+    assert_raises(PickMeToo::Error,
+                  'all frequencies must be two-member arrays the second member of which is Numeric') do
+      PickMeToo.new([['foo', nil]])
+    end
+  end
+end

data/test/documentation_test.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require 'minitest/autorun'
+
+require 'pick_me_too'
+require 'byebug'
+
+# :stopdoc:
+
+class BasicTest < Minitest::Test
+  def test_synopsis
+    rng = Random.new 1
+    picker = PickMeToo.new([['prevention', 1], ['cure', 16]], -> { rng.rand })
+    counter = Hash.new 0
+    32.times { counter[picker.pick] += 1 }
+    assert_equal({ 'cure' => 29, 'prevention' => 3 }, counter)
+  end
+
+  def test_synopsis_hash
+    rng = Random.new 1
+    picker = PickMeToo.new({ foo: 1, bar: 2, baz: 0.5 }, -> { rng.rand })
+    counter = Hash.new 0
+    32.times { counter[picker.pick] += 1 }
+    assert_equal({ foo: 13, bar: 12, baz: 7 }, counter)
+  end
+end

metadata

@@ -0,0 +1,125 @@
+--- !ruby/object:Gem::Specification
+name: pick_me_too
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- David F. Houghton
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2022-08-14 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: byebug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 9.1.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 9.1.0
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '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: PickMeToo is a Ruby urn model. It allows you to generate an "urn" from
+  which you can randomly sample items with specified frequencies. This facilitates
+  modeling things that occur with known frequencies, like weather or wandering monsters.
+email: dfhoughton@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- CHANGES.md
+- LICENSE
+- README.md
+- Rakefile
+- lib/pick_me_too.rb
+- pick_me_too.gemspec
+- test/basic_test.rb
+- test/documentation_test.rb
+homepage: https://github.com/dfhoughton/pick_me_too
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.5.3
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.7
+signing_key:
+specification_version: 4
+summary: Randomly select items from a list with specified frequencies
+test_files:
+- test/basic_test.rb
+- test/documentation_test.rb