croupier 1.1.0 → 1.2.0

data/README.md

@@ -32,6 +32,8 @@ where:
 
 ### Available distributions and options
 
+Current version provides: Cauchy, exponential, normal, Poisson, triangular and uniform distributions.
+
 To get a list of all the available distributions use the ```--help``` (or ```-h```) option with croupier:
 
     $ croupier --help
@@ -54,6 +56,13 @@ And then use the the distribution you want to generate the sample. You can get j
     dist.generate_sample(100) #=> returns an array of 100 random numbers following an exponential with rate 1.7
     dist.generate_number #=> returns one random number following an exponential with rate 1.7
 
+## How to generate a distribution.
+
+There are several ways. The easiest one is to override ```generate_number``` or ```generate_sample``` (one is enough).
+
+Nonetheless there is another cool way to implement a distribution: implementing ```inv_cdf```. ``ìnv_cdf``` receives a
+parameter ```n``` that is a sample of a uniform distribution. It should return the inverse of the cdf applied to ```n```.
+
 ## License
 
 Croupier is released under the MIT license.

data/RUNNING_TESTS.md

@@ -15,13 +15,27 @@ You can run these tests using the default Rake task:
 ### R tests
 
 There's a group of tests validating the probability distribution of several samples of numbers generated with Croupier.
+To generate samples to be tested, run the script ```generate_test_data.sh```:
+
+    > ./generate_test_data.sh
+
+Now you can run the R testsuite:
 These tests are statistical tests included in R scripts.
 To run them you need to have R installed in your system. You can get the R software from ```http://www.r-project.org/```
+
+Dependencies:
+
 The testsuite uses the 'testthat' package. You can install it from the R console with the folowing command:
 
     install.packages("testthat", repos = "http://cran.r-project.org/", type="source")
 
-Once you have R and all the dependencies installed in your system, you can run the test/testsuite.R file:
+Other R packages needed:
+
+    * triangle
+    * vcd
+
+The test script will try to intall all dependencies if they are not found in your R installation.
+You can run the test/testsuite.R file:
 
 Using Rscript:
 

data/lib/croupier/distribution.rb

@@ -27,12 +27,25 @@ module Croupier
 
     # Main method to generate n random numbers using the current probability distribution
     def generate_sample(n=1)
-      (1..n).map { generate_number }
+      if self.respond_to? :inv_cdf
+        (1..n).map{ inv_cdf(rand) }
+      else
+        (1..n).map{ generate_number }
+      end
     end
 
     # Generates one random number using the current probability distribution
     def generate_number
-      generate_sample 1
+      if self.respond_to? :inv_cdf
+        inv_cdf(rand)
+      else
+        generate_sample 1
+      end
+    end
+
+    # convenience method for lazy programmers
+    def params
+      @parameters
     end
 
     # Defines a hash with banner and all available CLI options.

data/lib/croupier/distributions/cauchy.rb

@@ -0,0 +1,39 @@
+module Croupier
+  module Distributions
+
+    #####################################################################
+    # Cauchy Distribution
+    # Continuous probability distribution describing resonance behavior.
+    #
+    class Cauchy < ::Croupier::Distribution
+
+      def initialize(options={})
+        @name = "Cauchy distribution"
+        @description = "Continuous probability distribution describing resonance behavior"
+        configure(options)
+        raise Croupier::InputParamsError, "Invalid scale value, it must be positive" unless params[:scale] > 0
+      end
+
+      def inv_cdf n
+        params[:location] + (params[:scale] * Math.tan(Math::PI * (0.5 - n)))
+      end
+
+      def default_parameters
+        {:location => 0.0, :scale => 1.0}
+      end
+
+      def self.cli_name
+        "cauchy"
+      end
+
+      def self.cli_options
+        {:options => [
+           [:location, 'location param', {:type=>:float, :default => 0.0}],
+           [:scale, 'scale param', {:type=>:float, :default => 1.0}],
+         ],
+         :banner => "Cauchy continuous distribution. Generate numbers following a Cauchy distribution with location and scale parameters"
+        }
+      end
+    end
+  end
+end

data/lib/croupier/distributions/exponential.rb

@@ -12,11 +12,11 @@ module Croupier
         @name = "Exponential distribution"
         @description = "Continuous probability distribution with a lambda param rate describing the time between events in a Poisson process"
         configure(options)
+        raise Croupier::InputParamsError, "Invalid interval values" if params[:lambda] <= 0
       end
 
-      def generate_number
-        raise Croupier::InputParamsError, "Invalid interval values" if @parameters[:lambda] <= 0
-        (-1/@parameters[:lambda]) * Math.log(rand)
+      def inv_cdf n
+        (-1/params[:lambda]) * Math.log(n)
       end
 
       def default_parameters

data/lib/croupier/distributions/normal.rb

@@ -9,7 +9,7 @@ module Croupier
     class Normal < ::Croupier::Distribution
 
       def initialize(options={})
-        @name = "Uniform distribution"
+        @name = "Normal distribution"
         @description = "Continuous distribution (mu,sigma) (defaults to (0,1) ) where mu is the mean and sigma the standard deviation."
         configure(options)
       end
@@ -28,8 +28,8 @@ module Croupier
         end
 
         # Adjust parameters.
-        gen.map!{ |x| x * @parameters[:std] }  if @parameters[:std] != 1
-        gen.map!{ |x| x + @parameters[:mean] } if @parameters[:mean] != 0
+        gen.map!{ |x| x * params[:std] }  if params[:std] != 1
+        gen.map!{ |x| x + params[:mean] } if params[:mean] != 0
 
         # Adjust length
         n.odd? ? gen[0..-2] : gen
@@ -48,7 +48,7 @@ module Croupier
            [:mean, 'mean of the distribution', {:type=>:float, :default => 0.0}],
            [:std, 'standard deviation of the distribution', {:type=>:float, :default => 1.0}]
          ],
-         :banner => "Normal distribution. Generate numbers following a continuous distribution the real line with mean :mean and standard deviation :std."
+         :banner => "Normal distribution. Generate numbers following a continuous distribution in the real line with mean :mean and standard deviation :std."
         }
       end
     end

data/lib/croupier/distributions/poisson.rb

@@ -0,0 +1,47 @@
+module Croupier
+  module Distributions
+
+    #####################################################################
+    # Poisson Distribution
+    # Discrete probability distribution that expresses the probability
+    # of a given number of event occurrin in a fixed interval of time
+    # and/or space if these events occur with a known average rate
+    # and independently of the time since the las event.
+    #
+    # Wikipedia http://en.wikipedia.org/wiki/Poisson_distribution
+    class Poisson < ::Croupier::Distribution
+
+      def initialize(options={})
+        @name = "Poisson distribution"
+        @description = "Discrete probability distribution that expresses the probability of a given number of events occurring in a fixed interval of time."
+        configure(options)
+      end
+
+      def generate_number
+        l = Math.exp(-params[:lambda])
+        k = 0; p = 1;
+        while p > l
+          p *= rand
+          k += 1;
+        end
+        k-1
+      end
+
+      def default_parameters
+        {:lambda => 50}
+      end
+
+      def self.cli_name
+        "poisson"
+      end
+
+      def self.cli_options
+        {:options => [
+           [:lambda, 'rate parameter (equal to the mean of the distribution)', {:type=>:integer, :default => 50}]
+         ],
+         :banner => "Poisson distribution. Discrete probability distribution that expresses the probability of a given number of events occurring in a fixed interval of time."
+        }
+      end
+    end
+  end
+end

data/lib/croupier/distributions/triangular.rb

@@ -0,0 +1,49 @@
+module Croupier
+  module Distributions
+
+    #####################################################################
+    # Triangular Distribution
+    # Continuous probability distribution whose lower limit
+    # is a, upper limit b and mode c (a <= c <= b).
+    class Triangular < ::Croupier::Distribution
+
+      def initialize(options={})
+        @name = "Triangular distribution"
+        @description = "Continuous probability distribution whose lower limit is a, upper limit b and mode c (a <= c <= b)"
+        configure(options)
+        raise Croupier::InputParamsError, "Invalid interval values" if params[:a] >= params[:b]
+        if params[:c] < params[:a] || params[:b] <  params[:c]
+          warn("Mode is not in the support. Mode value will be change to median.")
+          params[:c] = (params[:a]+params[:b])/2;
+        end
+        @F_c = (params[:c]-params[:a])/(params[:b]-params[:a])
+      end
+
+      def inv_cdf n
+        if n < @F_c
+          params[:a] + Math.sqrt(   n   * (params[:b] - params[:a]) * (params[:c] - params[:a]) )
+        else
+          params[:b] - Math.sqrt( (1-n) * (params[:b] - params[:a]) * (params[:b] - params[:c]) )
+        end
+      end
+
+      def default_parameters
+        {:a => 0.0, :b => 1.0, :c => 0.5}
+      end
+
+      def self.cli_name
+        "triangular"
+      end
+
+      def self.cli_options
+        {:options => [
+           [:a, 'lower limit', {:type=>:float, :default => 0.0}],
+           [:b, 'upper limit', {:type=>:float, :default => 1.0}],
+           [:c, 'mode'       , {:type=>:float, :default => 0.5}]
+         ],
+         :banner => "Triangular distribution. Continuous distribution whose support is the interval (a,b), with mode c."
+        }
+      end
+    end
+  end
+end

data/lib/croupier/distributions/uniform.rb

@@ -15,12 +15,12 @@ module Croupier
       end
 
       def generate_number
-        raise Croupier::InputParamsError, "Invalid interval values" if @parameters[:b] < @parameters[:a]
-        rand Range.new(@parameters[:a], @parameters[:b])
+        raise Croupier::InputParamsError, "Invalid interval values" if params[:b] < params[:a]
+        rand Range.new(params[:a], params[:b])
       end
 
       def default_parameters
-        {:a => 0, :b => 1}
+        {:a => 0.0, :b => 1.0}
       end
 
       def self.cli_name

data/lib/croupier.rb

@@ -4,14 +4,14 @@ require 'croupier/distribution'
 Dir[File.join(File.dirname(__FILE__), "./croupier/distributions/*.rb")].each {|f| require f}
 require 'croupier/cli/application'
 #####################################################################
-# Croupier module. 
+# Croupier module.
 # Used as a namespace containing all the Croupier code.
 # The module defines a Croupier::CLI::Application and interacts with the user output console.
 #
 module Croupier
   STDERR = $stderr
   STDOUT = $stdout
-  
+
   # Croupier module singleton methods.
   #
   class << self
@@ -53,7 +53,7 @@ module Croupier
     def clear_line!
       self.write "\r"
     end
-    
+
     # Trap SIGINT signal
     def trap_interrupt
       trap('INT') do
@@ -61,4 +61,4 @@ module Croupier
       end
     end
   end
-end
+end

data/test/distributions/R_tests/test_cauchy.R

@@ -0,0 +1,28 @@
+context('** Cauchy Distribution **')
+# Run a K-S test on the Croupier sample against a Cauchy R-generated sample
+# Accept Croupier's sample as Cauchy if p-value > 0.05
+# Also check for a statistic near 0
+
+context('Kolmogorov-Smirnov test for default (location, scale) = (0,1)')
+  croupier_cauchy <- read.table("../generated_samples/cauchy_0_1.data")
+  ks_result<-ks.test(croupier_cauchy$V1, "pcauchy")
+
+  test_that("p-value > 0.05", {
+    expect_true(ks_result$p.value > 0.05)
+  })
+
+  test_that("statistic converging to 0", {
+    expect_true(as.numeric(ks_result$statistic) < 0.05)
+  })
+
+context('Kolmogorov-Smirnov test for given (location, scale) = (12, 3)')
+  croupier_cauchy <- read.table("../generated_samples/cauchy_12_3.data")
+  ks_result<-ks.test(croupier_cauchy$V1, "pcauchy", location=12, scale=3)
+
+  test_that("p-value > 0.05", {
+    expect_true(ks_result$p.value > 0.05)
+  })
+
+  test_that("statistic converging to 0", {
+    expect_true(as.numeric(ks_result$statistic) < 0.05)
+  })

data/test/distributions/R_tests/test_poisson.R

@@ -0,0 +1,17 @@
+context('** Poisson Distribution **')
+
+context('ChiSquare Goodness of Fit test for mean = 5')
+  croupier_poisson <- read.table("../generated_samples/poisson_5.data")
+  cs_result<-summary(goodfit(croupier_poisson$V1, type="poisson", method="ML", par=list(lambda=5)))
+
+  test_that("p-value > 0.05, poisson mean = 5", {
+    expect_true(cs_result['Pearson',3] > 0.05)
+  })
+
+context('ChiSquare Goodness of Fit test for mean = 50')
+  croupier_poisson <- read.table("../generated_samples/poisson_50.data")
+  cs_result<-summary(goodfit(croupier_poisson$V1, type="poisson", method="ML", par=list(lambda=50)))
+
+  test_that("err, poisson lambda = 50", {
+    expect_true(cs_result['Pearson',3] > 0.05)
+  })

data/test/distributions/R_tests/test_triangular.R

@@ -0,0 +1,28 @@
+context('** Triangular Distribution **')
+# Run a K-S test on the Croupier sample against a exponential R-generated sample
+# Accept Croupier's sample as exponential if p-value > 0.05
+# Also check for a statistic near 0
+
+context('Kolmogorov-Smirnov test for a = -1, b = 5, c=4')
+  croupier_exponential <- read.table("../generated_samples/triangular_-1_5_4.data")
+  ks_result<-ks.test(croupier_exponential$V1, "ptriangle", a=-1, b=5, c=4)
+
+  test_that("p-value > 0.05 triangular, not default parameters", {
+    expect_true(ks_result$p.value > 0.05)
+  })
+
+  test_that("statistic converging to 0", {
+    expect_true(as.numeric(ks_result$statistic) < 0.05)
+  })
+
+context('Kolmogorov-Smirnov test for default values a=0, b=1, c=0.5')
+  croupier_exponential <- read.table("../generated_samples/triangular_0_1_05.data")
+  ks_result<-ks.test(croupier_exponential$V1, "ptriangle", a=0, b=1, c=0.5)
+
+  test_that("p-value > 0.05 triangular, default parameters", {
+    expect_true(ks_result$p.value > 0.05)
+  })
+
+  test_that("statistic converging to 0", {
+    expect_true(as.numeric(ks_result$statistic) < 0.05)
+  })

data/test/test_distribution_class.rb

@@ -28,4 +28,21 @@ class TestDistributionClass < MiniTest::Unit::TestCase
     assert_equal a.generate_sample(15).size, 15
   end
 
+  def test_generate_number_calls_inv_cdf_if_present
+    c = Class.new(Croupier::Distribution) do
+      def inv_cdf n; true; end
+      def generate_sample n; false; end
+    end
+    a = c.new
+    assert a.generate_number
+  end
+
+  def test_generate_sample_calls_inv_cdf_if_present
+    c = Class.new(Croupier::Distribution) do
+      def inv_cdf n; true; end
+      def generate_number n; false; end
+    end
+    a = c.new
+    assert a.generate_sample(3).all?
+  end
 end

data/test/testsuite.R

@@ -1,6 +1,7 @@
 #!/usr/bin/env Rscript
 #
 # This script runs all the R tests of the croupier gem for all the distributions.
