monte_carlo 0.0.5 → 0.0.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 74da23878bdb65fb83b2da57dfe27b843635ebb6
-  data.tar.gz: 99e5a8e29b89674d989a08ece215e222e225279f
+  metadata.gz: a1045401a068ca8ca900b000ca47c36a2d3b9aaf
+  data.tar.gz: 529e4a6ac17cd14dbba9a41b672202e23b83fabf
 SHA512:
-  metadata.gz: 35bade766de281601ea2b2dd9fc386349b24ddec9910ecd498a2b114c5f487a29ffbdff67c36e870d1ea141194c780dfa18c9b34f0e7d1b20d7eed9f931dc4cd
-  data.tar.gz: 77d6c42ca3d0f569c023e6fb67f9f40a926881c4892c7ee77494756c7d232b5a527df92e99c5bd4b50163a4c18878e78796a9ce36bd35a3ac1a29356bfae9d43
+  metadata.gz: 1f5ee56b4e2a2df819767c25e681de4d0103783aaf800922ea14680c119d2fd49d421128cb28038fcbd47d878e695770dc119d68c854e5a1868df51050883e37
+  data.tar.gz: 0b4eac19c056cebc1efdf5e101654d591b443bb2ab4243013a2fa84cdbefa54ec43dfcd28d83418ad1277ed9d637e7dcec231427fc3d56619be706c7536b36bc

data/.yardopts

@@ -0,0 +1,2 @@
+--no-private
+--markup=markdown

data/Gemfile

@@ -1,4 +1,12 @@
 source 'https://rubygems.org'
 
-# Specify your gem's dependencies in monte_carlo.gemspec
-gemspec
+gem 'rake'
+
+group :development do
+  gem 'yard'
+end
+
+group :test do
+  gem 'rspec', '~> 3.1'
+  gem 'rspec-its'
+end

data/README.md

@@ -20,56 +20,28 @@ Or install it yourself as:
 
 ## Usage
 
-Each experiment conatins:
-- `times`: the number of sample to create (defaults to 10,000)
-- `sample_method`: the method with which to generate a sample each iteration
-- `computation`: an optional coputation method to run on each sample to obtain a result
-- `setup` & `reset`: optional methods to run before and after each iteration
-
-For example;
-
-```ruby
-# Create an experiment with an optional number of times
-experiment = MonteCarlo::Experiment.new(100000)
-
-# Set your smaple method
-experiment.sample_method = -> { rand }
-
-# Set your optional computation method
-experiment.computation = -> (sample) { sample > 0.5 }
-
-# Run your experiment and get your results
-results = experiment.run
-```
-
-Another option is to use the configuration DSL, like so:
+Every `MonteCarlo::Experiment` must have a sample method to generate random samples. The samples generated when the experiment is run will be collected into a `MonteCarlo::ExperimentResults` object after an optional computation method to turn the random sample into a meaningful value.
+For example, the sample method may draw a random number between 1 and 10 and the computation method will test whether the number is greater than 5, returning `true` or `false` results.
 
 ```ruby
-# Create an experiment and pass it a configuration block
+# Create an instance and configure it with the DSL
 experiment = MonteCarlo::Experiment.new do
   times 1000000
-  sample_method { rand }
-  computation { |sample| sample > 0.5 }
+  sample_method { rand(10) }
+  computation { |sample| sample >= 5 }
 end
 
-# And run it normally
 results = experiment.run
-```
-
-Alternatively, you can write your sample and computation method as one with the shorthand block syntax and get the restults straight away:
 
-```ruby
-results = MonteCarlo::Experiment.run(100000) { rand > 0.5 }
+results.probability_distribution
+# => {true=>0.499443, false=>0.500557}
 ```
 
-The experiment returns a `MonteCarlo::ExperimentResults` object which contains an array of `MonteCarlo::Results` as well as some other handy methods.
+Or run it with the shorthand class method syntax:
 
-Each `MonteCarlo::Result` contains:
-- `index`: the index of the sample
-- `value`: the final value returned from sampling, after computation
-- `sample_value`: the value returned from the sample method, before computation
+## Docs
 
