erv 0.3.5 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a373b6d772167ba3c442980aa0ebef57fe3f06c686eb52022d7b7f52b46f3da2
-  data.tar.gz: 48cbe39fa60eeb16323437717816563b4f95c16827251c3b7fa76a3f59931d34
+  metadata.gz: 8d221c7c71ecf7cf3f2b329491efdea64b682744d106dfa43aa725be90c26b64
+  data.tar.gz: c8dcefee02e7a9c0bafb19ca1186e37acb138d90be8098076224f7ebd6c5dee8
 SHA512:
-  metadata.gz: fd33198c89901219af7bdfef38383cc2d3d4f9ce47f43ce27a2b33231d6ae4f9901c78ffd1cd67a6a2a25e863f6dd9d9f2b8efcc6221a663c11efd7cac34e641
-  data.tar.gz: 2a4618d56f415822b4a67f3b21e87fa19bb28281d88836f0f63a5e14adc3caca4f6b4c64fff62a4b6897ff49e97303e4f5888c95f318981b7bf25da6733f426e
+  metadata.gz: cd8301d624202ef0d4230d581dcfd4c0e046974c27af67e25d4e68a4db3f152e1f7f5aaa4af677e6ba58f2afb93f6e744b6505587b5a28280f6c8aecf2b8db24
+  data.tar.gz: 7aca0079037734d9ab7efb88ac31fe3e2981067e73646326317dde1fcec90aef2c291f93ba3c0cf7d5f8a1d197e3b01c03a4fbb21916d8b86953e0eb76ab86a1

data/LICENSE

@@ -1,6 +1,7 @@
 The MIT License (MIT)
 
-Copyright (c) 2014-2017 Mauro Tortonesi
+Copyright (c) 2014-2025 Mauro Tortonesi
+Copyright (c) 2023-2025 Filippo Poltronieri
 
 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

data/README.md

@@ -1,5 +1,7 @@
 # ruby-erv
 
+[![Gem Version](https://badge.fury.io/rb/erv.svg)](https://badge.fury.io/rb/erv)
+
 Easy/elegant random variable library
 
 
@@ -7,8 +9,10 @@ Easy/elegant random variable library
 
 ruby-erv is a library that enables to create objects representing random
 variables with a given probability distribution (gaussian, uniform, etc.) and
-to sample from them. ruby-erv was built from code that I extracted out of
-several scientific software I wrote for my research projects.
+to sample from them. It originated as a bunch of RNG-related code extracted out
+of several scientific software tools that we wrote for our research projects at
+the University of Ferrara, Italy, that we later reshaped in a more coherent and
+systematic fashion.
 
 
 ## Installation

data/config/sus.rb

@@ -0,0 +1,2 @@
+# Load main file of the framework
+require 'erv'

data/erv.gemspec

@@ -12,15 +12,12 @@ Gem::Specification.new do |spec|
   spec.summary       = %q{Easy/elegant Ruby library providing support for random variable generation}
   spec.homepage      = 'https://github.com/mtortonesi/ruby-erv'
   spec.license       = 'MIT'
+  spec.required_ruby_version = '>= 2.3.0'
 
   spec.files         = `git ls-files`.split($/).reject{|x| x == '.gitignore' or x == '.projections.json' }
   spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
   spec.require_paths = ['lib']
 
-  spec.add_development_dependency 'bundler', '~> 1.14'
-  spec.add_development_dependency 'rake', '~> 12.0'
-  spec.add_development_dependency 'minitest', '~> 5.10'
-  spec.add_development_dependency 'minitest-reporters', '~> 1.1'
-  spec.add_development_dependency 'minitest-spec-context', '~> 0.0.3'
+  spec.add_development_dependency 'sus', '~> 0.35.0'
 end

data/fixtures/erv/distribution_behaviour.rb

@@ -0,0 +1,23 @@
+module ERV
+  module DistributionBehavior
+    def self.included(base)
+      base.it 'should allow sampling' do
+        expect{ distribution.sample }.not.to raise_exception(ArgumentError).and(! be_nil)
+      end
+
+      base.it 'should have the expected mean and variance' do
+        # sample_mean = samples.inject(0.0) { |s, x| s + x } / num_samples.to_f
+        sample_mean = samples.sum / num_samples.to_f
+        distribution_mean = distribution.mean
+        expect(sample_mean).to be_within(epsilon * distribution_mean).of(distribution_mean)
+
+        sample_variance = samples.map{ |x| (x - sample_mean) **2 }.sum / (num_samples - 1).to_f
+        distribution_variance = distribution.variance
+        expect(sample_variance).to be_within(epsilon * distribution_variance).of(distribution_variance)
+      end
+    end
+  end
+  # def samples { num_samples.times.map { distribution.sample } }
+  # def epsilon { 5E-3 }
+  # def num_samples { 1_000_000 }
+end

data/lib/erv/beta_distribution.rb

@@ -0,0 +1,36 @@
+require 'erv/distribution'
+
+module ERV
+  class BetaDistribution < Distribution
+    def initialize(opts = {})
+      raise ArgumentError, 'alpha is required' unless opts[:alpha]
+      raise ArgumentError, 'beta is required' unless opts[:beta]
+      raise ArgumentError, 'alpha must be greater than zero' unless opts[:alpha].to_f > 0.0
+      raise ArgumentError, 'beta must be greater than zero' unless opts[:beta].to_f > 0.0
+
+      # Parameters alpha and beta must be greater than zero
+      @alpha = opts[:alpha]
+      @beta = opts[:beta]
+
+      @gamma_alpha = GammaDistribution.new(shape: @alpha, scale: 1.0)
+      @gamma_beta  = GammaDistribution.new(shape: @beta, scale: 1.0)
+    end
+
+    # The handbook describes many method to sample from a Beta distribution.
+    # We could use Gamma RVs or event sampling u ~ N(0,1) and then X = U ** (1 / alpha)
+    def sample
+      # let's use gamma random variables
+      x = @gamma_alpha.sample
+      y = @gamma_beta.sample
+      x / (x + y)
+    end
+
+    def mean
+      @alpha.to_f / (@alpha + @beta)
+    end
+
+    def variance
+      (@alpha.to_f * @beta) / (((@alpha + @beta)**2) * (@alpha + @beta + 1))
+    end
+  end
+end

data/lib/erv/discrete_uniform_distribution.rb

@@ -1,5 +1,4 @@
 require 'erv/distribution'
-require 'erv/support/try'
 
 
 module ERV
@@ -10,18 +9,17 @@ module ERV
     def initialize(opts={})
       super(opts)
 
-      raise ArgumentError unless opts[:max_value]
-      @max = opts[:max_value].to_i
-      @min = opts[:min_value].try(:to_i) || 0
+      @max = opts[:max_value]&.to_i
+      raise ArgumentError unless @max
+      @min = opts.fetch(:min_value, 0).to_i
       @mean = (@max + @min) / 2.0
       # See https://en.wikipedia.org/wiki/Discrete_uniform_distribution
-      @variance = ((@max - @min + 1) ** 2 - 1) / 12.0
+      @variance = ((@max - @min + 1).to_f ** 2 - 1.0) / 12.0
     end
 
     def sample
-      @min + @rng.rand(@max - @min)
+      (@min.to_f + @rng.rand * (@max - @min + 1).to_f).floor
     end
-
   end
 
 end

data/lib/erv/distribution.rb

@@ -1,6 +1,8 @@
 module ERV
 
   class Distribution
+
+    DEFAULT_SEED = 12345
     def initialize(opts={})
       # use provided RNG or create a new one
       if opts[:rng]
@@ -8,7 +10,7 @@ module ERV
       elsif opts[:seed]
         @rng = Random.new(opts[:seed])
       else
-        @rng = Random.new
+        @rng = Random.new(DEFAULT_SEED)
       end
     end
   end

data/lib/erv/expnorm_distribution.rb

@@ -0,0 +1,40 @@
+require 'erv/distribution'
+
+module ERV
+  class ExpNormDistribution < Distribution
+    def initialize(opts = {})
+      super(opts)
+
+      raise ArgumentError, 'mu is required'     unless opts[:mu]
+      raise ArgumentError, 'sigma is required'  unless opts[:sigma]
+      raise ArgumentError, 'lambda is required' unless opts[:lambda]
+      raise ArgumentError, 'sigma must be > 0'  if opts[:sigma].to_f <= 0
+      raise ArgumentError, 'lambda must be > 0' if opts[:lambda].to_f <= 0
+
+      @mu     = opts[:mu].to_f
+      @sigma  = opts[:sigma].to_f
+      @lambda = opts[:lambda].to_f # rate = 1/mean_exponential
+
+      @gaussian = GaussianDistribution.new(mean: @mu, sd: @sigma)
+      @exponential = ExponentialDistribution.new(rate: @lambda)
+    end
+
+    def sample
+      @gaussian.sample + @exponential.sample
+    end
+
+    # Theoretical Mean E[X]: μ + 1/λ
+    def mean
+      @mu + 1.0 / @lambda
+    end
+
+    # Theoretical Variance: σ² + 1/λ²
+    def variance
+      @sigma**2 + 1.0 / (@lambda**2)
+    end
+
+    def k
+      @lambda / @sigma
+    end
+  end
+end

data/lib/erv/exponential_distribution.rb

@@ -1,5 +1,4 @@
 require 'erv/distribution'
-require 'erv/support/try'
 
 
 module ERV
@@ -10,7 +9,7 @@ module ERV
     def initialize(opts={})
       super(opts)
 
-      @rate = opts[:rate].try(:to_f)
+      @rate = opts[:rate]&.to_f
       raise ArgumentError unless @rate and @rate > 0.0
 
       @mean = 1 / @rate

data/lib/erv/generalized_pareto_distribution.rb

@@ -1,9 +1,7 @@
 require 'erv/distribution'
-require 'erv/support/try'
 
 
 module ERV
-
   # See https://en.wikipedia.org/wiki/Generalized_Pareto_distribution
   class GpdDistribution < Distribution
     attr_accessor :mean, :variance
@@ -14,30 +12,28 @@ module ERV
       raise ArgumentError unless opts[:scale] and opts[:shape]
       @scale    = opts[:scale].to_f
       @shape    = opts[:shape].to_f
-      @location = opts[:location].try(:to_f) || 0.0
+      @location = opts.fetch(:location, 0.0).to_f
 
       @mean = if @shape < 1.0
         @location + @scale / (1.0 - @shape)
       else
-        Infinity
+        Float::Infinity
       end
 
       @variance = if @shape < 0.5
         (@scale ** 2.0) / (((1.0 - @shape) ** 2) * (1.0 - 2 * @shape))
       else
-        Infinity
+        Float::Infinity
       end
     end
 
     def sample
       u = 1.0 - @rng.rand
-      if @shape == 0.0
+      if @shape.abs < 1E-15 # numerically stable check if @shape == 0.0
         @location - @scale * Math::log(u)
       else
         @location + (@scale * ((u ** (- @shape)) - 1.0) / @shape)
       end
     end
-
   end
-
 end

data/lib/erv/lognorm_distribution.rb

@@ -0,0 +1,32 @@
+require 'erv/distribution'
+
+module ERV
+  class LogNormDistribution < Distribution
+    def initialize(opts = {})
+      super(opts)
+
+      raise ArgumentError, 'mu is required' unless opts[:mu]
+      raise ArgumentError, 'sigma is required' unless opts[:sigma]
+      raise ArgumentError, 'sigma must be greater than zero' unless opts[:sigma].to_f > 0.0
+
+      @mu = opts[:mu].to_f
+      @sigma = opts[:sigma].to_f
+
+      # From Handbook of Monte Carlo Methods [KROESE11], section 4.2.10, pag 121
+      @gaussian_dist = GaussianDistribution.new(mean: @mu, sd: @sigma)
+    end
+
+    def sample
+      # just sample from @gaussian_dist and exponentiate the result
+      Math.exp(@gaussian_dist.sample) # just sample from @gaussian_dist and exponentiate the res    Math.exp(@gaussian_dist.sample)))
+    end
+
+    def mean
+      Math.exp(@mu + 0.5 * @sigma**2)
+    end
+
+    def variance
+      Math.exp(2 * @mu + @sigma**2) * (Math.exp(@sigma**2) - 1)
+    end
+  end
+end

data/lib/erv/mixture_distribution.rb

@@ -10,6 +10,9 @@ require 'erv/uniform_distribution'
 module ERV
 
   class MixtureDistribution
+
+    DEFAULT_SEED = 12345
+    
     def initialize(confs, opts={})
       raise ArgumentError, "Please, provide at least 2 distributions!" if confs.count < 2
 
@@ -42,6 +45,7 @@ module ERV
       end
 
       seed = opts[:seed]
+      seed = DEFAULT_SEED if seed.nil?
       @mixture_sampler = (seed ? Random.new(seed) : Random.new)
     end
 

data/lib/erv/random_variable.rb

@@ -1,3 +1,4 @@
+require 'forwardable'
 require 'erv/constant_distribution'
 require 'erv/discrete_uniform_distribution'
 require 'erv/exponential_distribution'
@@ -7,20 +8,21 @@ require 'erv/generalized_pareto_distribution'
 require 'erv/geometric_distribution'
 require 'erv/mixture_distribution'
 require 'erv/uniform_distribution'
-require 'erv/support/try'
+require 'erv/weibull_distribution'
+require 'erv/lognorm_distribution'
+require 'erv/beta_distribution'
+require 'erv/expnorm_distribution'
 
 
 module ERV
-
   class RandomVariable
-
     extend Forwardable
 
     def_delegators :@dist, :mean, :variance
 
-    def initialize(args={})
+    def initialize(args = {})
       # get distribution name
-      dist_name = args[:distribution].try(:to_s)
+      dist_name = args[:distribution]&.to_s
 
       # get class name that corresponds to the requested distribution
       klass_name = dist_name.split('_').push('distribution').map(&:capitalize).join
@@ -33,17 +35,15 @@ module ERV
       @dist.sample
     end
 
-    alias_method :sample, :next
-
+    alias sample next
   end
 
-
   class SequentialRandomVariable
-
-    def initialize(opts={})
+    def initialize(opts = {})
       args = opts.dup
       first = args.delete(:first_value)
-      raise ArgumentError, "First value must be provided!" if first.nil?
+      raise ArgumentError, 'First value must be provided!' if first.nil?
+
       @most_recent = first.to_f
       @var = RandomVariable.new(args)
     end
@@ -52,8 +52,6 @@ module ERV
       @most_recent += @var.next
     end
 
-    alias_method :sample, :next
-
+    alias sample next
   end
-
 end

data/lib/erv/uniform_distribution.rb

@@ -1,5 +1,4 @@
 require 'erv/distribution'
-require 'erv/support/try'
 
 
 module ERV
@@ -8,9 +7,9 @@ module ERV
     def initialize(opts={})
       super(opts)
 
-      raise ArgumentError unless opts[:max_value]
-      max = opts[:max_value].to_f
-      @min = opts[:min_value].try(:to_f) || 0.0
+      max = opts[:max_value]&.to_f
+      raise ArgumentError unless max
+      @min = opts.fetch(:min_value, 0.0).to_f
       @range = max - @min
     end
 

data/lib/erv/version.rb

@@ -1,3 +1,3 @@
 module ERV
-  VERSION = '0.3.5'
+  VERSION = '0.4.0'
 end

data/lib/erv/weibull_distribution.rb

@@ -0,0 +1,23 @@
+require 'erv/distribution'
+
+module ERV
+  class WeibullDistribution < Distribution
+    def initialize(opts = {})
+      super(opts)
+
+      raise ArgumentError unless opts[:scale] and opts[:shape]
+
+      @scale = opts[:scale].to_f
+      @shape = opts[:shape].to_f
+
+      raise ArgumentError, 'scale parameter must be greater than zero!' unless @scale > 0.0
+      raise ArgumentError, 'shape parameter must be greater than zero!' unless @shape > 0.0
+    end
+
+    # For more details, see [KROESE11], section 4.2.18, algorithm 4.66 and
+    def sample
+      u = @rng.rand
+      @scale * (-Math.log(1 - u))**(1.0 / @shape)
+    end
+  end
+end

data/test/erv/beta_distribution_test.rb

@@ -0,0 +1,22 @@
+require 'erv/distribution_behaviour'
+
+describe ERV::BetaDistribution do
+  with 'initialization' do
+    it 'should require the alpha and beta parameters' do
+      expect{ ERV::BetaDistribution.new(alpha: 0.0) }.to raise_exception(ArgumentError)
+      expect{ ERV::BetaDistribution.new(beta: 0.0) }.to raise_exception(ArgumentError)
+      expect{ ERV::BetaDistribution.new(alpha: -1.0, beta: 0.0) }.to raise_exception(ArgumentError)
+      expect{ ERV::BetaDistribution.new(alpha: 0.0, beta: -1.0) }.to raise_exception(ArgumentError)
+    end
+  end
+
+  with 'sampling' do
+    let(:distribution) { ERV::BetaDistribution.new(alpha: 2.0, beta: 5.0) }
+
+    let(:num_samples) { 200_000 }
+    let(:samples) { num_samples.times.map { distribution.sample } }
+    let(:epsilon) { 1E-2 }
+
+    include ERV::DistributionBehavior
+  end
+end

data/test/erv/constant_distribution_test.rb

@@ -1,27 +1,17 @@
-require 'test_helper'
-
-require 'erv/constant_distribution'
-
 describe ERV::ConstantDistribution do
-
   it 'should require a reference value' do
-    lambda do
-      ERV::ConstantDistribution.new
-    end.must_raise ArgumentError
+    expect { ERV::ConstantDistribution.new }.to raise_exception(ArgumentError)
   end
 
-  context 'reference value' do
-
+  with 'reference value' do
     it 'should be accepted at initialization time' do
-      ERV::ConstantDistribution.new(value: 10)
+      expect { ERV::ConstantDistribution.new(value: 10) }.not.to raise_exception(ArgumentError)
     end
 
     it 'should match the value returned by sampling' do
       val = rand(100)
       crv = ERV::ConstantDistribution.new(value: val)
-      crv.sample.must_equal val
+      expect(crv.sample).to be == val
     end
-
   end
-
 end

data/test/erv/discrete_uniform_distribution_test.rb

@@ -1,81 +1,29 @@
-require 'test_helper'
-
-require 'erv/discrete_uniform_distribution'
+require 'erv/distribution_behaviour'
 
 describe ERV::DiscreteUniformDistribution do
-
-  let (:num_samples) { 10000 }
-
   it 'should require at least a maximum parameter' do
-    lambda do
-      ERV::DiscreteUniformDistribution.new()
-    end.must_raise ArgumentError
+    expect{ ERV::DiscreteUniformDistribution.new }.to raise_exception(ArgumentError)
   end
 
 
-  context 'a (default) 1-parameter distribution' do
-
-    let :zero_to_sixty do
-      ERV::DiscreteUniformDistribution.new(max_value: 60)
-    end
-
-    context 'sampling' do
-
-      it 'should allow sampling' do
-        zero_to_sixty.sample
-      end
-
-    end
-
-    context 'moments' do
-      let :samples do
-        0.upto(num_samples).collect { zero_to_sixty.sample }
-      end
+  with 'a (default) 1-parameter distribution' do
+    let(:distribution) { ERV::DiscreteUniformDistribution.new(max_value: 60) }
 
-      it 'should have the expected mean' do
-        sample_mean = samples.inject(0.0) {|s,x| s += x } / num_samples.to_f
-        sample_mean.must_be_within_epsilon zero_to_sixty.mean, 0.05
-      end
+    let(:num_samples) { 300_000 }
+    let(:samples) { num_samples.times.map { distribution.sample } }
+    let(:epsilon) { 1E-2 }
 
-      it 'should have the expected variance' do
-        sample_variance = samples.inject(0.0) {|s,x| s += (x - zero_to_sixty.mean) ** 2 } / num_samples.to_f
-        sample_variance.must_be_within_epsilon zero_to_sixty.variance, 0.05
-      end
-
-    end
+    include ERV::DistributionBehavior
   end
 
-  context 'a 2-parameter distribution' do
-
-    let :ten_to_ninety do
-      ERV::DiscreteUniformDistribution.new(min_value: 10, max_value: 90)
-    end
-
-    context 'sampling' do
-
-      it 'should allow sampling' do
-        ten_to_ninety.sample
-      end
 
-    end
+  with 'a 2-parameter distribution' do
+    let(:distribution) { ERV::DiscreteUniformDistribution.new(min_value: 10, max_value: 90) }
 
-    context 'moments' do
+    let(:num_samples) { 200_000 }
+    let(:samples) { num_samples.times.map { distribution.sample } }
+    let(:epsilon) { 1E-2 }
 
-      let :samples do
-        0.upto(num_samples).collect { ten_to_ninety.sample }
-      end
-
-      it 'should have the expected mean' do
-        sample_mean = samples.inject(0.0) {|s,x| s += x } / num_samples.to_f
-        sample_mean.must_be_within_epsilon ten_to_ninety.mean, 0.05
-      end
-
-      it 'should have the expected variance' do
-        sample_variance = samples.inject(0.0) {|s,x| s += (x - ten_to_ninety.mean) ** 2 } / num_samples.to_f
-        sample_variance.must_be_within_epsilon ten_to_ninety.variance, 0.05
-      end
-
-    end
+    include ERV::DistributionBehavior
   end
-
 end

data/test/erv/distribution_test.rb

@@ -1,17 +1,9 @@
-require 'test_helper'
-
-require 'erv/distribution'
-
 describe ERV::Distribution do
-
-  context 'when explicitly given an RNG' do
-
+  with 'when explicitly given an RNG' do
     it 'should use the given RNG' do
       rng = Random.new
       d = ERV::Distribution.new(rng: rng)
-      d.instance_variable_get(:@rng).must_equal rng
+      expect(d.instance_variable_get(:@rng)).to be == rng
     end
-
   end
-
 end

data/test/erv/expnorm_distribution_test.rb

@@ -0,0 +1,27 @@
+require 'erv/distribution_behaviour'
+
+describe ERV::ExpNormDistribution do
+  let(:num_samples) { 100_000 }
+
+  with 'initialization' do
+    it 'requires mu, sigma and lambda' do
+      expect{ ERV::ExpNormDistribution.new }.to raise_exception(ArgumentError)
+      expect{ ERV::ExpNormDistribution.new(mu: 0, sigma: 1) }.to raise_exception(ArgumentError)
+    end
+
+    it 'raises on invalid parameters' do
+      expect{ ERV::ExpNormDistribution.new(mu: 0, sigma: 0, lambda: 1) }.to raise_exception(ArgumentError)
+      expect{ ERV::ExpNormDistribution.new(mu: 0, sigma: 1, lambda: -1) }.to raise_exception(ArgumentError)
+    end
+  end
+
+  with 'sampling' do
+    let(:distribution) { ERV::ExpNormDistribution.new(mu: 10.0, sigma: 5.0, lambda: 0.2) }
+
+    let(:num_samples) { 200_000 }
+    let(:samples) { num_samples.times.map { distribution.sample } }
+    let(:epsilon) { 1E-2 }
+
+    include ERV::DistributionBehavior
+  end
+end