categorical_distribution 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 53bacc10077bb5dc4e4662c482f5f7e998574704
+  data.tar.gz: 096ebc9b023c6b842bbe60b1ef6fab7f412d0521
+SHA512:
+  metadata.gz: 296d5956f4d2dcf59d032fb6f10f809407e27aeb6557d9949a60fc76abc8f459618890a9d3d303f9ac57e167d61a0f72e97fedce6b992b10cb9a011326a12aab
+  data.tar.gz: e1de5a78bc59289acf47978b1a0010b95841cd33349f839cd4ba62e6f8f24b5e82d05ba2f9061bf04a3e9594b170968887b0b5365da1a091028287126883b6fe

data/.gitignore

@@ -0,0 +1,9 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/.travis.yml

@@ -0,0 +1,5 @@
+sudo: false
+language: ruby
+rvm:
+  - 2.2.5
+before_install: gem install bundler -v 1.13.1

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in categorical_distribution.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 Zane Geiger
+
+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,55 @@
+# CategoricalDistribution
+
+This gem provides an implementation of a [categorical distribution](https://en.wikipedia.org/wiki/Categorical_distribution) using [Vose's Alias Method](https://en.wikipedia.org/wiki/Allas_method). More details on the implementation can be found [here](http://www.keithschwarz.com/darts-dice-coins).
+The algorithm chooses a random item, with a weighted probability given on initialization, in constant time, after an O(n) initialization step.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'categorical_distribution'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install categorical_distribution
+
+## Usage
+
+    r = CategoricalDistribution.new({ a: 1, b: 2, c: 3 })
+    r.rand    #=> :a
+    r.rand    #=> :b
+    r.rand    #=> :c
+    r.rand    #=> :c
+    r.rand    #=> :b
+
+    r = CategoricalDistribution.new([1, 1, 1])
+    r.take(5) #=> [1, 2, 1, 1, 2]
+
+    r = CategoricalDistribution.new([1, 3], ['heads', 'tails'])
+    r.rand    #=> "tails"
+    r.rand    #=> "tails"
+    r.rand    #=> "tails"
+    r.rand    #=> "tails"
+    r.rand    #=> "heads"
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/zanecodes/categorical_distribution.
+
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+

data/Rakefile

@@ -0,0 +1,10 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList['test/**/*_test.rb']
+end
+
+task :default => :test

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "categorical_distribution"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/categorical_distribution.gemspec

@@ -0,0 +1,26 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'categorical_distribution/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "categorical_distribution"
+  spec.version       = CategoricalDistribution::VERSION
+  spec.authors       = ["Zane Geiger"]
+  spec.email         = ["zanecodes@gmail.com"]
+
+  spec.summary       = "Generates values from a categorical probability distribution in O(1) using Vose's Alias Method."
+  spec.homepage      = "https://github.com/zanecodes/categorical_distribution"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.13"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "minitest", "~> 5.0"
+end

data/lib/categorical_distribution/version.rb

@@ -0,0 +1,3 @@
+module CategoricalDistribution
+  VERSION = "0.1.0"
+end

data/lib/categorical_distribution.rb

@@ -0,0 +1,211 @@
+require 'forwardable'
+
+# Generate values from a categorical probability distribution in constant time.
+# Uses Vose's Alias Method to construct a table of probabilities and aliases.
+# To generate a value, we pick an entry in the distribution at random, and then pick
+# either the value or the alias, using a biased coin flip.
+#
+# Table construction is O(n), index generation is O(1).
+# 
+# See http://www.keithschwarz.com/darts-dice-coins for a detailed explanation.
+
+class CategoricalDistribution
+  extend Forwardable
+  include Enumerable
+
+
+  # :call-seq:
+  #   CategoricalDistribution.new(p={})
+  #   CategoricalDistribution.new(p=[])
+  #   CategoricalDistribution.new(p=[], values=[])
+  #
+  # Constructs a categorical random distribution from a set of probabilities
+  # and, optionally, values. 
+  #
+  # These can be passed as an array of probabilities and an array of values,
+  # or as a hash of values to probabilities.
+  #
+  # If necessary, probabilities will be normalized so that they sum to one.
+  # If no values are provided, they will default to the respective indices of
+  # each probability.
+  #
+  # Raises an +ArgumentError+ if any probability is negative.
+  #
+  #   CategoricalDistribution.new                                    
+  #     #=> {}
+  #
+  #   CategoricalDistribution.new([Rational(1, 5), Rational(4, 5)])
+  #     #=> {0 => (1/5), 1 => (4/5)}
+  #
+  #   CategoricalDistribution.new([1, 1, 1])
+  #     #=> {0 => (1/3), 1 => (1/3), 2 => (1/3)}
+  #
+  #   CategoricalDistribution.new([1, 1, 1], [:a, :b, :c])
+  #     #=> {:a => (1/3), :b => (1/3), :c => (1/3)}
+  #
+  #   CategoricalDistribution.new({a: 1, b: 2, c: 3})
+  #     #=> {:a => (1/6), :b => (1/3), :c => (1/2)}
+
+  def initialize(p={}, values=nil)
+    if p.respond_to?(:keys) && p.respond_to?(:values)
+      values, p = p.keys, p.values 
+    else
+      values ||= p.each_index.to_a
+    end
+
+    raise ArgumentError, 'probabilities must be positive' if p.any? { |value| value < 0 }
+
+    sum = p.reduce(:+)
+    p.map! { |value| Rational(value, sum) } unless sum == 1
+
+    @p = Hash[[values, p].transpose].freeze
+
+    n = p.size
+    @prob = Array.new(n, Rational(1))
+    @alias = Array.new(n)
+
+    p.map! { |value| value * n }
+
+    small, large = p.each_index.partition { |i| p[i] < 1 }
+
+    until small.empty?
+      l = small.pop
+      g = large.pop
+
+      @prob[l] = p[l]
+      @alias[l] = g
+
+      p[g] -= 1 - p[l]
+      (p[g] < 1 ? small : large) << g
+    end
+  end
+
+
+  # :call-seq:
+  #   distribution.rand              -> obj or nil
+  #   distribution.rand(random: rng) -> obj or nil
+  #
+  # Return a value from the probability distribution, or +nil+ if it is empty.
+  #
+  # The optional rng argument will be used as the random number generator.
+  #
+  #   distribution = CategoricalDistribution.new({a: 1, b: 2, c: 3})
+  #   distribution.rand      #=> :b
+  #   distribution.rand      #=> :c
+  #   distribution.rand      #=> :c
+
+  def rand(random: Random)
+    return if @prob.empty?
+
+    i = random.rand(@prob.size)
+    random.rand <= @prob[i] ? @p.keys[i] : @p.keys[@alias[i]]
+  end
+
+
+  # :call-seq:
+  #   distribution.each { |item| block }  -> nil
+  #   distribution.each                   -> Enumerator
+  #
+  # Calls the given block infinitely many times, passing a value from the
+  # distribution as a parameter.
+  #
+  # An Enumerator is returned if no block is given.
+  #
+  #   distribution = CategoricalDistribution.new([1, 2, 3])
+  #   distribution.each { |x| print x, " -- " }
+  #
+  # produces:
+  #
+  #  1 -- 2 -- 2 -- 0 -- 1 -- ... 
+  
+  def each(random: Random)
+    return enum_for(:each) unless block_given?
+
+    loop { yield rand } unless empty?
+  end
+
+
+  # Returns the distribution's values and their probabilities, as a hash of
+  # objects to Rationals which sum to one, or an empty hash if the distribution is empty.
+  #
+  #   CategoricalDistribution.new([1, 1, 1]).probabilities   
+  #     #=> {0 => (1/3), 1 => (1/3), 2 => (1/3)}
+  #
+  #   CategoricalDistribution.new.probabilities
+  #     #=> {}
+
+  def probabilities
+    @p
+  end
+
+
+  # :call_seq:
+  #   distribution == other_distribution    ->    bool
+  #
+  # Equality --- Two probability distributions are equal if they contain the
+  # same values and if each value has the same probability as the corresponding
+  # value in other_distribution.
+  #
+  #   CategoricalDistribution.new([1, 2])            == CategoricalDistribution.new([1, 2, 3])
+  #     #=> false
+  #
+  #   CategoricalDistribution.new([1, 2, 3])         == CategoricalDistribution.new([1, 2, 3])
+  #     #=> true
+  #
+  #   CategoricalDistribution.new([1, 2, 3])         == CategoricalDistribution.new([1, 1, 1])
+  #     #=> false
+  #
+  #   CategoricalDistribution.new([1, 2], [:a, :b])  == CategoricalDistribution.new([1, 2], [:a, :c])
+  #     #=> false
+
+  def ==(other)
+    self.probabilities == other.probabilities
+  end
+
+
+  # :call_seq:
+  #   distribution.eql?(other)  -> true or false
+  #
+  # Returns true if self and other are the same object, or are both probability
+  # distributions with the same values and probabilities.
+
+  def eql?(other)
+    self.equal?(other) || 
+      (self.class == other.class && self.probabilities == other.probabilities)
+  end
+
+
+  def_delegators :@p, :empty?, :hash, :length, :size, :to_s
+
+  ##
+  # :method: empty?
+  # :call_seq:
+  #   distribution.empty?    -> true or false
+  #
+  # Returns true if self contains no values.
+  #
+  #   distribution = CategoricalDistribution.new
+  #   distribution.empty?   #=> true
+
+  ##
+  # :method: hash
+  # :call_seq:
+  #   distribution.hash    -> fixnum
+  #
+  # Compute a hash-code for this probability distribution.
+  #
+  # Two distributions with the same values and probabilities will have the same
+  # hash code (and will compare using #eql?).
+  #
+  # See also Hash#hash.
+
+  ##
+  # :method: length
+  # :call_seq:
+  #   distribution.length  -> int
+  #
+  # Returns the number of values in self. May be zero.
+  #
+  #   CategoricalDistribution.new([1, 2, 3, 4]).length    #=> 4
+  #   CategoricalDistribution.new.length                  #=> 0
+end

metadata

@@ -0,0 +1,98 @@
+--- !ruby/object:Gem::Specification
+name: categorical_distribution
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Zane Geiger
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2016-10-15 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.13'
+- !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'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+description: 
+email:
+- zanecodes@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".travis.yml"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- categorical_distribution.gemspec
+- lib/categorical_distribution.rb
+- lib/categorical_distribution/version.rb
+homepage: https://github.com/zanecodes/categorical_distribution
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.5.1
+signing_key: 
+specification_version: 4
+summary: Generates values from a categorical probability distribution in O(1) using
+  Vose's Alias Method.
+test_files: []