random_variates 0.2.2 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 67576ececc07bebc1fdca7b6f25d4c2bfc9b719765e88a63530d4bf6dcb9e982
-  data.tar.gz: 271706b932ed05415196da7836d421e2be95c7d8a887cedf715101aa50802f03
+  metadata.gz: 7d30e6b62a53350bfd18a1deb7d5338c98d7fcd479a9f5020ff7bc6e8358c256
+  data.tar.gz: 33a02922156dc7b17b9aada61693562aca6a12cf059f2e5fa775f52b7de10bc0
 SHA512:
-  metadata.gz: 7f30374ac11869a77187be0532678bb8a3f3d00afcad1a894cf341d488c563ef5ced758a5a8641b584c42f51805af78b3a8eae95486b9839cc73e7c680714601
-  data.tar.gz: d1aa14d4af1113bf220c6e02aa516cbf66f30dd5c0932e4766d11984b5656a3deb9fa08e482cca194282c3e76c3a7e2c1c49249fa34fbecdb71f96d9d5507c73
+  metadata.gz: d2d6f766aa38c6647c4f184fb279854597f7bee784b007ca1da35a3791200645872e5cc433270ce14a094408a360afac313170e155bb451653a43be03996cae4
+  data.tar.gz: 82ea2362281c4eb8fe9ee0168f88df8a77333530d8a693cafd7a5ecc5490efea05167561a2458c3b65d21033a35ac791afecb667185cdaa72e1c681907959904

data/lib/random_variates.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # This library implements random variate generation for several
 # common statistical distributions.  Each distribution is implemented
 # in its own class, and different parameterizations are created as
@@ -44,7 +46,8 @@ class Uniform
   attr_reader :min, :max
 
   def initialize(min: 0.0, max: 1.0, rng: U_GENERATOR)
-    fail 'Max must be greater than min.' if max <= min
+    raise 'Max must be greater than min.' if max <= min
+
     @min = min
     @max = max
     range = max - min
@@ -57,32 +60,61 @@ end
 # Triangular random variate generator with specified +min+, +mode+, and +max+.
 #
 # *Arguments*::
-#   - +min+ -> the lower bound for the range (default: 0).
-#   - +max+ -> the upper bound for the range (default: 1).
-#   - +mode+ -> the highest likelihood value (+min+ ≤ +mode+ ≤ +max+; default: 1).
 #   - +rng+ -> the (+Enumerable+) source of U(0, 1)'s (default: U_GENERATOR)
+#   - +min+ -> the lower bound for the range.
+#   - +max+ -> the upper bound for the range.
+#   - +mode+ -> the highest likelihood value (+min+ ≤ +mode+ ≤ +max+).
+#   - +mean+ -> the expected value of the distribution.
 #
 class Triangle
   include RV_Generator
 
-  attr_reader :min, :max, :mode, :range
+  attr_reader :min, :max, :mode, :range, :mean
 
-  def initialize(min: 0.0, max: 1.0, mode: 1.0, rng: U_GENERATOR)
-    @range = max - min
-    fail 'Min must be less than Max.' if @range <= 0
-    fail 'Mode must be between Min and Max.' unless (min..max).include? mode
-    @min = min
-    @max = max
-    @mode = mode
-    crossover_p = (mode - min).to_f / @range
+  def initialize(rng: U_GENERATOR, **args)
+    param_names = %i[mean min max mode]
+    unless args.size > 2 && args.keys.all? { |k| param_names.include? k }
+      raise "invalid args - can only be #{param_names.join ', '}, or rng."
+    end
+
+    param_names.each { |k| args[k] ||= nil } if args.size < param_names.size
+
+    nil_args = args.select { |_, v| v.nil? }.keys
+    nil_args_count = nil_args.count
+    raise 'too many nil args' if nil_args_count > 1
+
+    args.transform_values! &:to_f
+
+    if nil_args_count == 0
+      if args[:mean] != (args[:min] + args[:max] + args[:mode]) / 3.0
+        raise 'inconsistent args'
+      end
+    else
+      key = nil_args.shift
+      case key
+      when :mean
+        args[key] = (args[:min] + args[:max] + args[:mode]) / 3.0
+      else
+        others = param_names - [key, :mean]
+        args[key] = 3 * args[:mean] - args.values_at(*others).sum
+      end
+    end
+
+    param_names.each { |parm| instance_variable_set("@#{parm}", args[parm]) }
+
+    @range = @max - @min
+    raise 'Min must be less than Max.' if @range <= 0
+    raise 'Mode must be between Min and Max.' unless (@min..@max).include? @mode
+
+    crossover_p = (@mode - @min).to_f / @range
     @generator = Enumerator.new do |yielder|
       loop do
         u = rng.next
-        if u < crossover_p
-          yielder << min + Math.sqrt(@range * (mode - min) * u)
-        else
-          yielder << max - Math.sqrt(@range * (max - mode) * (1.0 - u))
-        end
+        yielder << (
+          u < crossover_p ?
+            @min + Math.sqrt(@range * (@mode - @min) * u) :
+            @max - Math.sqrt(@range * (@max - @mode) * (1.0 - u))
+        )
       end
     end
   end
@@ -99,16 +131,19 @@ end
 class Exponential
   include RV_Generator
 
-  attr_reader :rate
+  attr_reader :rate, :mean
 
   def initialize(rate: nil, mean: nil, rng: U_GENERATOR)
-    fail 'Rate must be positive.' if rate && rate <= 0
-    fail 'Mean must be positive.' if mean && mean <= 0
-    fail 'Supply one and only one of mean or rate' unless rate.nil? ^ mean.nil?
+    raise 'Rate must be positive.' if rate && rate <= 0
+    raise 'Mean must be positive.' if mean && mean <= 0
+    raise 'Supply one and only one of mean or rate' unless rate.nil? ^ mean.nil?
+
     if rate.nil?
-      @mean, @rate = mean, 1.0 / mean
+      @mean = mean
+      @rate = 1.0 / mean
     else
-      @mean, @rate = 1.0 / rate, rate
+      @mean = 1.0 / rate
+      @rate = rate
     end
     @generator = Enumerator.new do |yielder|
       loop { yielder << (-@mean * Math.log(rng.next)) }
@@ -130,27 +165,29 @@ class Gaussian
   attr_reader :mean, :sd
 
   def initialize(mean: 0.0, sd: 1.0, rng: U_GENERATOR)
-    fail 'Standard deviation must be positive.' if sd <= 0
+    raise 'Standard deviation must be positive.' if sd <= 0
+
     @mean = mean
     @sd = sd
     @generator = Enumerator.new do |yielder|
       # Ratio of Uniforms
       bound = 2.0 * Math.sqrt(2.0 / Math::E)
       loop do
-          u = rng.next
-          next if u == 0.0
-          v = bound * (rng.next - 0.5)
-          x = v / u
-          x_sqr = x * x
-          u_sqr = u * u
-          if 6.0 * x_sqr <= 44.0 - 72.0 * u + 36.0 * u_sqr - 8.0 * u * u_sqr
-            yielder << sd * x + mean
-          elsif x_sqr * u >= 2.0 - 2.0 * u_sqr
-            next
-          elsif x_sqr <= -4.0 * Math.log(u)
-            yielder << sd * x + mean
-          end
+        u = rng.next
+        next if u == 0.0
+
+        v = bound * (rng.next - 0.5)
+        x = v / u
+        x_sqr = x * x
+        u_sqr = u * u
+        if 6.0 * x_sqr <= 44.0 - 72.0 * u + 36.0 * u_sqr - 8.0 * u * u_sqr
+          yielder << sd * x + mean
+        elsif x_sqr * u >= 2.0 - 2.0 * u_sqr
+          next
+        elsif x_sqr <= -4.0 * Math.log(u)
+          yielder << sd * x + mean
         end
+      end
     end
   end
 end
@@ -169,7 +206,8 @@ class BoxMuller
   attr_reader :mean, :sd
 
   def initialize(mean: 0.0, sd: 1.0, rng: U_GENERATOR)
-    fail 'Standard deviation must be positive.' if sd <= 0
+    raise 'Standard deviation must be positive.' if sd <= 0
+
     @mean = mean
     @sd = sd
     @generator = Enumerator.new do |yielder|
@@ -193,6 +231,8 @@ end
 
 # Gamma generator based on Marsaglia and Tsang method Algorithm 4.33
 #
+# Produces gamma RVs with expected value +alpha+ * +beta+.
+#
 # *Arguments*::
 #   - +alpha+ -> the shape parameter (+alpha+ > 0; default: 1).
 #   - +beta+ -> the rate parameter (+beta+ > 0; default: 1).
@@ -204,7 +244,8 @@ class Gamma
   attr_reader :alpha, :beta
 
   def initialize(alpha: 1.0, beta: 1.0, rng: U_GENERATOR)