+# 
 # Running the script:
 #  Option 1, Via Rscript:
 #    $> Rscript testsuite.R
@@ -8,9 +9,29 @@
 #  Option 2, from the R console:
 #    source('testsuite.R')
 #
-# In order to run the tests you need to have installed the testthat package
-# If it is not included in your R installation you can do so running this command:
-# install.packages("testthat", repos = "http://cran.r-project.org/", type="source")
-#
-library("testthat")
+# Dependencies:
+# In order to run the tests you need to have installed the following packages:
+# 
+#   - testthat
+#   - triangle
+#   - vcd
+# 
+# Croupier will try to install them automatically if they are not included
+# in your R installation.
+
+if(require('testthat') == FALSE) {
+  install.packages('testthat', repos = "http://cran.r-project.org/", type="source")
+  require('testthat')
+}
+
+if(require('triangle') == FALSE) {
+  install.packages('triangle')
+  require('triangle')
+}
+if(require('vcd') == FALSE) {
+  install.packages('vcd')
+  require('vcd')
+}
+options(warn=-1)
 test_dir("./distributions/R_tests/")
+options(warn=0)

metadata

@@ -1,15 +1,16 @@
 --- !ruby/object:Gem::Specification
 name: croupier
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
   prerelease: 
 platform: ruby
 authors:
 - Juanjo Bazán
+- Sergio Arbeo
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-06-09 00:00:00.000000000 Z
+date: 2012-06-21 00:00:00.000000000 Z
 dependencies: []
 description: Croupier is a Ruby gem to generate a random sample of numbers with a
   given probability distribution.
@@ -27,20 +28,20 @@ files:
 - lib/croupier/cli/application.rb
 - lib/croupier/cli/trollop.rb
 - lib/croupier/distribution.rb
+- lib/croupier/distributions/cauchy.rb
 - lib/croupier/distributions/exponential.rb
 - lib/croupier/distributions/normal.rb
+- lib/croupier/distributions/poisson.rb
+- lib/croupier/distributions/triangular.rb
 - lib/croupier/distributions/uniform.rb
 - lib/croupier/exceptions.rb
 - lib/croupier.rb
+- test/distributions/R_tests/test_cauchy.R
 - test/distributions/R_tests/test_exponential.R
 - test/distributions/R_tests/test_normal.R
+- test/distributions/R_tests/test_poisson.R
+- test/distributions/R_tests/test_triangular.R
 - test/distributions/R_tests/test_uniform.R
-- test/distributions/generated_samples/exponential_1.data
-- test/distributions/generated_samples/exponential_1_6.data
-- test/distributions/generated_samples/normal_0_1.data
-- test/distributions/generated_samples/normal_5_6.data
-- test/distributions/generated_samples/uniform_0_1.data
-- test/distributions/generated_samples/uniform_5_33.data
 - test/test_croupier_module.rb
 - test/test_distribution_class.rb
 - test/testsuite.R
@@ -73,15 +74,12 @@ signing_key:
 specification_version: 3
 summary: Samples of random numbers with specific probability distributions
 test_files:
+- test/distributions/R_tests/test_cauchy.R
 - test/distributions/R_tests/test_exponential.R
 - test/distributions/R_tests/test_normal.R
+- test/distributions/R_tests/test_poisson.R
+- test/distributions/R_tests/test_triangular.R
 - test/distributions/R_tests/test_uniform.R
-- test/distributions/generated_samples/exponential_1.data
-- test/distributions/generated_samples/exponential_1_6.data
-- test/distributions/generated_samples/normal_0_1.data
-- test/distributions/generated_samples/normal_5_6.data
-- test/distributions/generated_samples/uniform_0_1.data
-- test/distributions/generated_samples/uniform_5_33.data
 - test/test_croupier_module.rb
 - test/test_distribution_class.rb
 - test/testsuite.R