hash_sample 0.8.5

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 96d9552ffc743c9e19465465918840036fc94d6b04097b487d0c18b2ab3a094e
+  data.tar.gz: ec329877c7b1978caf6dd17a36fd41b0094b64863753a1f890d1b5a5bcc7f529
+SHA512:
+  metadata.gz: 2d026964365bd5fcafb9b349dad30553644cbd3d048cb6a38abeb9c833d3726366f1cce045ce45cfeeb202e3e7aa24a3c5d78940c541ab62bccccfe33302c322
+  data.tar.gz: 80c85b10012618901bf538e82341349c81608838b26beb2ac9d6237f29a53b5b7c3eda26084e1fefa91bc86b3e14964072f86e6de57d0390e768c2e08c823970

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 Sergey Evstegneiev
+
+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,86 @@
+# hash_sample
+
+Implements regular sampling and weighted random sampling with and without replacement for Hashes
+
+## Installation
+
+    gem install hash_sample
+
+## Usage
+
+```ruby
+    require 'hash_sample'
+    loaded_die = {'1' => 0.1, '2' => 0.1, '3' => 0.1, '4' => 0.1, '5' => 0.1, '6' => 0.5}
+    p loaded_die.wchoice      # "6"
+    p loaded_die.wchoice(1)   # ["6"]
+    p loaded_die.wchoice(10)  # ["4", "6", "3", "3", "2", "2", "1", "6", "4", "6"]
+    p loaded_die.wsample      # 6
+    p loaded_die.wsample(6)   # ["6", "3", "2", "4", "1", "5"]
+    p loaded_die.wsample(10)  # ["2", "6", "1", "3", "4", "5"]
+    p loaded_die.sample       # { '1' => 0.1 }
+    p loaded_die.sample(6)    # {'1' => 0.1, '2' => 0.1, '3' => 0.1, '4' => 0.1, '5' => 0.1, '6' => 0.5}
+```
+
+## Hash instance methods
+### hash.sample(n = 1) ⇒ Hash
+Choose a random key=>value pair or n random pairs from the hash.
+
+The key=>value pairs are chosen by using random and unique indices in order to ensure that each pair doesn't includes more than once
+
+If the hash is empty it returns an empty hash. 
+
+If the hash contains less than n unique keys, the copy of whole hash will be returned, none of keys will be lost due to bad luck.
+
+Returns new Hash containing sample key=>value pairs
+
+### hash.wchoice ⇒ Object
+### hash.wchoice(n) ⇒ Array of n samples.
+Weighted random sampling *with* replacement.
+
+Choose a random key or n random keys from the hash, according to weights defined in hash values.
+
+The samples are drawn by using random and replaced by its copy, so they **can be repeated in result**.
+
+If the hash is empty the first form returns nil and the second form returns an empty array.
+
+All weights should be Numeric.
+
+Zero or negative weighs will be ignored.
+
+    {'_' => 9, 'a' => 1}.wchoice(10)  # ["_", "a", "_", "_", "_", "_", "_", "_", "_", "_"]
+
+### hash.wsample ⇒ Object
+### hash.wsample(n) ⇒ Array of n samples.
+Weighted random sampling *without* replacement.
+
+Choose 1 or n *distinct* random keys from the hash, according to weights defined in hash values.
+Drawn items are not replaced.
+
+If the hash is empty the first form returns nil and the second form returns an empty array.
+
+All weights should be Numeric.
+
+Zero or negative weighs will be ignored.
+
+    {'_' => 9, 'a' => 1}.wchoice(10)  # ["_", "a"]
+
+### hash.wchoices(n = 1) ⇒ Object
+alias for wchoice
+
+### hash.wsamples(n = 1) ⇒ Object
+alias for wsample
+
+## Contributing
+
+1. Fork it ( https://github.com/serg123e/hash_sample/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request
+
+## References
+
+1. [Efraimidis and Spirakis implementation of random sampling with replacement](https://gist.github.com/O-I/3e0654509dd8057b539a)
+2. [Weighted Random Sampling (2005; Efraimidis, Spirakis)](https://utopia.duth.gr/~pefraimi/research/data/2007EncOfAlg.pdf)
+3. [Abandoned Ruby feature request](https://bugs.ruby-lang.org/issues/4247#change-25166)
+4. [Inspiring example of using max_by for Enumerables with the same algorithm](https://ruby-doc.org/core-2.7.1/Enumerable.html#method-i-max_by)

data/Rakefile

@@ -0,0 +1,156 @@
+require 'yard'
+require 'rake'
+require 'date'
+
+#############################################################################
+#
+# Helper functions
+#
+#############################################################################
+
+def name
+  "hash_sample"
+end
+
+def version
+  line = File.read("lib/#{name}/version.rb")[/^\s*VERSION\s*=\s*.*/]
+  line.match(/.*VERSION\s*=\s*['"](.*)['"]/)[1]
+end
+
+# assumes x.y.z all digit version
+def next_version
+  # x.y.z
+  v = version.split '.'
+  # bump z
+  v[-1] = v[-1].to_i + 1
+  v.join '.'
+end
+
+def bump_version
+  old_file = File.read("lib/#{name}/version.rb")
+  old_version_line = old_file[/^\s*VERSION\s*=\s*.*/]
+  new_version = next_version
+  # replace first match of old version with new version
+  old_file.sub!(old_version_line, "    VERSION = '#{new_version}'")
+
+  File.write("lib/#{name}/version.rb", old_file)
+
+  new_version
+end
+
+def replace_header(head, header_name)
+  head.sub!(/(\.#{header_name}\s*= ').*'/) { "#{$1}#{send(header_name)}'"}
+end
+
+def gemspec_file
+  "#{name}.gemspec"
+end
+
+def gem_files
+ ["#{name}-#{version}.gem"]
+end
+
+def gemspecs
+   ["#{name}.gemspec"]
+end
+
+def date
+  Date.today.to_s
+end
+#############################################################################
+#
+# Custom tasks (add your own tasks here)
+#
+#############################################################################
+
+YARD::Rake::YardocTask.new do |t|
+end
+
+desc "Generate RCov test coverage and open in your browser"
+task :coverage do
+  require 'rcov'
+  sh "rm -fr coverage"
+  sh "rcov test/test_*.rb"
+  sh "open coverage/index.html"
+end
+
+desc "Open an irb session preloaded with this library"
+task :console do
+  sh "irb -r rubygems -r ./lib/#{name}.rb"
+end
+
+desc "Update version number and gemspec"
+task :bump do
+  puts "Updated version to #{bump_version}"
+  # Execute does not invoke dependencies.
+  # Manually invoke gemspec then validate.
+  Rake::Task[:gemspec].execute
+  Rake::Task[:validate].execute
+end
+
+desc 'Build gem'
+task :build => :gemspec do
+  sh "mkdir pkg"
+  gemspecs.each do |gemspec|
+    sh "gem build #{gemspec}"
+  end
+  gem_files.each do |gem_file|
+    sh "mv #{gem_file} pkg"
+  end
+end
+
+
+desc "Build and install"
+task :install => :build do
+  sh "gem install --local --no-document pkg/#{name}-#{version}.gem"
+end
+
+desc 'Update gemspec'
+task :gemspec => :validate do
+  # read spec file and split out manifest section
+  spec = File.read(gemspec_file)
+  head, _manifest, tail = spec.split(/\s*# = MANIFEST =\n/)
+
+  # replace name version and date
+  replace_header(head, :name)
+  replace_header(head, :version)
+  replace_header(head, :date)
+  #comment this out if your rubyforge_project has a different name
+#  replace_header(head, :rubyforge_project)
+
+  # determine file list from git ls-files
+  files = `git ls-files`.
+    split("\n").
+    sort.
+    reject { |file| file =~ /^\./ }.
+    reject { |file| file =~ /^(rdoc|pkg|test|Home\.md|\.gitattributes|Guardfile)/ }.
+    map { |file| "      #{file}" }.
+    join("\n")
+
+  # piece file back together and write
+  manifest = "    s.files = %w(\n#{files}\n    )"
+  spec = [head, manifest, tail].join("\n    # = MANIFEST =\n")
+  File.open(gemspec_file, 'w') { |io| io.write(spec) }
+  puts "Updated #{gemspec_file}"
+end
+
+desc 'Validate lib files and version file'
+task :validate do
+  libfiles = Dir['lib/*'] - ["lib/#{name}.rb", "lib/#{name}"]
+  unless libfiles.empty?
+    puts "Directory `lib` should only contain a `#{name}.rb` file and `#{name}` dir."
+    exit!
+  end
+  unless Dir['VERSION*'].empty?
+    puts "A `VERSION` file at root level violates Gem best practices."
+    exit!
+  end
+end
+
+begin
+  require 'rspec/core/rake_task'
+  desc "run rspec tests"
+  RSpec::Core::RakeTask.new(:spec)
+  task :default => :spec
+rescue LoadError
+end

data/hash_sample.gemspec

@@ -0,0 +1,36 @@
+Gem::Specification.new do |s|
+    s.name        = 'hash_sample'
+    s.platform    = Gem::Platform::RUBY
+    s.authors     = ["Sergey Evstegneiev"]
+    s.email       = ["serg123e@gmail.com"]
+    s.homepage    = 'https://github.com/serg123e/hash_sample'
+    s.summary     = %q{Implements multiple sampling methods for Hash class}
+    s.description = %q{Regular and weighted random sampling with and without replacement are implemented}
+    # s.metadata    = { 'source_code_uri' => 'https://github.com/serg123e/hash-sample' }
+    s.add_development_dependency "rspec", "~> 3.5"
+    s.add_development_dependency "rake", "~> 13"
+
+    s.require_paths = ["lib"]
+
+    s.required_ruby_version = '>= 2.4'
+
+    s.date              = '2020-05-01'
+    s.version           = '0.8.5'
+    s.license           = 'MIT'
+
+    s.rdoc_options = ['--charset=UTF-8']
+    s.extra_rdoc_files = %w(README.md LICENSE)
+    # = MANIFEST =
+    s.files = %w(
+      LICENSE
+      README.md
+      Rakefile
+      hash_sample.gemspec
+      lib/hash_sample.rb
+      lib/hash_sample/version.rb
+      spec/hash_sample_spec.rb
+      spec/spec_helper.rb
+    )
+    # = MANIFEST =
+    s.test_files = s.files.select { |path| path =~ /^test\/test_.*\.rb/ }
+end

data/lib/hash_sample/version.rb

@@ -0,0 +1,4 @@
+module HashSample
+    # gem version
+    VERSION = '0.8.5'
+end

data/lib/hash_sample.rb

@@ -0,0 +1,94 @@
+# monkey-patched Hash module
+class Hash
+  ##
+  # Choose a random key=>value pair or *n* random pairs from the hash.
+  #
+  # @return [Hash] new Hash containing sample key=>value pairs
+  #
+  # The elements are chosen by using random and unique indices in order to ensure that each element doesn't includes more than once.
+  # If the hash is empty it returns an empty hash.
+  # If the hash contains less than *n* unique keys, the copy of whole hash will be returned, none of keys will be lost.
+  def sample(n = 1)
+    to_a.sample(n).to_h
+  end
+
+  ###
+  # alias for wchoice
+  def wchoices(*args)
+    wchoice(*args)
+  end
+
+  ## 
+  # Choose 1 or n random keys from the hash, according to weights defined in hash values
+  # (weighted random sampling *with* *replacement*)
+  # 
+  # @overload wchoice
+  #   @return [Object] one sample object
+  # @overload wchoice(n)
+  #   @param n [Integer] number of samples to be returned
+  #   @return [Array] Array of n samples
+  #
+  # The keys are chosen by using random according to its weights and *can* *be* *repeated* *in* *result*.
+  # If the hash is empty the first form returns nil and the second form returns an empty array.
+  # All weights should be Numeric.
+  # Zero or negative weighs will be ignored.
+  #
+  # ===== Example
+  #
+  #     p {'_' => 9, 'a' => 1}.wchoice(10)  # ["_", "a", "_", "_", "_", "_", "_", "_", "_", "_"]
+  #
+  def wchoice(*args)
+    _check_weighted_params
+    n = args.first || 1
+    res = []
+    n.times do
+      tmp = max_by { |_, weight| weight.positive? ? rand**(1.0 / weight) : 0 }
+      res << tmp.first unless tmp.nil?
+    end
+    return args.empty? ? res.first : res
+  end
+
+  # internal method to validate parameters
+  def _check_weighted_params(*_args)
+    sum_weights = 0
+    each_value do |v|
+      raise ArgumentError, "All weights should be numeric unlike #{v}" unless v.is_a? Numeric
+
+      sum_weights += v if v.positive?
+    end
+
+    raise ArgumentError, "At least one weight should be > 0" unless sum_weights.positive? || empty?
+  end
+
+  ##
+  # Choose 1 or n *distinct* random keys from the hash, according to weights defined in hash values 
+  # (weighted random sampling *without* *replacement*)
+  #
+  # @overload wsample
+  #   @return [Object] one sample object
+  # @overload wsample(n)
+  #   @param n [Integer] number of samples to be returned
+  #   @return [Array] Array of n or sometimes less than n samples
+  #
+  # When there are no sufficient distinct samples to return, the result will contain less than n samples
+  # If the hash is empty the first form returns nil and the second form returns an empty array.
+  # All weights should be Numeric.
+  # Zero or negative weighs will be ignored.
+  #
+  # ===== Example
+  #
+  #     p {'_' => 9, 'a' => 1}.wsample(10)  # ["_", "a"]
+  #
+  def wsample(*args)
+    _check_weighted_params
+    n = args.first || 1
+    res = max_by(n) { |_, weight| weight.positive? ? rand**(1.0 / weight) : 0 }.map(&:first)
+    return args.empty? ? res.first : res
+  end
+
+  ###
+  # alias for wsample
+  def wsamples(*args)
+    wsample(*args)
+  end
+end

data/spec/hash_sample_spec.rb

@@ -0,0 +1,168 @@
+# require 'lib/core_ext.rb'
+
+#
+# Specs
+#
+describe 'Hash#sample' do
+  describe 'when specified parameter n>1' do
+    it 'returns new Hash with specified number of unique key=>value samples' do
+      h = { 'a' => 'b', 'b' => 'b', 'c' => 'b' }
+      expect(h.sample(3)).to eq h
+    end
+  end
+  describe 'when specified parameter n> number of unique keys' do
+    it 'returns new Hash only with unique key=>value samples' do
+      h = { 'a' => 'b', 'b' => 'b', 'c' => 'b' }
+      expect(h.sample(10)).to eq h
+    end
+  end
+
+  describe 'when specified parameter n> number of unique keys' do
+    it 'keys can not be lost because of bad luck' do
+      h = { 'a' => 'b', 'b' => 'b', 'c' => 'b' }
+      min = h.keys.length
+      100.times do
+        min = [h.sample(4).keys.length, min].min
+      end
+      expect(min).to be 3
+    end
+  end
+
+  describe 'when specified parameter n==1' do
+    it 'returns new Hash with 1 random key=>value sample' do
+      h = { 'a' => 'b', 'b' => 'b', 'c' => 'b' }
+      expect(h.sample(1).keys.length).to eq 1
+    end
+  end
+end
+
+%w[wchoice wsample].each do |weighted_method|
+  describe 'plural form of method' do
+    weighted_methods = weighted_method + "s"
+    it 'can be used' do
+      expect({}).to respond_to(weighted_methods)
+    end
+    it 'works as expected without args' do
+      expect({ 'a' => 1 }.send(weighted_methods)).to eq 'a'
+    end
+    it 'works as expected with args' do
+      expect({ 'a' => 1 }.send(weighted_methods, 1)).to eq ['a']
+    end
+  end
+
+  describe "Hash\##{weighted_method}" do
+    it 'returns weighted sample key from all keys with respect of its weights' do
+      s = { 1 => 90, 2 => 10 }
+      freq = Hash.new(0)
+      1000.times { freq[s.send(weighted_method)] += 1 }
+      expect(freq[1]).to be_between(800, 999)
+      expect(freq[2]).to be_between(1, 200)
+    end
+
+    describe 'when weights are equal' do
+      it 'it should returns equal parts of samples' do
+        res = 1.upto(100_000).to_a.map { { +1 => 50, -1 => 50 }.send(weighted_method) }
+        expect(res.sum).to be_between(-1000, 1000) # +-1%  bias
+      end
+    end
+
+    describe 'when Hash is empty' do
+      it 'returns nil' do
+        expect({}.send(weighted_method)).to be_nil
+      end
+    end
+
+    describe 'when weights are Float' do
+      it 'returns a value as expected' do
+        expect([1, 2].include?({ 1 => 0.1, 2 => 0.9 }.send(weighted_method))).to be true
+      end
+    end
+
+    describe 'when some weights are negative' do
+      it 'does not sample that key' do
+        100.times { expect({ 'a' => -1, 'b' => 2 }.send(weighted_method)).to eq 'b' }
+      end
+    end
+
+    describe 'when weight contains zero' do
+      it 'returns non-zero weighted element' do
+        10.times do
+          expect({ 1 => 0, 2 => 1, 3 => 0 }.send(weighted_method)).to eq 2
+        end
+      end
+    end
+
+    describe 'when weight is non-numeric' do
+      it 'raises ArgumentError' do
+        expect { { 1 => 'asd', 2 => 2 }.send(weighted_method) }.to raise_error(ArgumentError)
+      end
+    end
+
+    describe 'when all weights are zero' do
+      it 'raises ArgumentError' do
+        expect { { 1 => 0, 2 => 0 }.send(weighted_method) }.to raise_error(ArgumentError)
+      end
+      # @todo do not raise error when all weights are zero
+      # xit 'returns empty array' do
+      #   h = { 'a'=>0, 'b'=>0, 'c'=>0 }
+      #   expect( h.wchoice(10) ).to eq []
+      # end
+    end
+
+    describe 'when hash is empty' do
+      it 'returns empty array or nil' do
+        expect({}.send(weighted_method, 10)).to eq []
+        expect({}.send(weighted_method)).to eq nil
+      end
+    end
+
+    describe 'when specified parameter n>1' do
+      it 'returns array of sample keys 2' do
+        100.times { expect({ 1 => 1, 2 => 0.01, 3 => 0.0000001 }.wchoice(3).length).to be 3 }
+      end
+    end
+    describe 'when specified parameter n==1' do
+      subject { { '1' => 1, '2' => 1, '3' => 1 }.wchoice(1) }
+      it 'returns array of one key' do
+        expect(subject).to be_kind_of(Array)
+        expect(subject.length).to be 1
+      end
+    end
+
+    describe 'should work with complex Objetcts as keys' do
+      subject { { %w[asd zxf] => 1, %w[asd bsd] => 1, %w[asd dsf] => 1 }.wchoice }
+      it 'returns array of one key' do
+        expect(subject).to be_kind_of(Array)
+        expect(subject.length).to be 2
+        expect(subject).to include 'asd'
+      end
+    end
+
+    describe 'when specified parameter n is greater than number of unique keys' do
+      it 'returns array with exactly n key samples, repeating some of them' do
+        h = { 'a' => 1, 'b' => 1, 'c' => 1 }
+        expect(h.wchoice(10).length).to eq 10
+      end
+    end
+  end
+end
+
+describe 'Hash#wchoice' do
+  describe 'when specified parameter n>1' do
+    it 'returns array of n sample keys' do
+      expect({ 'a' => 1 }.wchoice(2)).to eq %w[a a]
+    end
+  end
+end
+
+describe 'Hash#wsample' do
+  describe 'when specified parameter n>1' do
+    it 'returns array of unique keys' do
+      expect({ 'a' => 1 }.wsample(2)).to eq ['a']
+    end
+  end
+
+  it 'returned objects are not repeated' do
+    expect({ '_' => 9, 'a' => 1 }.wsample(10).sort).to eq %w[_ a]
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,7 @@
+require 'simplecov'
+require 'rspec/simplecov'
+
+SimpleCov.minimum_coverage 100
+SimpleCov.start
+
+require 'hash_sample'

metadata

@@ -0,0 +1,84 @@
+--- !ruby/object:Gem::Specification
+name: hash_sample
+version: !ruby/object:Gem::Version
+  version: 0.8.5
+platform: ruby
+authors:
+- Sergey Evstegneiev
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2020-05-01 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.5'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13'
+description: Regular and weighted random sampling with and without replacement are
+  implemented
+email:
+- serg123e@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.md
+- LICENSE
+files:
+- LICENSE
+- README.md
+- Rakefile
+- hash_sample.gemspec
+- lib/hash_sample.rb
+- lib/hash_sample/version.rb
+- spec/hash_sample_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/serg123e/hash_sample
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options:
+- "--charset=UTF-8"
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.7.6.2
+signing_key: 
+specification_version: 4
+summary: Implements multiple sampling methods for Hash class
+test_files: []