-    fail 'Alpha and beta must be positive.' if alpha <= 0 || beta <= 0
+    raise 'Alpha and beta must be positive.' if alpha <= 0 || beta <= 0
+
     @alpha = alpha
     @beta = beta
     std_normal = Gaussian.new(mean: 0.0, sd: 1.0, rng: rng)
@@ -252,7 +293,8 @@ class Weibull
   attr_reader :rate, :k
 
   def initialize(rate: 1.0, k: 1.0, rng: U_GENERATOR)
-    fail 'Rate and k must be positive.' if rate <= 0 || k <= 0
+    raise 'Rate and k must be positive.' if rate <= 0 || k <= 0
+
     @rate = rate
     @k = k
     power = 1.0 / k
@@ -271,11 +313,43 @@ end
 #
 class Erlang < Weibull
   def initialize(rate: 1.0, k: 1, rng: U_GENERATOR)
-    fail 'K must be integer.' unless k.integer?
+    raise 'K must be integer.' unless k.integer?
+
     super(rate: rate, k: k, rng: rng)
   end
 end
 
+# von Mises generator.
+#
+# This von Mises distribution generator is based on the VML algorithm by
+# L. Barabesis: "Generating von Mises variates by the Ratio-of-Uniforms Method"
+# Statistica Applicata Vol. 7, #4, 1995
+# http://sa-ijas.stat.unipd.it/sites/sa-ijas.stat.unipd.it/files/417-426.pdf
+#
+# *Arguments*::
+#   - +kappa+ -> concentration coefficient (+kappa+ ≥ 0).
+#   - +rng+ -> the (+Enumerable+) source of U(0, 1)'s (default: U_GENERATOR)
+#
+class VonMises
+  include RV_Generator
+
+  attr_reader :kappa
+
+  def initialize(kappa:, rng: U_GENERATOR)
+    raise 'kappa must be positive.' if kappa < 0
+    s = (kappa > 1.3 ? 1.0 / Math.sqrt(kappa) : Math::PI * Math.exp(-kappa))
+    @generator = Enumerator.new do |yielder|
+      loop do
+        r1 = rng.next
+        theta = s * (2.0 * rng.next - 1.0) / r1
+        next if (theta.abs > Math::PI)
+        yielder << theta if (0.25 * kappa * theta * theta < 1.0 - r1) ||
+                      (0.5 * kappa * (Math.cos(theta) - 1.0) >= Math.log(r1))
+      end
+    end
+  end
+end
+
 # Poisson generator.
 #
 # *Arguments*::
@@ -288,7 +362,8 @@ class Poisson
   attr_reader :rate
 
   def initialize(rate: 1.0, rng: U_GENERATOR)
-    fail 'rate must be positive.' if rate <= 0
+    raise 'rate must be positive.' if rate <= 0
+
     @rate = rate
     threshold = Math.exp(-rate)
     @generator = Enumerator.new do |yielder|
@@ -314,7 +389,8 @@ class Geometric
   attr_reader :p
 
   def initialize(p: 0.5, rng: U_GENERATOR)
-    fail 'Require 0 < p < 1.' if p <= 0 || p >= 1
+    raise 'Require 0 < p < 1.' if p <= 0 || p >= 1
+
     @p = p
     log_q = Math.log(1 - p)
     @generator = Enumerator.new do |yielder|
@@ -336,8 +412,9 @@ class Binomial
   attr_reader :n, :p
 
   def initialize(n: 1, p: 0.5, rng: U_GENERATOR)
-    fail 'N must be a positive integer.' if n.to_i != n || n <= 0
-    fail 'Require 0 < p < 1.' if p <= 0 || p >= 1
+    raise 'N must be a positive integer.' if n.to_i != n || n <= 0
+    raise 'Require 0 < p < 1.' if p <= 0 || p >= 1
+
     @n = n.to_i
     @p = p
     log_q = Math.log(1 - p)
@@ -347,6 +424,7 @@ class Binomial
         loop do
           sum += Math.log(rng.next) / (n - result)
           break if sum < log_q
+
           result += 1
         end
         yielder << result

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: random_variates
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.3.0
 platform: ruby
 authors:
 - Paul J Sanchez
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-07-15 00:00:00.000000000 Z
+date: 2019-08-28 00:00:00.000000000 Z
 dependencies: []
 description: Random variate generators implemented as enumerator/enumerable.
 email: pjs@alum.mit.edu
@@ -38,8 +38,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.7.7
+rubygems_version: 3.0.3
 signing_key: 
 specification_version: 4
 summary: Random variate generator classes.