weighted_randomizer 0.1.0

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.yardopts

@@ -0,0 +1,6 @@
+-m markdown
+--readme README.md
+-
+Changes.md
+LICENSE
+

data/Changes.md

@@ -0,0 +1,3 @@
+0.1.0
+-----------
+- Initial release

data/Gemfile

@@ -0,0 +1,2 @@
+source 'https://rubygems.org'
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Ryan LeCompte
+
+MIT License
+
+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,59 @@
+# Weighted Randomizer
+
+Weighted Randomizer is an implementation of weighted randomization in Ruby.
+This gem is useful for situations where you have a group of items with
+corresponding weights, and you want to randomly select an item with its associated
+weight taken into account. Potential uses of this gem could be weighted job
+queues or other types of data where weights are potentially important.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'weighted_randomizer'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install weighted_randomizer
+
+## Usage
+
+Using this gem is as simple as the following:
+
+```ruby
+  queues = {'queue1' => 25, 'queue2' => 100, 'queue3' => 2}
+  randomizer = WeightedRandomizer.new(queues)
+
+  # Fetch a single random item.
+  randomizer.sample # => single item
+
+  # Fetch the next 10 weighted random items.
+  randomizer.sample(10) # => array of items
+```
+
+## License
+
+Please see LICENSE for licensing details.
+
+## Author
+
+Ryan LeCompte
+
+[@ryanlecompte](https://twitter.com/ryanlecompte)
+
+## Acknowledgements
+
+The core of this gem was graciously based on recipe 5.11 from the
+[Ruby Cookbook](http://shop.oreilly.com/product/9780596523695.do)
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,2 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"

data/lib/weighted_randomizer.rb

@@ -0,0 +1,58 @@
+# Implements weighted randomization for a group of weighted items.
+# This class expects a hash of key -> value pairs where the value is
+# the weight for the item.
+#
+# @example Usage
+#  wr = WeightedRandomizer.new('queue1' => 25, 'queue2' => 100, 'queue3' => 2)
+#  puts "Using queue #{wr.sample}"
+#
+# @note Mostly adapted from recipe 5.11 from the Ruby Cookbook.
+class WeightedRandomizer
+  VERSION = '0.1.0'
+
+  # Creates a new instance.
+  #
+  # @param [Hash] items the weighted items (key item, value weight)
+  # @return [WeightedRandomizer]
+  def initialize(items)
+    @items = normalize(items)
+  end
+
+  # Returns one or more weighted random values.
+  #
+  # @param [Integer] num the number of samples to return
+  # @return [Object, Array<Object>] one or more sampled items
+  def sample(num = nil)
+    return _sample unless num
+    Array.new(num) { _sample }
+  end
+
+  private
+
+  # Returns a single weighted random value.
+  #
+  # @return [Object] the weighted item
+  def _sample
+    pick = rand
+    @items.each do |key, weight|
+      return key if pick <= weight
+      pick -= weight
+    end
+    nil
+  end
+
+  # Normalizes the weights to float values so that
+  # arbitrary integer/float weights can be specified.
+  #
+  # @param [Hash] items the weighted items (key item, value weight)
+  # @return [Hash] the items with their weights normalized
+  def normalize(items)
+    normalized = {}
+    sum = items.values.inject(0.0, :+)
+    items.each do |key, weight|
+      normalized[key] = weight / sum
+    end
+
+    normalized
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,5 @@
+require 'rspec'
+require 'weighted_randomizer'
+
+RSpec.configure do |config|
+end

data/spec/weighted_randomizer_spec.rb

@@ -0,0 +1,31 @@
+require 'spec_helper'
+
+describe WeightedRandomizer do
+  let(:items) { {:a => 2, :b => 5, :c => 53} }
+  let(:randomizer) { WeightedRandomizer.new(items) }
+
+  describe '#initialize' do
+    it 'creates a new instance with normalized weighted items' do
+      internal_items = randomizer.instance_variable_get(:@items)
+      internal_items.keys.should =~ items.keys
+      internal_items.values.inject(:+).should == 1.0
+    end
+  end
+
+  describe '#sample' do
+    it 'returns a single item by default' do
+      randomizer.sample.should be_a(Symbol)
+    end
+
+    it 'returns an array of items with count specified' do
+      randomizer.sample(5).should be_an(Array)
+    end
+
+    it 'respects weights' do
+      result = randomizer.sample(1000).each_with_object(Hash.new(0)) { |i, h|
+        h[i] += 1
+      }
+      result.max_by { |k, v| v }.first.should == :c
+    end
+  end
+end

data/weighted_randomizer.gemspec

@@ -0,0 +1,22 @@
+# -*- encoding: utf-8 -*-
+
+require File.expand_path('../lib/weighted_randomizer', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["Ryan LeCompte"]
+  gem.email         = ["lecompte@gmail.com"]
+  gem.description   = %q{Provides a common utility for weighted randomization}
+  gem.summary       = %q{Provides a common utility for weighted randomization}
+  gem.homepage      = "http://github.com/ryanlecompte/weighted_randomizer"
+
+  gem.files         = `git ls-files`.split($\)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.name          = "weighted_randomizer"
+  gem.require_paths = ["lib"]
+  gem.version       = WeightedRandomizer::VERSION
+
+  gem.add_development_dependency('rake')
+  gem.add_development_dependency('rspec')
+  gem.add_development_dependency('yard')
+end

metadata

@@ -0,0 +1,113 @@
+--- !ruby/object:Gem::Specification
+name: weighted_randomizer
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+  prerelease: 
+platform: ruby
+authors:
+- Ryan LeCompte
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-05-29 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Provides a common utility for weighted randomization
+email:
+- lecompte@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .yardopts
+- Changes.md
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- lib/weighted_randomizer.rb
+- spec/spec_helper.rb
+- spec/weighted_randomizer_spec.rb
+- weighted_randomizer.gemspec
+homepage: http://github.com/ryanlecompte/weighted_randomizer
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: -345244177172627536
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: -345244177172627536
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.23
+signing_key: 
+specification_version: 3
+summary: Provides a common utility for weighted randomization
+test_files:
+- spec/spec_helper.rb
+- spec/weighted_randomizer_spec.rb
+has_rdoc: