statistical 0.1.0

data/data/template/rng.erb

@@ -0,0 +1,53 @@
+require 'statistical/exceptions'
+require 'statistical/distribution/<%= distribution%>'
+
+module Statistical
+  # Companion RNG class for the continuous uniform distribution. Requires a
+  #   distrbution object of the corresponding distribution
+  #
+  # @author Vaibhav Yenamandra
+  #
+  # @attr_reader [Numeric] lower The lower bound of the uniform distribution.
+  # @attr_reader [Numeric] upper The upper bound of the uniform distribution.
+  module Rng
+    class <%= distribution.capitalize.camelcase %>
+      attr_reader :generator, # other params go here
+      
+      def initialize(dobj = nil, seed = Random.new_seed)
+        unless dobj.nil? || dobj.is_a?(Statistical::Distribution::<%= distribution.capitalize.camelcase %>)
+          raise TypeError, "Expected Distribution object or nil, found #{dobj.class}"
+        end
+        dobj = Statistical::Distribution::<%= distribution.capitalize.camelcase %>.new if dobj.nil?
+        @generator = Rng::Uniform.new(Distribution::Uniform.new, seed)
+        # Map other parameters here
+        @sdist = dobj
+      end
+
+      # Return the next random number from the sequence
+      #
+      # @return next random number in the sequence
+      def rand
+      end
+
+      # Compare against another rng to see if they are the same
+      #
+      # @return true if and only if, source distributions are the same and the
+      #   prng has the same initial state
+      def eql?(other)
+        return false unless other.is_a?(self.class)
+        # Compare parameters and other stuff here
+        @generator == other.generator
+      end
+
+      # Return the type of the source distribution
+      #
+      # @return source distribution's type
+      def type
+        @sdist.class
+      end
+
+      alias_method :==, :eql?
+      private :eql?
+    end
+  end
+end

data/data/template/spec.erb

@@ -0,0 +1,142 @@
+require 'spec_helper'
+require 'statistical/rng/<%= distribution%>'
+require 'statistical/distribution/<%= distribution %>'
+
+describe Statistical::Rng::<%= distribution.capitalize.camelcase %> do
+  it 'passes the G-test at a 95% significance level' do
+  end
+
+  describe '.new' do
+    context 'when called with no arguments' do
+      fail
+    end
+
+    context 'when parameters are specified' do
+      fail
+    end
+
+    context 'when initialized with a seed' do
+      it 'should be repeatable for the same arguments' do
+        fail
+      end
+    end
+  end
+
+  describe '#rand' do
+    it 'returns a number between 0 and 1 by default' do
+      fail
+    end
+
+    it 'returns a bounded value when bounds are specified' do
+      fail
+    end
+  end
+
+  describe '#==' do
+    context 'when compared against another uniform distribution' do
+      it 'should return true if the bounds and seed are the same' do
+        fail
+      end
+
+      it 'should return false if bounds / seed differ' do
+        fail
+      end
+    end
+
+    context 'when compared against any other distribution class' do
+      it 'should return false if classes are different' do
+        fail
+      end
+    end
+  end
+end
+
+
+describe Statistical::Distribution::<%= distribution.capitalize.camelcase %> do
+  describe '.new' do
+    context 'when called with no arguments' do
+      fail
+    end
+    
+    context 'when upper and lower bounds are specified' do
+      fail
+    end
+  end
+  
+  
+  describe '#pdf' do
+    context 'when called with x < lower_bound' do
+      fail
+    end
+    
+    context 'when called with x > upper_bound' do
+      fail
+    end
+    
+    context 'when called with x in [lower_bound, upper_bound]' do
+      fail
+    end
+  end
+  
+  describe '#cdf' do
+    context 'when called with x < lower' do
+      fail
+    end
+    
+    context 'when called with x > upper' do
+      fail
+    end
+    
+    context 'when called with x in [lower, upper]' do
+      fail
+    end
+  end
+  
+  describe '#quantile' do
+    context 'when called for x > 1' do
+      fail
+    end
+    
+    context 'when called for x < 0' do
+      fail
+    end
+    
+    context 'when called for x in [0, 1]' do
+      fail
+    end
+  end
+  
+  describe '#p_value' do
+    it 'should be the same as #quantile' do
+      fail
+    end
+  end  
+  
+  describe '#mean' do
+    it 'should return the correct mean' do
+      fail
+    end
+  end
+  
+  describe '#variance' do
+    it 'should return the correct variance' do
+      fail
+    end
+  end
+  
+  describe '#==' do
+    context 'when compared against another Uniform distribution' do
+      it 'returns `true` if they have the same parameters' do
+        fail
+      end
+      
+      it 'returns `false` if they have different parameters' do
+        fail
+      end
+    end
+    
+    context 'when compared against any distribution type' do
+      fail
+    end
+  end
+end

data/lib/core_extensions.rb

@@ -0,0 +1,35 @@
+# All core class modifications go here
+String.class_eval do
+  # Convert CamelCase to snake_case
+  def snakecase
+    gsub(/::/, '/')
+      .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+      .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+      .tr('-', '_')
+      .downcase
+  end
+
+  # convert snake_case to CamelCase
+  def camelcase
+    split('_').map(&:capitalize).join
+  end
+end
+
+Array.class_eval do
+  def sum
+    inject(:+)
+  end
+
+  def mean
+    sum.fdiv(count)
+  end
+
+  def variance
+    map { |x| (x - mean)**2}.sum.fdiv(count)
+  end
+
+  def comprehend(&block)
+    return self if block.nil?
+    collect(&block).compact
+  end
+end

data/lib/statistical.rb

@@ -0,0 +1,7 @@
+require 'statistical/version'
+require 'statistical/distribution'
+require 'statistical/rng'
+require 'core_extensions'
+
+module Statistical
+end

data/lib/statistical/distribution.rb

@@ -0,0 +1,36 @@
+require 'statistical/distribution/uniform'
+require 'statistical/distribution/uniform_discrete'
+require 'statistical/distribution/two_point'
+require 'statistical/distribution/bernoulli'
+require 'statistical/distribution/exponential'
+require 'statistical/distribution/laplace'
+require 'statistical/distribution/weibull'
+
+module Statistical
+  # Factory module used to create instances of various distributions classes
+  # nested under itself
+  module Distribution
+    # @private
+    # No need to document this
+    # Dynamically add constants when called
+    def self.const_missing(cname)
+      const_set(cname, make_classmap) if cname == :DISTRIBUTION_TYPES
+    end
+
+    # Create a distribution identified by the type hash
+    # @raise ArgumentError if `type` was not found
+    def self.create(type = :uniform, *args, &block)
+      raise ArgumentError unless DISTRIBUTION_TYPES.include?(type)
+      DISTRIBUTION_TYPES[type].new(*args, &block)
+    end
+
+    def self.make_classmap
+      dist_klasses = constants.select { |k| const_get(k).is_a?(Class)}
+      keylist = dist_klasses.map { |k| k.to_s.snakecase.to_sym}
+      klasses = dist_klasses.map { |k| const_get(k)}
+      return Hash[keylist.zip(klasses)].freeze
+    end
+
+    private_class_method :make_classmap
+  end
+end

data/lib/statistical/distribution/bernoulli.rb

@@ -0,0 +1,29 @@
+require 'statistical/distribution/two_point'
+
+module Statistical
+  module Distribution
+    # This is a convenience class implemented for syntactic sugar.
+    # `TwoPoint.new(p)` already mimics and is infact the behaviour of this class
+    #
+    # @note The states used to represent success & failure must be Numeric.
+    #   Using it on generic state lables can cause strange outcomes!
+    #
+    # @note state_failure < state_sucesss, for the sake of sanity.
+    #
+    # @author Vaibhav Yenamandra
+    # @attr_reader [Float] p probability of the success state (= 1)
+    # @attr_reader [Float] q probability of the failure state (= 0)
+    class Bernoulli < TwoPoint
+      # This is probably the best but the least descriptive variable name
+      # attr_reader @p, @q
+
+      # Returns a new instance of the Bernoulli distribution
+      #
+      # @param [Float] prob_success The probability of success
+      def initialize(prob_success = 0.5)
+        super(prob_success)
+        self
+      end
+    end
+  end
+end

data/lib/statistical/distribution/exponential.rb

@@ -0,0 +1,85 @@
+require 'statistical/helpers'
+
+module Statistical
+  module Distribution
+    # Abstraction of common statistical properties of the exponential
+    #   distribution
+    #
+    # @author Vaibhav Yenamandra
+    # @attr_reader [Numeric] rate Rate parameter controlling the
+    #   exponential distribution. Same as `λ` in the canonical version
+    class Exponential
+      attr_reader :rate, :support
+
+      # Returns a new `Statistical::Distribution::Uniform` instance
+      #
+      # @param [Numeric] rate Rate parameter of the exponential distribution.
+      #   Same as `λ` in the canonical version
+      # @return `Statistical::Distribution::Exponential` instance
+      def initialize(rate = 1)
+        @rate = rate
+        @support = Domain[0.0, Float::INFINITY, :right_open]
+      end
+
+      # Returns value of probability density function at a point.
+      #
+      # @param [Numeric] x A real valued point
+      # @return [Float] Probility density function evaluated at x
+      def pdf(x)
+        return [@rate * Math.exp(-@rate * x), 0.0, 0.0][@support <=> x]
+      end
+
+      # Returns value of cumulative density function at a point.
+      #
+      # @param [Numeric] x A real valued point
+      # @return [Float] Probability mass function evaluated at x
+      def cdf(x)
+        return [1 - Math.exp(-@rate * x), 1.0, 0.0][@support <=> x]
+      end
+
+      # Returns value of inverse CDF for a given probability
+      #
+      # @see #p_value
+      #
+      # @param [Float] p a value within [0, 1]
+      # @return Inverse CDF for valid p
+      # @raise [RangeError] if p > 1 or p < 0
+      def quantile(p)
+        raise RangeError, "`p` must be in [0, 1], found: #{p}" if p < 0 || p > 1
+        return Math.log(1 - p) / -@rate
+      end
+
+      # Returns the mean value for the calling instance. Calculated mean, and
+      #   not inferred from simulations
+      #
+      # @return Mean of the distribution
+      def mean
+        return 1.0 / @rate
+      end
+
+      # Returns the expected value of variance for the calling instance.
+      #
+      # @return Variance of the distribution
+      def variance
+        return (1.0 / @rate)**2
+      end
+
+      # Compares two distribution instances and returns a boolean outcome
+      #   Available publicly as #==
+      #
+      # @private
+      #
+      # @param other A distribution object (preferred)
+      # @return [Boolean] true if-and-only-if two instances are of the same
+      #   class and have the same parameters.
+      def eql?(other)
+        return other.is_a?(self.class) && @rate == other.rate
+      end
+
+      alias :== :eql?
+      alias :p_value :quantile
+
+      private :eql?
+    end
+  end
+end

data/lib/statistical/distribution/laplace.rb

@@ -0,0 +1,101 @@
+require 'statistical/helpers'
+
+module Statistical
+  module Distribution
+    # Say something useful about this class.
+    #
+    # @note Any caveats you want to talk about go here...
+    #
+    # @author Vaibhav Yenamandra
+    # @attr_reader [Numeric] scale Scale parameter of the Laplace distribution.
+    # @attr_reader [Numeric] location Location parameter to determine where the
+    #   distribution is centered / where the mean lies at
+    class Laplace
+      attr_reader :scale, :location, :support
+
+      # Returns a new instance of the Laplace distribution; also known as
+      #   the two-sided exponential distribution
+      #
+      # @param [Numeric] scale Scale parameter of the Laplace distribution.
+      # @param [Numeric] location Location parameter to determine where the
+      #   distribution is centered / where the mean lies at
+      # @return `Statistical::Distribution::Laplace` instance
+      def initialize(location = 0, scale = 1)
+        @scale = scale
+        @location = location
+        @support = Domain[-Float::INFINITY, Float::INFINITY, :full_open]
+        self
+      end
+
+      # Returns value of probability density function at a point.
+      #
+      # @param [Numeric] x A real valued point
+      # @return [Float] Probility density function evaluated at x
+      def pdf(x)
+        x_ = (x - @location).abs.fdiv(@scale)
+        return Math.exp(- x_).fdiv(2 * @scale)
+      end
+
+      # Returns value of cumulative density function at a point.
+      #
+      # @param [Numeric] x A real valued point
+      # @return [Float] Cumulative density function evaluated at x
+      def cdf(x)
+        return [0.5,
+                1.0 - 0.5 * Math.exp((@location - x).fdiv(@scale)),
+                0.5 * Math.exp((x - @location).fdiv(@scale))
+        ][x <=> @location]
+      end
+
+      # Returns value of inverse CDF for a given probability
+      #
+      # @see #p_value
+      #
+      # @param [Numeric] p a value within [0, 1]
+      # @return Inverse CDF for valid p
+      # @raise [RangeError] if p > 1 or p < 0
+      def quantile(p)
+        raise RangeError, "`p` must be in [0, 1], found: #{p}" if p < 0 || p > 1
+
+        return [@location,
+                @location - @scale * Math.log(2 * (1.0 - p)),
+                @scale * Math.log(2 * p) + @location
+        ][p <=> 0.5]
+      end
+
+      # Returns the expected mean value for the calling instance.
+      #
+      # @return Mean of the distribution
+      def mean
+        return @location
+      end
+
+      # Returns the expected value of variance for the calling instance.
+      #
+      # @return Variance of the distribution
+      def variance
+        return 2 * @scale * @scale
+      end
+
+      # Compares two distribution instances and returns a boolean outcome
+      #   Available publicly as #==
+      #
+      # @private
+      #
+      # @param other A distribution object (preferred)
+      # @return [Boolean] true if-and-only-if two instances are of the same
+      #   class and have the same parameters.
+      def eql?(other)
+        return false unless other.is_a?(self.class) &&
+                            other.scale == @scale &&
+                            other.location == @location
+        return true
+      end
+
+      alias :== :eql?
+      alias :p_value :quantile
+
+      private :eql?
+    end
+  end
+end