-If no computation method was given, `value` and `sample_value` will be the same.
+[Can be found here](http://www.rubydoc.info/gems/monte_carlo)
 
 ## Contributing
 

data/lib/monte_carlo/errors.rb

@@ -1,6 +1,7 @@
 module MonteCarlo
   module Errors
 
+    # Raised when trying to run an experiment before setting a sample method
     class NoSampleMethodError < StandardError; end
 
   end

data/lib/monte_carlo/experiment.rb

@@ -1,21 +1,65 @@
 module MonteCarlo
+  # Class to run your Monte Carlo experiments
+  #
+  # @example
+  #   experiment = MonteCarlo::Experiment.new
+  #   experiment.sample_method = -> { rand(10) }
+  #   results = experiment.run
   class Experiment
 
+    # The default number of sample methods to generate
     DEFAULT_TIMES = 10000
 
+    # @!attribute times 
+    #   @return [#times] the number of samples to generate
+    # @!attribute sample_method
+    #   @return [#call] a method to generate a sample each time
+    # @!attribute computation
+    #   @return [#call] a method to turn a random sample to a meaningful result
+    # @!attribute setup
+    #   @return [#call] a method to run before each iteration
+    # @!attribute reset
+    #   @return [#call] a method to run after each iteration
     attr_accessor :times, :sample_method, :computation, :setup, :reset
 
+    # Shorthand syntax to run a simple experiment
+    #
+    # @example
+    #   results = MonteCarlo::Experiment.run(100000) { rand(10) }
+    #
+    # @param times [optional, #times] the number of samples to generate
+    # @param block [Block] the method to generate one sample each iteration
+    # @raise [MonteCarlo::Errors::NoSampleMethodError] if no block is given
+    # @return [MonteCarlo::ExperimentResults]
     def self.run(times = DEFAULT_TIMES, &block)
       experiment = MonteCarlo::Experiment.new(times)
       experiment.sample_method = block
       experiment.run
     end
 
+    # Initialize a new experiment
+    #
+    # @example
+    #   experiment = MonteCarlo::Experiment.new do
+    #     times 100000
+    #     sample_method { rand(10) }
+    #     computation { |sample| sample >= 5  }
+    #   end
+    #   
+    #   results = experiment.run
+    #
+    # @param times [optional, #times] the number of samples to generate
+    # @param block [optional, Block] a block to configure the experiment using the {MonteCarlo::ExperimentDSL}
+    # @return [MonteCarlo::Experiment]
     def initialize(times = DEFAULT_TIMES, &block)
       @times = times
       MonteCarlo::ExperimentDSL.new(self).instance_eval(&block) if block_given?
     end
 
+    # Run the experiment
+    #
+    # @raise [MonteCarlo::Errors::NoSampleMethodError] if the experiment has no sample method set
+    # @return [MonteCarlo::ExperimentResults]
     def run
       if @sample_method.nil?
         raise MonteCarlo::Errors::NoSampleMethodError, 'A sample method for this experiment is not defined'

data/lib/monte_carlo/experiment_dsl.rb

@@ -1,26 +1,53 @@
 module MonteCarlo
+  # Class to setup an experiment using a DSL syntax
   class ExperimentDSL
 
+    # Initializes a DSL instance for the given experiment
+    #
+    # @example
+    #   experiment = MonteCarlo::Experiment.new do
+    #     times 100000
+    #     sample_method { rand(10) }
+    #     computation { |sample| sample >= 5  }
+    #   end
+    #
+    # @param experiment [MonteCarlo::Experiment] the experiment to configure
+    # @return [MonteCarlo::ExperimentDSL]
     def initialize(experiment)
       @experiment = experiment
     end
 
+    # Set the number of samples to generate
+    #
+    # @param times [#times]
     def times(times)
       @experiment.times = times
     end
 
+    # Set the sample method of the experiment
+    #
+    # @param block [Block]
     def sample_method(&block)
       @experiment.sample_method = block
     end
 
+    # Set the computation method of the experiment
+    #
+    # @param block [Block]
     def computation(&block)
       @experiment.computation = block
     end
 
+    # Set the setup method of the experiment
+    #
+    # @param block [Block]
     def setup(&block)
       @experiment.setup = block
     end
 
+    # Set the reset method of the experiment
+    #
+    # @param block [Block]
     def reset(&block)
       @experiment.reset = block
     end

data/lib/monte_carlo/experiment_results.rb

@@ -1,4 +1,5 @@
 module MonteCarlo
+  # Class containing the results of a {MonteCarlo::Experiment}
   class ExperimentResults
     include Enumerable
 
@@ -6,21 +7,33 @@ module MonteCarlo
       @results = []
     end
 
+    # Returns an enumerable of the results or runs the given block
+    #
+    # @param block [optional, Block] the block to run on each of the results
     def each(&block)
       @results.each do |result|
         block_given? ? block.call(result) : yield(result)
       end
     end
 
+    # Add a result to the list
+    #
+    # @param result [MonteCarlo::Result]
     def << result
       @results << result
       reset_memoizers
     end
 
+    # The number of results
+    #
+    # @return [Fixnum]
     def size
       @results.size
     end
 
+    # Calculates the probabilty distribution of the results
+    #
+    # @return [Hash]
     def probability_distribution
       @probability_distribution ||= @results.group_by(&:value).inject({}) do |probabilites, (value, results)|
         probabilites[value] = results.size.to_f / self.size
@@ -28,6 +41,9 @@ module MonteCarlo
       end
     end
 
+    # Calculates the frequency distibution of the results
+    #
+    # @return [Hash]
     def frequency_distribution
       @frequency_distribution ||= @results.group_by(&:value).inject({}) do |frequencies, (value, results)|
         frequencies[value] = results.size
@@ -35,10 +51,18 @@ module MonteCarlo
       end
     end
 
+    # Calcuates the probablity of the given value in the results
+    #
+    # @param value the value for which to get the probability
+    # @return [Float]
     def probability_of(value)
       probability_distribution.fetch(value, 0)
     end
 
+    # Calculates the frequency of the given value in the results
+    #
+    # @param value the value for which to get the frequency
+    # @return [Fixnum]
     def frequency_of(value)
       frequency_distribution.fetch(value, 0)
     end

data/lib/monte_carlo/result.rb

@@ -1,7 +1,14 @@
 module MonteCarlo
+  # Class that contains the result of a single sample of a {MonteCarlo::Experiment}
   class Result
     include Comparable
 
+    # @!attribute value
+    #   @return the value returned after the computation
+    # @!attribute sample_value
+    #   @return the raw value returned from the sample method
+    # @!attribute index
+    #   @return [Fixnum] the index of the iteration the result was generated at
     attr_accessor :value, :sample_value, :index
 
     def initialize(index = nil, value = nil, sample_value = nil)

data/lib/monte_carlo/version.rb

@@ -1,3 +1,7 @@
 module MonteCarlo
-  VERSION = "0.0.5"
+
+  # Current version
+  # @return [String]
+  VERSION = "0.0.6"
+
 end

data/monte_carlo.gemspec

@@ -20,8 +20,5 @@ Gem::Specification.new do |spec|
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
   spec.require_paths = ["lib"]
 
-  spec.add_development_dependency "bundler", "~> 1.7"
-  spec.add_development_dependency "rake", "~> 10.0"
-  spec.add_development_dependency "rspec", "~> 3.1"
-  spec.add_development_dependency "rspec-its"
+  spec.add_development_dependency "bundler", "~> 1.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: monte_carlo
 version: !ruby/object:Gem::Version
-  version: 0.0.5
+  version: 0.0.6
 platform: ruby
 authors:
 - Assaf Gelber
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-11-19 00:00:00.000000000 Z
+date: 2014-11-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -16,56 +16,14 @@ dependencies:
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: '1.7'
+        version: '1.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: '1.7'
-- !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: rspec
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ~>
-      - !ruby/object:Gem::Version
-        version: '3.1'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ~>
-      - !ruby/object:Gem::Version
-        version: '3.1'
-- !ruby/object:Gem::Dependency
-  name: rspec-its
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - '>='
-      - !ruby/object:Gem::Version
-        version: '0'
+        version: '1.0'
 description: A small gem to help with Monte Carlo Method experiments in ruby.
 email:
 - assaf.gelber@gmail.com
@@ -75,6 +33,7 @@ extra_rdoc_files: []
 files:
 - .gitignore
 - .travis.yml
+- .yardopts
 - Gemfile
 - LICENSE.txt
 - README.md
@@ -120,3 +79,4 @@ test_files:
 - spec/lib/monte_carlo/experiment_results_spec.rb
 - spec/lib/monte_carlo/experiment_spec.rb
 - spec/spec_helper.rb
+has_rdoc: